企业官网建设流程全解析

WordPress Gutenberg 评论标题块 core/comments-title 完全指南：动态渲染、属性配置与源码实现解析

【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg

本篇指南围绕 Gutenberg（WordPress 块编辑器）中负责显示评论标题的core/comments-title块展开，深入讲解其在当前仓库中的块元数据（block.json）、服务端动态渲染（index.php）与编辑器端编辑体验（edit.jsx）三部分实现。读完本文，你将掌握该块的属性配置、样式支持范围、上下文数据来源，以及它在主题评论模板中的正确使用方式与版本迁移机制。

块概览：一个带评论数量的动态标题

core/comments-title是 Gutenberg 内置的动态块（Dynamic Block），其作用是在文章评论区域顶部渲染一个"标题 + 评论数量"的文本，例如"3 responses to「我的文章标题」"。它的核心元数据定义在 block.json，基本信息如下：

该块是一个典型的动态块：它不会把 HTML 写入文章内容，而是以块注释（block comment）形式存于 post content 中，渲染时由 PHP 在服务端实时生成。它必须嵌套在core/comments块内部——在 block.json 中通过"ancestor": [ "core/comments" ]声明了这一限制，编辑器会阻止用户把它放到评论容器之外。这一点从 comments 块的编辑模板 也能得到印证：core/comments块插入时的默认模板第一个子块就是core/comments-title，其后紧跟core/comment-template。

属性（Attributes）详解

该块的四个属性全部定义在 block.json，由attributes属性声明，编辑器据此完成类型校验与默认值填充：

其中level直接决定渲染出的标签名。在 index.php 的服务端逻辑中，渲染函数先默认$tag_name = 'h2'，一旦检测到level属性就拼接为'h' . $attributes['level']，最终输出<h2>到<h6>中的对应标签。编辑器端 edit.jsx 同样通过'h' + level计算预览用的 TagName，保证前后端渲染层级一致。

样式支持（Supports）范围

该块的样式支持配置同样完整定义在 block.json。相比 README 自动生成的摘要，源码中还包含更多细节：

• anchor：true，允许设置锚点 ID；
• align：true，允许对齐（左/中/右/宽幅/全宽）；
• html：false，禁止用户编辑原始 HTML（动态块常规约束）；
• __experimentalBorder：radius、color、width、style四项全部开启（README 摘要未列出该项，但 block.json 明确支持边框）；
• color：gradients: true，且默认控制项（__experimentalDefaultControls）开启background与text；
• spacing：margin: true、padding: true；
• typography：fontSize、lineHeight、textAlign，以及实验性的__experimentalFontFamily、__experimentalFontWeight、__experimentalFontStyle、__experimentalTextTransform、__experimentalTextDecoration、__experimentalLetterSpacing，默认控制项包含字号与字族等；
• interactivity：clientNavigation: true，支持客户端导航（前台无刷新跳转场景）。

正是由于textAlign同时存在于 typography 支持与独立对齐支持中，历史上曾产生过属性冗余的问题（见下文"版本迁移"），这也是 deprecated 逻辑存在的直接原因。

上下文（Context）数据来源

该块依赖两个外部上下文，声明在 block.json 的usesContext中：

• postId：当前文章 ID；
• postType：当前文章类型。

编辑器端 edit.jsx 通过const { postId, postType } = context;接收它们，并用useEntityProp( 'postType', postType, 'title', postId )读取当前文章标题用于占位预览。当在站点编辑器（Site Editor）中使用时postId为undefined，此时占位标题退化为固定的"Post Title"文案（见 edit.jsx）。

服务端渲染：标题文案的完整生成逻辑

该块渲染的核心是 index.php 中的render_block_core_comments_title()函数。它由register_block_core_comments_title()（同一文件 L91-L98）通过register_block_type_from_metadata( __DIR__ . '/comments-title', ... )注册，并挂载在init钩子上。其执行流程如下：

1. 密码保护文章直接返回：若post_password_required()为真，不渲染任何内容；
2. 计算文本对齐类名：若存在textAlign属性，生成has-text-align-{value}类名并合入块包裹属性（get_block_wrapper_attributes）；
3. 读取数据：get_comments_number()获取评论总数，get_the_title()获取文章标题；
4. 确定标签名：根据level属性确定h2~h6；
5. 零评论短路：若评论数为'0'，直接return——没有评论时不输出标题，这是主题开发者需要特别注意的行为；
6. 按两个开关组合标题文案，完整文案矩阵如下（均使用 i18n 翻译函数）：

