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本篇指南围绕 GutenbergWordPress 块编辑器中负责显示评论标题的core/comments-title块展开深入讲解其在当前仓库中的块元数据block.json、服务端动态渲染index.php与编辑器端编辑体验edit.jsx三部分实现。读完本文你将掌握该块的属性配置、样式支持范围、上下文数据来源以及它在主题评论模板中的正确使用方式与版本迁移机制。块概览一个带评论数量的动态标题core/comments-title是 Gutenberg 内置的动态块Dynamic Block其作用是在文章评论区域顶部渲染一个标题 评论数量的文本例如3 responses to「我的文章标题」。它的核心元数据定义在 block.json基本信息如下项目值块名称Namecore/comments-title分类Categorytheme主题类块API 版本3块类型动态Dynamic服务端渲染文本域textdomaindefault随核心翻译该块是一个典型的动态块它不会把 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属性声明编辑器据此完成类型校验与默认值填充属性类型默认值说明showPostTitlebooleantrue是否在标题中显示文章标题showCommentsCountbooleantrue是否在标题中显示评论数量levelnumber2标题标签级别渲染为h2~h6levelOptionsarray—可选的标题级别列表用于工具栏下拉的选项集合无默认值其中level直接决定渲染出的标签名。在 index.php 的服务端逻辑中渲染函数先默认$tag_name h2一旦检测到level属性就拼接为h . $attributes[level]最终输出h2到h6中的对应标签。编辑器端 edit.jsx 同样通过h level计算预览用的 TagName保证前后端渲染层级一致。样式支持Supports范围该块的样式支持配置同样完整定义在 block.json。相比 README 自动生成的摘要源码中还包含更多细节anchortrue允许设置锚点 IDaligntrue允许对齐左/中/右/宽幅/全宽htmlfalse禁止用户编辑原始 HTML动态块常规约束__experimentalBorderradius、color、width、style四项全部开启README 摘要未列出该项但 block.json 明确支持边框colorgradients: true且默认控制项__experimentalDefaultControls开启background与textspacingmargin: true、padding: truetypographyfontSize、lineHeight、textAlign以及实验性的__experimentalFontFamily、__experimentalFontWeight、__experimentalFontStyle、__experimentalTextTransform、__experimentalTextDecoration、__experimentalLetterSpacing默认控制项包含字号与字族等interactivityclientNavigation: true支持客户端导航前台无刷新跳转场景。正是由于textAlign同时存在于 typography 支持与独立对齐支持中历史上曾产生过属性冗余的问题见下文版本迁移这也是 deprecated 逻辑存在的直接原因。上下文Context数据来源该块依赖两个外部上下文声明在 block.json 的usesContext中postId当前文章 IDpostType当前文章类型。编辑器端 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钩子上。其执行流程如下密码保护文章直接返回若post_password_required()为真不渲染任何内容计算文本对齐类名若存在textAlign属性生成has-text-align-{value}类名并合入块包裹属性get_block_wrapper_attributes读取数据get_comments_number()获取评论总数get_the_title()获取文章标题确定标签名根据level属性确定h2~h6零评论短路若评论数为0直接return——没有评论时不输出标题这是主题开发者需要特别注意的行为按两个开关组合标题文案完整文案矩阵如下均使用 i18n 翻译函数showCommentsCountshowPostTitle评论数 1评论数 1开开One response to %s文章标题%1$s responses to %2$s数量 文章标题开关One response%s responses关开Response to %sResponses to %s关关ResponseResponses文案中的数量使用number_format_i18n()做本地化数字格式化见 index.php复数形式通过_n()选择输出结构最终渲染为{tag} idcomments {wrapper_attributes}{title}/{tag}index.php。注意固定输出idcomments这一 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}_fieldsid发起HEAD请求从响应头X-WP-Total读取评论总数edit.jsx并借助闭包变量currentPostId丢弃过期请求的结果在站点编辑器中则利用块编辑器设置里的__experimentalDiscussionSettingsthreadCommentsDepth、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等块配合构成完整的评论区块。主题开发者在使用时需要注意必须嵌套在core/comments内否则编辑器会拒绝或报错无评论时不输出任何标题如需在无评论时仍显示引导文案应在评论容器外层自行添加条件逻辑标题标签层级由level属性控制默认h2为保证文档大纲合理通常与页面标题层级衔接如文章正文用h2、评论标题用h3标题的固定idcomments可作为评论区域的锚点供跳转到评论链接使用若希望自定义文案可注册该块的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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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本篇指南围绕 GutenbergWordPress 块编辑器中负责显示评论标题的core/comments-title块展开深入讲解其在当前仓库中的块元数据block.json、服务端动态渲染index.php与编辑器端编辑体验edit.jsx三部分实现。读完本文你将掌握该块的属性配置、样式支持范围、上下文数据来源以及它在主题评论模板中的正确使用方式与版本迁移机制。块概览一个带评论数量的动态标题core/comments-title是 Gutenberg 内置的动态块Dynamic Block其作用是在文章评论区域顶部渲染一个标题 评论数量的文本例如3 responses to「我的文章标题」。它的核心元数据定义在 block.json基本信息如下项目值块名称Namecore/comments-title分类Categorytheme主题类块API 版本3块类型动态Dynamic服务端渲染文本域textdomaindefault随核心翻译该块是一个典型的动态块它不会把 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属性声明编辑器据此完成类型校验与默认值填充属性类型默认值说明showPostTitlebooleantrue是否在标题中显示文章标题showCommentsCountbooleantrue是否在标题中显示评论数量levelnumber2标题标签级别渲染为h2~h6levelOptionsarray—可选的标题级别列表用于工具栏下拉的选项集合无默认值其中level直接决定渲染出的标签名。在 index.php 的服务端逻辑中渲染函数先默认$tag_name h2一旦检测到level属性就拼接为h . $attributes[level]最终输出h2到h6中的对应标签。编辑器端 edit.jsx 同样通过h level计算预览用的 TagName保证前后端渲染层级一致。样式支持Supports范围该块的样式支持配置同样完整定义在 block.json。相比 README 自动生成的摘要源码中还包含更多细节anchortrue允许设置锚点 IDaligntrue允许对齐左/中/右/宽幅/全宽htmlfalse禁止用户编辑原始 HTML动态块常规约束__experimentalBorderradius、color、width、style四项全部开启README 摘要未列出该项但 block.json 明确支持边框colorgradients: true且默认控制项__experimentalDefaultControls开启background与textspacingmargin: true、padding: truetypographyfontSize、lineHeight、textAlign以及实验性的__experimentalFontFamily、__experimentalFontWeight、__experimentalFontStyle、__experimentalTextTransform、__experimentalTextDecoration、__experimentalLetterSpacing默认控制项包含字号与字族等interactivityclientNavigation: true支持客户端导航前台无刷新跳转场景。正是由于textAlign同时存在于 typography 支持与独立对齐支持中历史上曾产生过属性冗余的问题见下文版本迁移这也是 deprecated 逻辑存在的直接原因。上下文Context数据来源该块依赖两个外部上下文声明在 block.json 的usesContext中postId当前文章 IDpostType当前文章类型。编辑器端 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钩子上。其执行流程如下密码保护文章直接返回若post_password_required()为真不渲染任何内容计算文本对齐类名若存在textAlign属性生成has-text-align-{value}类名并合入块包裹属性get_block_wrapper_attributes读取数据get_comments_number()获取评论总数get_the_title()获取文章标题确定标签名根据level属性确定h2~h6零评论短路若评论数为0直接return——没有评论时不输出标题这是主题开发者需要特别注意的行为按两个开关组合标题文案完整文案矩阵如下均使用 i18n 翻译函数showCommentsCountshowPostTitle评论数 1评论数 1开开One response to %s文章标题%1$s responses to %2$s数量 文章标题开关One response%s responses关开Response to %sResponses to %s关关ResponseResponses文案中的数量使用number_format_i18n()做本地化数字格式化见 index.php复数形式通过_n()选择输出结构最终渲染为{tag} idcomments {wrapper_attributes}{title}/{tag}index.php。注意固定输出idcomments这一 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}_fieldsid发起HEAD请求从响应头X-WP-Total读取评论总数edit.jsx并借助闭包变量currentPostId丢弃过期请求的结果在站点编辑器中则利用块编辑器设置里的__experimentalDiscussionSettingsthreadCommentsDepth、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等块配合构成完整的评论区块。主题开发者在使用时需要注意必须嵌套在core/comments内否则编辑器会拒绝或报错无评论时不输出任何标题如需在无评论时仍显示引导文案应在评论容器外层自行添加条件逻辑标题标签层级由level属性控制默认h2为保证文档大纲合理通常与页面标题层级衔接如文章正文用h2、评论标题用h3标题的固定idcomments可作为评论区域的锚点供跳转到评论链接使用若希望自定义文案可注册该块的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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
