# 05 · 代码片段库 本分册是**可直接复制**的片段库。每个片段包含：一句话说明 → 落点文件 → 完整代码 → 注意事项。 ## 阅读约定 - **参考实现**（片段 1–10）：逐字来自参考主题 `xiaoying-mailbox`，类名 / 函数名 / 常量名已与源码核对一致，可直接照抄。 - **推荐实现（新增）**（片段 11–15）：参考主题中**没有**这些能力，以下给出与现有风格一致的推荐写法（只用 daisyUI / Tailwind 类名，不写自定义 CSS）。 - 所有片段默认放在**主题根目录**，代码中的路径均为主题内相对路径。 - 函数与全局量统一 `xy_mbx_` 前缀；文案为中文直出（与参考实现一致，不引入 i18n 包装）。 - 片段中出现的 Tailwind / daisyUI 类名必须存在于 `assets/css/tailwind.css`；新增或改动类名后必须重新执行 `npm run build:css`。 --- ## 1. 面包屑（文章页） **说明**：输出「首页 › 文章 › 首个分类 › 当前标题」四级面包屑，未设置文章列表页时自动省略「文章」这一层。 **落点文件**：`single.php`（文章标题之前）。 ```php ``` **注意事项** - 用 `get_the_category()` 取数组，只取 `[0]`；直接在循环外调用 `get_the_category_list()` 会输出全部分类，不适合面包屑。 - `aria-current="page"` 是 daisyUI `breadcrumbs` 标记当前项的约定，同时满足无障碍要求。 - 层级判断全部基于函数返回值，不要写死「一定有文章页」——后台「设置 → 阅读」未指定文章页时 `page_for_posts` 为 0。 --- ## 2. 列表卡片骨架 **说明**：`home.php` / `archive.php` / `search.php` / `index.php` 共用的响应式网格卡片（封面或占位块、分类徽标、日期、评论数徽标、两行截断标题、摘要、阅读全文）。 **落点文件**：`template-parts/post-list.php`。 ```php
'h-full w-full object-cover' ) ); ?>
暂无封面
name ); ?>

阅读全文 →
``` **注意事项** - 卡片标题用 `h2`（页面 `h1` 已被列表页标题占用），保证每页只有一个 `h1`。 - 无图占位块与封面图都用 `aspect-[16/9]` 固定比例，卡片才能等高；封面的 `h-full w-full object-cover` 负责裁切不变形。 - 标题用 `line-clamp-2` 截两行；固定行数可避免高度参差。超长无空格串由 `theme.css` 的 `overflow-wrap: anywhere` 兜底。 - 摘要用 `wp_trim_words( get_the_excerpt(), 24, '…' )` 统一长度，不要直接输出 `the_excerpt()`。 - 本片段**依赖调用方已处于主循环上下文**（`have_posts()` / `the_post()` 可用），页面模板负责 `get_header()` 与容器。 --- ## 3. 列表分页与空态 **说明**：有文章时输出分页；无文章时给出中文空态，搜索页空态带上搜索词。 **落点文件**：`template-parts/post-list.php`（接在片段 2 的卡片网格之后）。 ```php '上一页', 'next_text' => '下一页', 'mid_size' => 1, ) ); ?>

暂无内容。

``` **注意事项** - 分页外观来自 `assets/css/theme.css` 里的 `.pagination .nav-links` 与 `.page-numbers` 规则（对齐 daisyUI 按钮观感），不需要在模板里额外加类。 - 空态分支顺序固定：先 `is_search()`，再兜底「暂无内容」，否则搜索页会落到通用文案上。 - 搜索词必须 `esc_html()` 后再拼接输出。 - 分页依赖查询里的 `found_posts`；自定义查询若设了 `no_found_rows => true`（如片段 10 的相关文章）就**不要**再对它输出分页。 --- ## 4. 评论列表容器 **说明**：评论区外壳（`id="comments"`）、评论列表、嵌套列表排版、评论分页、空态与表单入口。 **落点文件**：`comments.php`（由 `single.php` 的 `comments_template()` 调用）。 ```php

评论 0 ) : ?>

还没有评论，来说两句吧。以下为本文的引用通告：

    'xy_mbx_comment_item', 'style' => 'ol', 'format' => 'html5', 'short_ping' => true, ) ); ?>
'上一页', 'next_text' => '下一页', 'mid_size' => 1, ) ); ?>

还没有评论，来说两句吧。

评论功能已关闭。

``` **注意事项** - 嵌套层级由 WordPress 输出为 `ol.children`，这里**用任意变体类名排版**（`[&_ol.children]:border-l` 等），因此不需要写任何自定义 CSS；改这些类名后要重新构建样式。 - `'format' => 'html5'` 与 `add_theme_support('html5', ['comment-list','comment-form'])` 配套，缺一不可。 - 空态有两种：真的一条评论都没有 →「还没有评论，来说两句吧。」；只有引用通告 → 追加一句「以下为本文的引用通告：」，因为 `have_comments()` 为真但真实评论数为 0。 - 评论数用 `xy_mbx_real_comment_count()`（片段 7），不要用 `get_comments_number()`，否则引用通告会让数字虚高。 - 评论区只在文章详情页输出；页面模板不要调用 `comments_template()`。 --- ## 5. 评论项渲染回调（含占位头像与引用通告分支） **说明**：`wp_list_comments()` 的单条评论回调；含彩色首字占位头像、待审核徽标、回复链接，以及引用通告的紧凑行分支。 **落点文件**：`inc/comments.php`。 ```php 由 Walker_Comment 自动补全，本回调不要输出。 * * @param WP_Comment $comment 评论对象。 * @param array $args wp_list_comments() 参数。 * @param int $depth 当前嵌套层级。 */ function xy_mbx_comment_item( $comment, $args, $depth ) { // 引用通告（pingback / trackback）不是读者评论：用紧凑行展示「引用通告 + 来源标题」， // 不显示头像与「回复」入口，也不参与评论数统计。 if ( in_array( (string) $comment->comment_type, array( 'pingback', 'trackback' ), true ) ) { ?>
  • >
    引用通告
  • >
    comment_approved ) : ?> 待审核
    $depth, 'max_depth' => isset( $args['max_depth'] ) ? $args['max_depth'] : 5, 'reply_text' => '回复', 'before' => '
    ', 'after' => '
    ', ) ) ); ?>
    ` 上，WordPress 靠它输出层级与状态类；`
    • ` 由 walker 自动补，回调里不要写。 - `xy-comment-text` 是给评论正文预留的钩子类名（参考实现中未在 `theme.css` 定义规则），不要指望它有样式。 --- ## 6. 评论表单字段与按钮的 daisyUI 样式 **说明**：通过 `comment_form_defaults` 过滤器把表单字段、按钮换成 daisyUI 输入框 / 按钮，并回填已留言访客的昵称、邮箱、网址。 **落点文件**：`inc/comments.php`。 ```php '; $defaults['title_reply_after'] = ''; $defaults['comment_notes_before'] = '

    邮箱不会公开显示，带 * 的为必填项。

    '; $defaults['class_form'] = 'mt-3 space-y-3'; $defaults['class_submit'] = 'btn btn-primary btn-sm'; $defaults['comment_field'] = '' . ''; // 已登录或曾留言过的访客，回填其昵称/邮箱/网址。 $xy_commenter = wp_get_current_commenter(); $defaults['fields'] = array( 'author' => '' . '', 'email' => '' . '', 'url' => '' . '', ); return $defaults; } add_filter( 'comment_form_defaults', 'xy_mbx_comment_form_defaults' ); ``` **注意事项** - 表单控件 id / name（`author`、`email`、`url`、`comment`）不能改，WordPress 靠它们接收数据。 - `title_reply_before` / `title_reply_after` 用于给「发表评论」标题挂类名；h3 层级满足「每页一个 `h1`」的约定。 - 输入框用 `input w-full` / `textarea w-full`（不带 `input-bordered` 等旧版类，daisyUI 5 已内置边框）；提交按钮 `btn btn-primary btn-sm`。 - 不要在这里 `echo` 表单，`comment_form()` 才是唯一入口。 --- ## 7. 评论数徽标 **说明**：只统计真实评论（排除引用通告），仅在数量大于 0 时输出；可选渲染成跳 `#comments` 的链接。 **落点文件**：`inc/comments.php`；调用点 `single.php`（传 `true`）与 `template-parts/post-list.php`（默认）。 ```php $xy_post_id, 'type' => 'comment', 'status' => 'approve', 'count' => true, ) ); } /** * 输出评论数徽标（仅在真实评论数大于 0 时输出）。 * * @param int|null $post_id 文章 ID，默认当前文章。 * @param bool $link_to_comments 是否渲染为跳到评论区的链接（详情页用）。 */ function xy_mbx_comment_count_badge( $post_id = null, $link_to_comments = false ) { $xy_count = xy_mbx_real_comment_count( $post_id ); if ( $xy_count < 1 ) { return; } $xy_label = esc_html( number_format_i18n( $xy_count ) ); $xy_icon = ''; if ( $link_to_comments ) { echo '' . $xy_icon . ' ' . $xy_label . ''; // phpcs:ignore WordPress.Security.EscapeOutput -- 图标为本函数内固定字符串，文字已转义。 return; } echo '' . $xy_icon . ' ' . $xy_label . ''; // phpcs:ignore WordPress.Security.EscapeOutput -- 同上。 } ``` **注意事项** - 数量为 0 时函数**直接返回、不输出任何内容**，因此调用处不需要写 `if`。 - 首页 / 归档列表的卡片调用 `xy_mbx_comment_count_badge()`（不传参，走当前文章）；文章详情页调用 `xy_mbx_comment_count_badge( null, true )` 输出跳 `#comments` 的链接。 - 图标是函数内固定字符串（非用户输入），文字已 `esc_html()`，故用 `phpcs:ignore` 标注而非二次转义。 - 数字用 `number_format_i18n()` 输出，跟随站点数字格式。 --- ## 8. 侧栏容器 + sticky 写法 **说明**：详情页右栏容器与内部 sticky 滚动容器；后续新增侧栏模块只需往里追加 `get_template_part()`。 **落点文件**：`single.php`（两栏布局的右栏）。 ```php
    ``` **注意事项** - 外层 `lg:grid-cols-[minmax(0,1fr)_20rem]` 里 `minmax(0,1fr)` 的 `min-0` 必须保留，否则正文里的长代码块 / 宽表格会把左栏顶宽、右栏被挤扁；左栏容器同时要带 `min-w-0`。 - 右栏 `lg:row-span-2` 跨「正文行 + 评论区行」，`lg:row-start-1` 从第一行开始；评论区必须是左栏第 2 行（`lg:col-start-1 lg:row-start-2`）才能形成两栏错位布局。 - 窄屏顺序由 DOM 决定：正文 → 侧栏模块 → 评论区，无需额外 `order` 类。 - sticky 容器带 `lg:max-h-[calc(100vh-3rem)] lg:overflow-y-auto`：侧栏模块多于视口高度时自身滚动，不会把 sticky 拉坏。 - 模块间距由容器的 `space-y-4` 统一负责，模块自身**不要**再加 `mt-*`。 --- ## 9. 侧栏卡片外壳（品牌渐变描边） **说明**：1px 品牌渐变描边（外层 `p-px` + 内层圆角减 1px）+ 标题渐变竖条，是侧栏所有模块的统一外观。 **落点文件**：`template-parts/related-posts.php`（可复用到任意侧栏模块）。 ```php

    相关文章

    ``` **注意事项** - 描边靠「外层渐变背景 + `p-px` + 内层不透明卡片」实现：内层必须是 `bg-base-100`（不透），否则渐变会透上来。 - 内层圆角写 `rounded-[calc(var(--radius-box)-1px)]`：比外层 `rounded-box` 少 1px，描边在四角才均匀（daisyUI 主题变量，勿写死具体尺寸）。 - 阴影只加在外层（`shadow-sm`），内层不加，否则边缘会出现双层阴影。 - 每个模块的标题 `id` 不能重复（如 `xy-related-heading`），并用 `aria-labelledby` 关联到 `
    `。 - 标题竖条是纯装饰，必须带 `aria-hidden="true"`；标题字号在侧栏统一降到 `text-base`。 --- ## 10. 相关文章取数（同分类优先 + 最新补齐） **说明**：详情页侧栏内链模块，同分类优先、不足用最新文章补齐、始终排除当前文章，取不到任何结果时整块不输出。 **落点文件**：`template-parts/related-posts.php`。 ```php $xy_related_category_ids, 'posts_per_page' => $xy_related_limit, 'post__not_in' => array( get_the_ID() ), 'no_found_rows' => true, 'ignore_sticky_posts' => true, ) ); $xy_related_posts = $xy_related_category_query->posts; } // 2. 补齐：排除当前文章与已收录文章，用最新文章补足。 $xy_related_exclude_ids = array_merge( array( get_the_ID() ), wp_list_pluck( $xy_related_posts, 'ID' ) ); $xy_related_missing = $xy_related_limit - count( $xy_related_posts ); if ( $xy_related_missing > 0 ) { $xy_related_fill_query = new WP_Query( array( 'posts_per_page' => $xy_related_missing, 'post__not_in' => $xy_related_exclude_ids, 'no_found_rows' => true, 'ignore_sticky_posts' => true, ) ); $xy_related_posts = array_merge( $xy_related_posts, $xy_related_fill_query->posts ); } // 无相关文章时整块不输出。 if ( empty( $xy_related_posts ) ) { return; } ?>

    相关文章

    true`（不需要总数、省一次 `SQL_CALC_FOUND_ROWS`）与 `ignore_sticky_posts => true`（置顶文章不应霸占侧栏）。 - `setup_postdata()` 后必须把 `$GLOBALS['post']` 一起换掉（仅调用 `setup_postdata()` 不会更新全局 `$post`），结尾必须 `wp_reset_postdata()`，否则会污染调用方的主循环。 - 缩略图用 `medium` 尺寸 + `loading="lazy"`；无缩略图时 `
    ` 留作灰色占位块（`bg-base-200` + `ring-1`），保持每行高度一致。 - 侧栏宽度只有 20rem，条目用「缩略图 + 标题 + 日期」两列结构，标题 `line-clamp-2` 截两行。 - `if ( empty( $xy_related_posts ) ) { return; }` 保证站点文章不足时整块不输出，不留空卡片。 --- ## 11. 图集与灯箱【推荐实现（新增）】 **说明**：接管 WordPress 图集输出，改成「等宽方格缩略图 + daisyUI 锚点灯箱」；锚点式 modal 由 daisyUI 的 `.modal` + `:target` 支持，**不需要 JS，也不需要自定义 CSS**。 **落点文件**：`inc/gallery.php`（在 `functions.php` 里 `require_once` 加载）。 ```php '', 'size' => 'medium', ), $attr, 'gallery' ); $ids = array_filter( array_map( 'absint', explode( ',', (string) $attr['ids'] ) ) ); // 未指定 ids 的图集（按当前文章附件自动收集）沿用 WordPress 默认输出。 if ( empty( $ids ) ) { return $output; } $grid = '
    '; $modals = ''; foreach ( $ids as $attachment_id ) { $thumb = wp_get_attachment_image( $attachment_id, $attr['size'], false, array( 'class' => 'aspect-square w-full rounded-box object-cover', 'loading' => 'lazy' ) ); if ( '' === $thumb ) { continue; } $modal_id = 'xy-gallery-' . (int) $instance . '-' . (int) $attachment_id; $full_url = (string) wp_get_attachment_image_url( $attachment_id, 'large' ); $alt = (string) get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ); // 缩略图指向弹窗锚点；关闭用 （daisyUI 锚点 modal 的标准用法）。 $grid .= '' . $thumb . ''; $modals .= ''; } return $grid . '
    ' . $modals; } add_filter( 'post_gallery', 'xy_mbx_gallery_lightbox', 10, 3 ); ``` **最小替代方案（不接管输出）**：若只想要网格排版、放大沿用 WordPress 默认的「点击进附件页」，则不加过滤器，只给正文容器补任意变体类名： ```php
    ``` **注意事项** - 只用 `[gallery ids="1,2,3"]` 形式接管；**未写 `ids` 的图集沿用 WordPress 默认输出**，避免两种渲染路径并存导致行为不一致（要接管自动收集，自行用 `get_children()` 取当前文章附件）。 - 弹窗用 `' . '
    '; } ``` **注意事项** - 站外视频**默认优先**（省带宽与 CDN 成本）；自托管只留给短片或需要防盗链的场景，且视频文件不要进主题目录，放媒体库或对象存储。 - 响应式靠 `aspect-video` 容器（16:9）+ `h-full w-full`，**不要**给 iframe 写死 `width` / `height` 属性，否则窄屏溢出。 - `preload="metadata"` 只预取元信息，避免首屏把整个视频文件拖下来；`playsinline` 让 iOS 不强制全屏。 - 时长 / 分辨率建议存成文章自定义字段（`inc/meta.php`），列表卡片上单独展示，不要塞进标题文字里。 - 输出一律 `esc_url()` / `esc_attr()`；`