文案中的数量使用number_format_i18n()做本地化数字格式化（见 index.php），复数形式通过_n()选择；

7. 输出结构：最终渲染为<{tag} id="comments" {wrapper_attributes}>{title}</{tag}>（index.php）。注意固定输出id="comments"，这一 ID 供评论跳转锚点使用，与块自身的anchor支持是两个独立机制。

编辑器体验：工具栏、设置面板与实时评论数

在编辑器端，edit.jsx 提供了完整的编辑 UI：

• 工具栏（BlockControls）：内置HeadingLevelDropdown下拉（edit.jsx），可直接切换标题级别（h2~h6），选项由levelOptions属性控制；
• 设置面板（InspectorControls）：使用ToolsPanel提供两个开关项——Show post title（显示文章标题）与Show comments count（显示评论数量）（edit.jsx），各自对应showPostTitle、showCommentsCount属性，重置按钮会把两者恢复为true；
• 实时评论数获取：编辑器会尽力渲染与前台一致的占位文案。在文章编辑器中，通过apiFetch对/wp/v2/comments?post={postId}&_fields=id发起HEAD请求，从响应头X-WP-Total读取评论总数（edit.jsx），并借助闭包变量currentPostId丢弃过期请求的结果；在站点编辑器中则利用块编辑器设置里的__experimentalDiscussionSettings（threadCommentsDepth、threadComments、commentsPerPage、pageComments），按"嵌套评论数 + 顶级评论数"的规则估算占位数量，并与comment-template编辑占位保持一致（edit.jsx）。

预览占位文案的拼接逻辑（edit.jsx）与 PHP 端文案矩阵完全对齐，保证所见即所得。

块标记（Block Markup）与存储格式

由于是动态块，前台 HTML 由服务端生成，文章内容中只保存如下形式的块注释（来自 README 的官方示例）：

<!-- wp:comments-title {"level":4,"style":{"spacing":{"padding":{"top":"6px","right":"6px","bottom":"6px","left":"6px"}},"border":{"width":"3px","radius":"100px"}},"borderColor":"vivid-red","backgroundColor":"primary","textColor":"background","fontSize":"large"} /-->

示例同时展示了level、style.spacing、borderColor、backgroundColor、textColor、fontSize等属性的序列化形式，这些正是上文中supports体系（边框、间距、颜色、排版）在前端操作后在保存内容中的呈现结果。

版本迁移与向后兼容

deprecated.js 中维护了两个历史版本，保证老内容平滑升级：

• v1：包含已废弃的singleCommentLabel、multipleCommentsLabel两个字符串属性（自定义单数/复数文案，现已移除），迁移逻辑删除这两个属性；
• v2：包含独立的textAlign字符串属性。由于textAlign现在由 typography 支持接管，旧数据通过 migrate-text-align.js 迁移：若检测到textAlign属性，将其写入style.typography.textAlign，同时剥离顶层textAlign；若className中存在has-text-align-(left|center|right)类名（旧编辑器保存的对齐类），isEligible也会判定为需要迁移。

两个版本的save均为() => null，与动态块的"不保存 HTML"约束一致。迁移完成后，新版本（v3，即当前 block.json 定义）不再识别这些历史属性。

在主题中的实际用法

core/comments-title是评论流程块组（core/comments）的一员，通常与core/comment-template、core/comments-pagination等块配合，构成完整的评论区块。主题开发者在使用时需要注意：

1. 必须嵌套在core/comments内，否则编辑器会拒绝或报错；
2. 无评论时不输出任何标题，如需在无评论时仍显示引导文案，应在评论容器外层自行添加条件逻辑；
3. 标题标签层级由level属性控制（默认h2），为保证文档大纲合理，通常与页面标题层级衔接（如文章正文用h2、评论标题用h3）；
4. 标题的固定id="comments"可作为评论区域的锚点，供"跳转到评论"链接使用；
5. 若希望自定义文案，可注册该块的render_callback变体或改用core/comments模板中的替换块，本仓库内未提供额外钩子。

如需进一步深入，可继续阅读同目录下的 block.json、index.php、edit.jsx 与 deprecated.js，并对照 comments 块的编辑模板 观察其在默认评论模板中的位置。

【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg