';
$after = isset($args['after_title']) ? $args['after_title'] : '
';
echo $before . esc_html($title) . $after;
}
endif;
if (!function_exists('yang_widget_uid')):
/**
* 生成挂件内 HTML id 的唯一前缀。
*
* 🔴 为什么不能用写死的 id：挂件可以添加多个实例，同一页面上
* 两个「文章聚合」就会产生两套重复 id（HTML 非法，
* aria-labelledby 也只能指到第一个）。
* `$this->id` 由 WP_Widget 分配（形如 `widget_posts-2`），
* 同一请求内唯一；但在单元测试/旧版环境里可能不存在，所以做兜底。
*
* @param object $widget 挂件实例
* @return string 形如 `yang-widget_posts-2`
*/
function yang_widget_uid($widget)
{
$id = '';
if (is_object($widget) && isset($widget->id) && is_string($widget->id) && $widget->id !== '') {
$id = $widget->id;
} elseif (is_object($widget) && isset($widget->id_base) && is_string($widget->id_base) && $widget->id_base !== '') {
$id = $widget->id_base;
} else {
$id = 'widget';
}
return 'yang-' . preg_replace('/[^a-z0-9_-]+/i', '-', $id);
}
endif;
if (!function_exists('yang_widget_open')):
/**
* 挂件外框起始标签。
*
* 侧栏注册的 before_widget 是 ``，其中 %2$s 是
* 挂件类名（classname）。这里故意**不用**它，而是自己拼类名：
* 主题的挂件样式全部写成 `.k-main .sidebar .w-about` 这种以 `w-` 开头的
* 短类名，用 classname 会变成 `widget_widget_about` 之类，样式一条都不生效。
* 保留 `widget` 这个基类（主题里 `.k-main .sidebar .widget` 提供白底与内边距）。
*
* @param string $modifier 形如 'w-about'
* @return string
*/
function yang_widget_class($modifier)
{
return 'widget ' . $modifier;
}
endif;
/* ==========================================================================
* 热度算法（3.2.49）
*
* ── 为什么废弃旧的 most_comm_posts() ──────────────────────────────────
* 旧实现的候选池是「最近 N 天（默认 30）**发布**的文章」：
*
* WHERE post_date BETWEEN '$daysago' AND '$today'
* ORDER BY comment_count DESC LIMIT 6
*
* 对日更站点没问题，对低频更新的站点直接失效。本站实测（2026-10-26）：
* 7 天内发布 0 篇 / 30 天内 1 篇 / 90 天内 1 篇 / 180 天内 6 篇
* 30 天候选池只有 1 篇 ⇒ LIMIT 6 也只能返回 1 条。
* 这就是侧栏「热点」永远只显示一条的真正原因 —— **不是排序错，是池子空**。
*
* 而且「最近 30 天发布」本身就不是「热」的定义：热是累计互动，不是新鲜度。
*
* ── 现在的算法 ────────────────────────────────────────────────────────
* 候选池：全站所有已发布 post（不含 page —— 「留言本」这种页面 views 214 万，
* 它的热度对"最热文章"没有意义；`post_type='post'` 天然挡掉）。
* 打分：三个指标各取 log10 后加权求和
*
* score = 3*log10(views+1) + 5*log10(love+1) + 4*log10(comments+1)
*
* 为什么取 log10：本站 views 中位数 4981、最大 56075（差 11 倍），
* 但 love 最大只有 40、评论最大 93。不取对数的话 views 一个指标就吃掉
* 全部权重，点赞和评论等于没参与。取对数后三者量级被拉平到可比的区间。
*
* 为什么权重是 3 / 5 / 4（不是常见的 1 / 3 / 5）：
* 用通用值实测，前 8 名有 6 篇是 2009 年的老随笔 —— 因为那批文章评论
* 80~93 条，仅评论一项（1.97×5=9.86）就压过 views 最大值的贡献（4.75×1=4.75），
* 结果变成"评论数排行榜"。把 views 权重提到 3 之后三个指标影响力均衡：
* 点赞最高（5）—— 点👍 是比评论更强的认可信号，且本站只有 197 篇有点赞，
* 稀缺性让它更有区分度；评论次之（4）—— 要付出打字成本；浏览最轻（3）。
*
* 实测这组权重的排名（前 8）：Anaconda多用户安装(love=40) · kratos主题发布(love=9,评论37)
* · LaTex上划线(love=19) · 那一年2009 · LaTex字体(love=12) · Windows7自带WMP(评论93)
* → 技术文章与高互动随笔混合出现，2009 年那批也没有被完全埋掉。
*
* ── 有意不加时间衰减 ──────────────────────────────────────────────────
* 「全站历史最热」是累计榜，不是时效榜。Hacker News / Reddit 那套
* gravity 衰减是给「新内容榜」用的，加上去会把老文章压到看不见，
* 那就又回到"只有最近几条"的老问题。要时效榜是另一个功能，不塞在这里。
*
* ── 顺手修掉的两个坑 ──────────────────────────────────────────────────
* ① 旧代码里 `date_default_timezone_set("PRC")` 直接改 **PHP 全局时区**，
* 影响同一请求里之后所有时间函数。已删。
* ② 旧代码把 `$title` 原样插进 `title="..."` 属性，标题里有双引号就会
* 截断属性（甚至注入）。已改用 esc_attr()。
* ====================================================================== */
if (!function_exists('yang_hot_score')):
/**
* 单篇文章的热度分。
*
* @param int $views 浏览数
* @param int $love 点赞数
* @param int $comments 评论数
* @return float
*/
function yang_hot_score($views, $love, $comments)
{
return 3 * log10((int) $views + 1)
+ 5 * log10((int) $love + 1)
+ 4 * log10((int) $comments + 1);
}
endif;
if (!function_exists('yang_hot_posts')):
/**
* 取热度最高的文章。
*
* 为什么在 PHP 里算分、不在 SQL 里 ORDER BY：
* 分值是三项 log 加权和，SQL 里要写三段 LOG10 + COALESCE + 两个
* LEFT JOIN 到 postmeta，可读性极差，而且没法复用 yang_hot_score()
* （测试和产品必须是同一份实现，不能各写一遍）。
* 代价是要把候选行取回来 —— 本站 967 篇 post，一次取 4 个字段
* 内存占用可忽略；如果将来文章上万，再加 LIMIT / 缓存。
* 为防止极端情况，SQL 侧先用 views 粗排取前 N*10（对数排序里
* 真正的高分不会来自 views 极低的文章，这个粗排是安全的）。
*
* @param int $nums 返回条数
* @return array 文章对象数组，每项含 ID/post_title/views/love/comments/score
*/
function yang_hot_posts($nums = 6)
{
global $wpdb;
$nums = max(1, (int) $nums);
// 粗排窗口：给足余量。views 前 200 名以外不可能靠 love/评论翻盘
// （log10 域下，love 满分 1.61×5=8.05，补不回 views 差 1 个数量级的 3 分）。
$pool = max(200, $nums * 20);
$sql = $wpdb->prepare(
"SELECT p.ID, p.post_title, p.post_date, p.comment_count,
COALESCE(CAST(mv.meta_value AS UNSIGNED), 0) AS views,
COALESCE(CAST(ml.meta_value AS UNSIGNED), 0) AS love
FROM {$wpdb->posts} p
LEFT JOIN {$wpdb->postmeta} mv ON mv.post_id = p.ID AND mv.meta_key = 'views'
LEFT JOIN {$wpdb->postmeta} ml ON ml.post_id = p.ID AND ml.meta_key = 'love'
WHERE p.post_status = 'publish'
AND p.post_type = 'post'
ORDER BY views DESC
LIMIT %d",
$pool
);
$rows = $wpdb->get_results($sql);
if (empty($rows)) {
return array();
}
$scored = array();
foreach ($rows as $r) {
$r->views = (int) $r->views;
$r->love = (int) $r->love;
$r->comments = (int) $r->comment_count;
$r->score = yang_hot_score($r->views, $r->love, $r->comments);
$scored[] = $r;
}
usort($scored, function ($a, $b) {
if ($a->score == $b->score) {
// 同分按浏览数兜底，保证顺序稳定（否则每次刷新顺序会跳）
return $b->views <=> $a->views;
}
return $b->score <=> $a->score;
});
return array_slice($scored, 0, $nums);
}
endif;
/**
* 小工具文章聚合 —— 热点文章
*
* ⚠️ 这个函数名和签名保留着，因为 `widget_posts::widget()` 里有一句
* `if (function_exists('most_comm_posts'))` 调用它。留着旧名不破兼容，
* 但内部已经完全换成 yang_hot_posts()。
*
* @param int $days 已废弃。旧实现用它当"最近 N 天发布"的时间窗，
* 那正是只显示一条的根因。保留参数只为不破坏调用签名。
* @param int $nums 返回条数
*/
function most_comm_posts($days = 30, $nums = 6)
{
$posts = yang_hot_posts($nums);
$output = '';
foreach ($posts as $p) {
$output .= ''
. ''
. esc_html(wp_strip_all_tags($p->post_title))
. '';
}
echo $output;
}
class widget_search extends WP_Widget {
public function __construct() {
$widget_ops = array(
'classname' => 'widget_search',
'description' => __( 'A search form for your site.' ),
'customize_selective_refresh' => true,
);
parent::__construct( 'search', _x( 'Search', 'Search widget' ), $widget_ops );
}
public function widget( $args, $instance ) {
/* 🔴 id 必须带实例后缀。
* 原来写死 id="searchform" / id="search" / id="searchsubmit"，
* 挂两个搜索挂件时全撞；主题别处或核心再放一个搜索表单也会撞。 */
$uid = yang_widget_uid($this);
echo '
';
yang_widget_title($args, $instance, '', $this->id_base);
?>
';
}
public function form( $instance ) {
$instance = wp_parse_args( (array) $instance, array( 'title' => '' ) );
$title = $instance['title'];
?>
'' ) );
$instance['title'] = sanitize_text_field( $new_instance['title'] );
return $instance;
}
}
class widget_ad extends WP_Widget
{
public function __construct()
{
/* 名字与 id_base 都走显式实参（2026-10-27，工单 #23）。
*
* ── 原来写法为什么"看着像 bug 但实际没坏" ────────────────────
* 原来写的是 `parent::__construct(false, false, $widget_ops)`，
* 把名字放在 `$widget_ops['name']` 里。两条链路分开看：
*
* ① `$widget->name`：确实等于 false。
* `WP_Widget::__construct` 只有 `$this->name = $name;`，
* 而 `wp_parse_args` 的默认值只补 classname 与
* customize_selective_refresh，**不补 name**。
*
* ② 但后台列表/搜索用的**不是** `$widget->name`，而是
* `$wp_registered_widgets[]['name']`。它是这么来的：
* `_register_one()` → `wp_register_sidebar_widget($id, $this->name, ..., $this->widget_options)`
* → 里面先 `$widget = array('name' => $name, ...)`
* → 紧接着 `$widget = array_merge($widget, $options)` ← 关键
* `$options` 就是 `$this->widget_options`，其中的 `'name'`
* **把前面的 false 覆盖掉了**。所以注册表里名字一直是好的。
*
* 实测（老代码）：`$widget->name` = false，但
* `$wp_registered_widgets['ad-1']['name']` = '图片广告' —— 名字没丢。
* 也就是说「用户找不到挂件」的真实原因是后台走了区块编辑器、
* 没有拖放面板，与本构造函数的实参无关（开关见文件上方）。
*
* ── 那为什么还是改了 ────────────────────────────────────────
* ① 名字配在 `$widget_ops` 里是靠 array_merge **顺带**覆盖生效的，
* 属于隐式行为；显式走第 2 参是 WP 文档写法，读代码的人不用
* 再去追 array_merge 才敢确认名字有没有生效。
* ② `$this->name` 在整个 WP 里有多处直接读（例如区块编辑器的
* 挂件类型接口），值是 false 时行为取决于调用方是否兜底 ——
* 这次侥幸没事，不代表以后没事。
*
* 第 1 参显式写 'ad'：$id_base 决定 option 名（widget_ad）。
* 库里已经有用户的实例，**id_base 一旦变了配置就全丢**。
* 原来传 false 时 WP 靠类名推导出 'ad'（不是 widget_ad，它会把
* wp_/widget_ 前缀剥掉），效果一样 —— 写出来是为了不依赖推导。 */
$widget_ops = array(
'description' => __('显示自定义图片广告的工具', 'kratos'),
);
parent::__construct('ad', __('图片广告', 'kratos'), $widget_ops);
}
public function widget($args, $instance)
{
$subtitle = !empty($instance['subtitle']) ? $instance['subtitle'] : __('广告', 'kratos');
$image = !empty($instance['image']) ? $instance['image'] : '';
$url = !empty($instance['url']) ? $instance['url'] : '';
/* 🔴 原来这三处都是裸拼：
* '
__('文章标签的展示工具', 'kratos'),
);
parent::__construct('tags', __('标签聚合', 'kratos'), $widget_ops);
}
public function widget($args, $instance)
{
$number = !empty($instance['number']) ? $instance['number'] : '8';
$order = !empty($instance['order']) ? $instance['order'] : 'RAND';
$tags = wp_tag_cloud(array(
'unit' => 'px',
'smallest' => 14,
'largest' => 14,
'number' => $number,
'format' => 'flat',
'orderby' => 'count',
'order' => $order,
'echo' => false,
)
);
/* 🔴 标题原来是硬编码的 __('标签聚合')，后台没有输入框也改不了。
* 现在走实例的 title，没设才回落到「标签聚合」——
* 这样老站点的显示**一点不变**，但用户可以改了。 */
echo '';
}
public function update($new_instance, $old_instance)
{
$instance = array();
$instance['title'] = (!empty($new_instance['title'])) ? sanitize_text_field($new_instance['title']) : '';
$instance['number'] = (!empty($new_instance['number'])) ? (int) $new_instance['number'] : 8;
$instance['order'] = (!empty($new_instance['order'])) ? $new_instance['order'] : 'RAND';
return $instance;
}
public function form($instance)
{
global $wpdb;
$title = !empty($instance['title']) ? $instance['title'] : '';
$number = !empty($instance['number']) ? $instance['number'] : '8';
$order = !empty($instance['order']) ? $instance['order'] : 'RAND';
?>
__('展示最热、随机、最新文章的工具', 'kratos'),
);
parent::__construct('posts', __('文章聚合', 'kratos'), $widget_ops);
}
public function widget($args, $instance)
{
$number = !empty($instance['number']) ? (int) $instance['number'] : 6;
if ($number < 1) {
$number = 6;
}
/* 🔴 id 唯一化（原来全是写死的）。
* 老代码把同一套标签页导航写了两份 —— 桌面一份带图标（d-none d-xl-flex）、
* 手机一份不带图标（d-xl-none）—— 于是 nav-tab / nav-new-tab /
* nav-hot-tab / nav-random-tab **四个 id 各出现两次**，HTML 非法；
* `aria-labelledby="nav-new-tab"` 也只能指到第一份。
* 挂两个「文章聚合」实例时撞得更彻底。
*
* 现在只渲染**一份**导航：图标用 CSS 在窄屏隐藏（见 kratos.css 的
* `.w-recommended .tab-icon`）。这样 id 天然唯一，DOM 也少一半。 */
$uid = yang_widget_uid($this);
echo '
' . $subtitle . '
'
* ① $url 没 esc_url —— 后台填个带引号的地址就能截断 href 属性；
* ② img 的 src 值**没有引号** —— 图片 URL 里只要有一个空格，
* 后半截就会被解析成另一个属性（常见于文件名带空格的媒体库图片）；
* ③ $subtitle 没转义 —— 后台填 < 或 & 会破坏结构。
* 下面全部补齐；alt 取副标题，避免读屏软件只念文件名。 */
echo '';
yang_widget_title($args, $instance, '', $this->id_base);
$imgAlt = wp_strip_all_tags($subtitle);
echo ''
. ' . ')
'
. '
';
}
public function update($new_instance, $old_instance)
{
$instance = array();
$instance['title'] = (!empty($new_instance['title'])) ? sanitize_text_field($new_instance['title']) : '';
$instance['subtitle'] = (!empty($new_instance['subtitle'])) ? sanitize_text_field($new_instance['subtitle']) : '';
$instance['image'] = (!empty($new_instance['image'])) ? esc_url_raw($new_instance['image']) : '';
$instance['url'] = (!empty($new_instance['url'])) ? esc_url_raw($new_instance['url']) : '';
return $instance;
}
public function form($instance)
{
$title = !empty($instance['title']) ? $instance['title'] : '';
$subtitle = !empty($instance['subtitle']) ? $instance['subtitle'] : __('广告', 'kratos');
$image = !empty($instance['image']) ? $instance['image'] : '';
$url = !empty($instance['url']) ? $instance['url'] : '';
?>
__('可跳转后台的个人简介展示工具', 'kratos'),
);
parent::__construct('about', __('个人简介', 'kratos'), $widget_ops);
}
/**
* 取挂件实例里的某个值；空则返回回退值。
*
* 🔴 为什么不用 `!empty()` 判定：
* ① 用户在后台把字段清空后，update() 存进去的是空字符串 ''，
* `!empty('')` 为 false —— 这一条两边一致，没问题；
* ② 但 `!empty('0')` 也是 **false**！昵称就叫「0」、简介只写「0」
* 的站点会莫名其妙被回落到主题设置。判空只能判「去掉空白后是空串」。
*
* 3.2.51 起 widget_about 的四个字段都走这里，取值顺序统一为：
* 实例自己的值 → $fallback（主题设置 / 主题自带默认图）
*
* @param array $instance 挂件实例
* @param string $key 字段名
* @param string $fallback 实例里没填时用的值
* @return string
*/
private function pick($instance, $key, $fallback)
{
$v = isset($instance[$key]) ? $instance[$key] : '';
if (!is_string($v)) {
return $fallback;
}
$v = trim($v);
return ($v === '') ? $fallback : $v;
}
public function widget($args, $instance)
{
/* ══════════════════════════════════════════════════════════════
* 3.2.51：这三项原来**只读主题设置**，挂件表单里压根没有对应字段。
*
* 老代码长这样（拿掉注释后的实质）：
* $introduce = kratos_option('a_about', ...);
* $username = kratos_option('a_nickname', ...);
* $avatar = yang_option_image('a_gravatar');
*
* 于是用户点开侧栏「个人简介」，表单里只有「背景图片」一个字段，
* 头像 / 昵称 / 简介**无处可填**，只能跑去「主题设置 → 站长信息」
* 改那份全站共用的。同一侧栏想放两个人的简介就不可能。
*
* 取值顺序（实例优先，留空回落）：
* ① 挂件实例自己填的
* ② 主题设置「站长信息」—— **必须保留**：线上站点正用着
* 「老杨 / 博士，非博学之士…」那一套，改成"空了就空着"
* 会让所有老站点升级后侧栏突然变空白。
* ③ 代码里的兜底文案
* ══════════════════════════════════════════════════════════════ */
$introduce = $this->pick(
$instance,
'introduce',
kratos_option('a_about', __('保持饥渴的专注，追求最佳的品质', 'kratos'))
);
$username = $this->pick(
$instance,
'nickname',
kratos_option('a_nickname', __('Kratos', 'kratos'))
);
$avatar = $this->pick(
$instance,
'avatar',
yang_option_image('a_gravatar')
);
$background = $this->pick(
$instance,
'background',
ASSET_PATH . '/assets/img/about-background.png'
);
/* 🔴 原来写的是 `background:url(' . $background . ') no-repeat ...`
* —— url() 里的地址**没有引号**。只要路径含空格、括号、单引号，
* CSS 解析器就会在那里截断，整条声明作废（背景变白）。
* 媒体库文件名带空格很常见。这里补引号。
*
* 🔴 这里**只拼一次转义**，而且拼完还要整体 esc_attr()。
* 第一版写的是 esc_url($background) 再套 esc_attr($bg) ——
* esc_url() 已经做过 HTML 实体化，esc_attr() 又来一次 ⇒
* `&` 被编成 `&`，CSS 里拿到的是字面量 "amp"，
* 背景图直接 404。测试里那条「URL 完整」判据抓到的就是它。
*
* 正确做法：URL 只做**协议/字符清洗**（esc_url_raw，不入实体），
* url() 内部用双引号包住，最后整个 style 属性交给 esc_attr()
* 统一转义一次。这样 `&` 只会被编成 `&`（正确），
* 浏览器解析回属性值后仍是原始的 `&`。
*
* 🔴 $introduce / $username / $avatar 现在都可能来自**后台表单**
* （用户自己填的），原来是裸 echo。个人简介里写个 < 就把后面的
* 结构吃掉了。简介保留换行（textarea 的自然语义），其余全部转义。 */
$bg = 'background-image:url("' . esc_url_raw($background) . '");'
. 'background-repeat:no-repeat;'
. 'background-position:center center;'
. 'background-size:cover;';
echo '' . esc_html($subtitle) . '
'
. '';
echo '';
yang_widget_title($args, $instance, '', $this->id_base);
echo '
';
}
/**
* 保存实例。
*
* 🔴 不能用 `!empty($new_instance[...])` 判"用户填了没有"：
* `!empty('0')` 是 **false** ⇒ 昵称就叫「0」、简介只写「0」的站点
* 保存后会变成空串、前台回落主题设置，而且**后台看起来像没保存成功**。
* 测试 `_about_test.php` 的「昵称『0』能存下来」抓到的就是这个。
* 统一用「转成字符串、trim 后是不是空串」判断，与 pick() 一致。
*/
public function update($new_instance, $old_instance)
{
$instance = array();
$instance['title'] = $this->clean_text($new_instance, 'title');
$instance['background'] = $this->clean_url($new_instance, 'background');
/* 3.2.51 新增三项。
*
* 🔴 简介是 textarea，**不能**用 sanitize_text_field：
* 那个函数会去掉所有换行，用户分段的简介会挤成一整段。
* 要用 sanitize_textarea_field（WP 4.7+ 才有）。
* 主题没声明最低 WP 版本，所以对更老的版本做个兜底 ——
* 兜底只做「去标签 + 规整换行」，不追求完全等价。
*
* 🔴 头像/背景是 URL，用 esc_url_raw（只清洗协议与字符），
* 不要在这里 esc_url —— 存进库的值必须是可以直接用的原地址。 */
$instance['avatar'] = $this->clean_url($new_instance, 'avatar');
$instance['nickname'] = $this->clean_text($new_instance, 'nickname');
$instance['introduce'] = $this->clean_textarea($new_instance, 'introduce');
return $instance;
}
/**
* 取一个新提交的字段；没提交或只有空白 → 空串。
*
* @param array $src 新提交的实例数组
* @param string $key 字段名
* @return string
*/
private function submitted($src, $key)
{
if (!isset($src[$key])) {
return '';
}
$v = $src[$key];
if (!is_string($v)) {
return '';
}
return trim($v);
}
private function clean_text($src, $key)
{
$v = $this->submitted($src, $key);
return $v === '' ? '' : sanitize_text_field($v);
}
private function clean_url($src, $key)
{
$v = $this->submitted($src, $key);
return $v === '' ? '' : esc_url_raw($v);
}
private function clean_textarea($src, $key)
{
$v = $this->submitted($src, $key);
if ($v === '') {
return '';
}
if (function_exists('sanitize_textarea_field')) {
return sanitize_textarea_field($v);
}
return trim(preg_replace('/\r\n|\r/', "\n", wp_strip_all_tags($v)));
}
public function form($instance)
{
$title = !empty($instance['title']) ? $instance['title'] : '';
/* 输入框里显示**用户自己填的原始值**（没填就是空），
* 预览图显示**前台实际会用的那张**（含回落）。
*
* 两者刻意分开：
* · 输入框若直接显示回落值，用户会以为"我已经填了"，
* 保存后才发现其实存的是主题设置那份；
* · 预览图画的是最终效果，用户一眼能看出现在用的是哪张。 */
$avatarRaw = isset($instance['avatar']) ? trim((string) $instance['avatar']) : '';
$bgRaw = isset($instance['background']) ? trim((string) $instance['background']) : '';
$nicknameRaw = isset($instance['nickname']) ? trim((string) $instance['nickname']) : '';
$introduceRaw = isset($instance['introduce']) ? (string) $instance['introduce'] : '';
$avatarShown = $this->pick($instance, 'avatar', yang_option_image('a_gravatar'));
$bgShown = $this->pick($instance, 'background', ASSET_PATH . '/assets/img/about-background.png');
?>
';
if (current_user_can('manage_options')) {
echo '';
} else {
echo '';
}
echo ' . ')
';
echo '
';
echo '