Gutenberg 核心块深入解析core/term-name分类法术语名称块的渲染机制与配置指南【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读core/term-name是 WordPress Gutenberg 块编辑器中的核心主题类块用于在页面中动态展示当前分类法术语Term的名称例如分类Category、标签Tag等归档页上的术语标题。本文以 packages/block-library/src/term-name/README.md 为骨架结合仓库中的block.json、编辑器端源码与服务端渲染源码系统讲解该块的属性体系、支持能力、上下文数据流、动态渲染原理以及编辑器内的降级与迁移机制帮助你理解并能在主题模板中正确使用与定制这一块。块概览定位与元数据根据 term-name/block.json该块的核心元数据如下名称Namecore/term-name标题TitleTerm Name分类Categorytheme主题类块API 版本apiVersion3描述DescriptionDisplays the name of a taxonomy term.显示分类法术语的名称关键词Keywordsterm title文本域textdomaindefault样式句柄stylewp-block-term-name在 packages/block-library/src/index.jsx 中该块通过registerBlockType体系注册为 Gutenberg 的核心块之一其块类型为动态块Dynamic Block即渲染由服务端完成帖子内容中不保存最终 HTML。属性Attributeslevel、isLink 与 levelOptionsREADME 中通过attributes属性定义于block.json声明了三个属性属性类型默认值说明levelnumber0标题层级0表示使用p段落标签isLinkbooleanfalse是否将术语名称包裹为指向术语归档页的链接levelOptionsarray—编辑器端标题层级下拉框的可用选项三个属性在编辑器端edit.jsx与服务端渲染index.php中的处理完全对应level 的取值语义编辑器端const TagName level 0 ? p :h${level};服务端$tag_name 0 $level ? p : h . (int) $level;——两者保持一致0渲染为段落p16渲染为对应的h1h6。服务端还做了(int)强转防止非数值输入注入到标签名中。isLink 的作用编辑器端在开启该开关时渲染一个href#term-name-pseudo-link且onClick中preventDefault的占位链接仅用于编辑预览服务端则通过get_term_link( $term )获取真实术语链接并用esc_url()转义后输出a包裹的术语名称见下文服务端渲染节。levelOptions仅用于编辑器 UI配合HeadingLevelDropdown组件生成标题层级下拉选项。编辑器端的属性交互在 edit.jsx 中工具栏BlockControls中使用了HeadingLevelDropdown其value{ level }、options{ levelOptions }onChange时写入setAttributes( { level: newLevel } )侧边栏InspectorControls通过ToolsPanel实验性工具面板组件提供Make term name a link开关ToggleControl切换isLink面板的resetAll将isLink重置为false显示的文本通过decodeEntities( term.name )对术语名称做 HTML 实体解码避免特殊字符如在编辑预览中显示异常当术语数据尚未就绪时回退显示翻译字符串__( Term Name )。支持能力SupportsREADME 与block.json中supports声明了该块可继承的主题样式控制能力能力配置值说明anchortrue支持 HTML 锚点 IDalign[wide, full]支持宽对齐与全宽对齐htmlfalse不允许在 HTML 模式下直接编辑该块的标记动态块常规设定color.gradientstrue支持渐变背景color.linktrue支持链接颜色spacing.paddingtrue支持内边距设置typography.fontSize/lineHeight/textAligntrue支持字号、行高、文本对齐interactivity.clientNavigationtrue支持客户端导航区块视图互操作__experimentalBorder半径、颜色、宽度、样式实验性边框能力值得注意block.json中还声明了实验性默认控件color.__experimentalDefaultControlsbackground、text、link默认显示typography.__experimentalDefaultControls.fontSize字号默认显示__experimentalBorder.__experimentalDefaultControls颜色、宽度、样式默认显示。这些默认控件决定样式侧边栏中默认展开的面板项便于用户在插入块后快速调整颜色、字号与边框。上下文ContexttermId 与 taxonomy该块不单独查询数据而是通过块上下文Block Context消费外部提供的术语数据usesContexttermId、taxonomy在典型的使用场景中术语上下文由**术语查询块core/term-template**通过providesContext提供在 term-template/edit.jsx 中可以看到其以{ termId: term.id, taxonomy }的结构向子块注入上下文从而让core/term-name在循环内针对每个术语分别渲染其名称。同时编辑器端的use-term-name.js实现了双层数据获取策略优先使用上下文当termId与taxonomy都存在时通过select( coreStore ).getEntityRecord( taxonomy, taxonomy, termId )从wordpress/core-data获取术语实体回退到模板解析当上下文缺失例如直接在站点编辑器里编辑某个术语归档模板时则解析当前模板的 slug——正则/^(category|tag|taxonomy-([^-]))$|^(((category|tag)|taxonomy-([^-]))-(.))$/用于识别形如category-news、tag-featured的术语归档模板提取出 taxonomy 与 termSlug再通过getEntityRecords( taxonomy, taxonomy, { slug: termSlug, per_page: 1 } )取回术语记录。动态渲染与服务端实现README 明确指出该块属于动态块Dynamic Block渲染发生在服务端帖子内容中不保存渲染后的 HTML仅保存块注释标记!-- wp:term-name /--服务端渲染逻辑位于 index.php 的render_block_core_term_name()其流程为数据来源解析若块上下文中存在termId与taxonomy则调用get_term( $termId, $taxonomy )获取术语否则回退到get_queried_object()并校验返回对象是否为WP_Term实例保证在分类/标签归档页场景下的正确回退空值保护术语不存在或返回WP_Error时直接返回空字符串不输出任何标记标签选择依据level属性决定p或h1h6链接处理若isLink为真通过get_term_link()获取术语归档链接esc_url()转义后生成a href...术语名/a样式类合成当设置了textAlign时追加has-text-align-{value}类当设置了链接文本颜色style.elements.link.color.text时追加has-link-color类包装属性使用get_block_wrapper_attributes()生成包含类与主题样式变量的包装属性输出最终以sprintf拼装标签 包装属性术语名称/标签返回。块注册通过register_block_type_from_metadata( __DIR__ . /term-name, [ render_callback ... ] )完成并在init钩子上执行见 index.php。服务端文件头部注释标注了该块自6.9.0版本引入since 6.9.0。编辑器端实现与数据 Hook编辑器端的入口在 index.js通过initBlock()完成注册edit指向 edit.jsxsave未提供动态块不保存内容并挂载了deprecated迁移数组。术语数据获取的核心 Hook 是 use-term-name.js 中的useTermName( termId, taxonomy )返回{ hasContext, term }hasContext标识是否拥有上下文数据有上下文时返回core-data中的术语实体无上下文时返回模板解析得到的术语。其中模板解析函数useTemplateBasedTermData()特意通过字符串core/editor访问编辑器 store以避免引入wordpress/editor包依赖源码中有wordpress/data-no-store-string-literals的 eslint 豁免注释这种按需加载的思路对自定义动态块同样具有参考价值。样式实现该块的样式位于 style.scss目前仅有一条规则.wp-block-term-name { // 该块支持自定义内边距border-box 使内边距计算更可预测。 box-sizing: border-box; }即wp-block-term-name容器统一使用border-box盒模型保证用户设置内边距spacing.padding时宽高计算符合直觉。其余视觉样式颜色、字号、行高等均由块编辑器根据supports配置生成的行内 CSS 变量控制服务端渲染时通过get_block_wrapper_attributes()输出。兼容性与属性迁移仓库中的 deprecated.js 定义了该块的v1 版本迁移v1 的属性结构包含了独立的textAligntype: string属性且save: () null动态块始终无保存内容迁移函数migrateTextAlign见 utils/migrate-text-align.js会将顶层textAlign属性搬移进style.typography.textAlign随后从属性中移除isEligible通过!! attributes.textAlign判定是否命中旧版本数据。这一机制保证老版本块数据在升级后能无缝转换为新的样式结构textAlign由独立属性收敛为typography样式的一部分与块自身的supports.typography.textAlign能力保持一致。典型使用场景与注意事项在术语模板/查询循环中使用将core/term-name放入core/term-template循环内借助termId、taxonomy上下文自动渲染每个术语的名称设置level为 16 可让术语名称作为页面/列表标题出现。在归档模板中直接使用上下文缺失时服务端回退到get_queried_object()编辑器端回退到模板 slug 解析因此在分类、标签等归档模板中直接使用也能正确显示当前术语名称。链接开关需要术语名称可点击跳转到归档页时开启isLink注意编辑器预览中的伪链接#term-name-pseudo-link只是占位真实链接由服务端get_term_link()生成。动态块约束由于不保存 HTML该块的supports.html为false文本内容无法在代码编辑器中直接改写样式完全依赖块编辑器的控件面板。相关源码与测试入口块元数据packages/block-library/src/term-name/block.json编辑器实现packages/block-library/src/term-name/edit.jsx数据 Hookpackages/block-library/src/term-name/use-term-name.js服务端渲染packages/block-library/src/term-name/index.php迁移逻辑packages/block-library/src/term-name/deprecated.js样式packages/block-library/src/term-name/style.scss上下文提供方packages/block-library/src/term-template/edit.jsx深入阅读这些文件可以完整还原core/term-name从「块上下文注入 → 编辑器端数据获取 → 服务端动态渲染」的完整链路并为开发自定义术语相关动态块提供可直接借鉴的实现范式。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gutenberg 核心块深入解析：core/term-name（分类法术语名称块）的渲染机制与配置指南
Gutenberg 核心块深入解析core/term-name分类法术语名称块的渲染机制与配置指南【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读core/term-name是 WordPress Gutenberg 块编辑器中的核心主题类块用于在页面中动态展示当前分类法术语Term的名称例如分类Category、标签Tag等归档页上的术语标题。本文以 packages/block-library/src/term-name/README.md 为骨架结合仓库中的block.json、编辑器端源码与服务端渲染源码系统讲解该块的属性体系、支持能力、上下文数据流、动态渲染原理以及编辑器内的降级与迁移机制帮助你理解并能在主题模板中正确使用与定制这一块。块概览定位与元数据根据 term-name/block.json该块的核心元数据如下名称Namecore/term-name标题TitleTerm Name分类Categorytheme主题类块API 版本apiVersion3描述DescriptionDisplays the name of a taxonomy term.显示分类法术语的名称关键词Keywordsterm title文本域textdomaindefault样式句柄stylewp-block-term-name在 packages/block-library/src/index.jsx 中该块通过registerBlockType体系注册为 Gutenberg 的核心块之一其块类型为动态块Dynamic Block即渲染由服务端完成帖子内容中不保存最终 HTML。属性Attributeslevel、isLink 与 levelOptionsREADME 中通过attributes属性定义于block.json声明了三个属性属性类型默认值说明levelnumber0标题层级0表示使用p段落标签isLinkbooleanfalse是否将术语名称包裹为指向术语归档页的链接levelOptionsarray—编辑器端标题层级下拉框的可用选项三个属性在编辑器端edit.jsx与服务端渲染index.php中的处理完全对应level 的取值语义编辑器端const TagName level 0 ? p :h${level};服务端$tag_name 0 $level ? p : h . (int) $level;——两者保持一致0渲染为段落p16渲染为对应的h1h6。服务端还做了(int)强转防止非数值输入注入到标签名中。isLink 的作用编辑器端在开启该开关时渲染一个href#term-name-pseudo-link且onClick中preventDefault的占位链接仅用于编辑预览服务端则通过get_term_link( $term )获取真实术语链接并用esc_url()转义后输出a包裹的术语名称见下文服务端渲染节。levelOptions仅用于编辑器 UI配合HeadingLevelDropdown组件生成标题层级下拉选项。编辑器端的属性交互在 edit.jsx 中工具栏BlockControls中使用了HeadingLevelDropdown其value{ level }、options{ levelOptions }onChange时写入setAttributes( { level: newLevel } )侧边栏InspectorControls通过ToolsPanel实验性工具面板组件提供Make term name a link开关ToggleControl切换isLink面板的resetAll将isLink重置为false显示的文本通过decodeEntities( term.name )对术语名称做 HTML 实体解码避免特殊字符如在编辑预览中显示异常当术语数据尚未就绪时回退显示翻译字符串__( Term Name )。支持能力SupportsREADME 与block.json中supports声明了该块可继承的主题样式控制能力能力配置值说明anchortrue支持 HTML 锚点 IDalign[wide, full]支持宽对齐与全宽对齐htmlfalse不允许在 HTML 模式下直接编辑该块的标记动态块常规设定color.gradientstrue支持渐变背景color.linktrue支持链接颜色spacing.paddingtrue支持内边距设置typography.fontSize/lineHeight/textAligntrue支持字号、行高、文本对齐interactivity.clientNavigationtrue支持客户端导航区块视图互操作__experimentalBorder半径、颜色、宽度、样式实验性边框能力值得注意block.json中还声明了实验性默认控件color.__experimentalDefaultControlsbackground、text、link默认显示typography.__experimentalDefaultControls.fontSize字号默认显示__experimentalBorder.__experimentalDefaultControls颜色、宽度、样式默认显示。这些默认控件决定样式侧边栏中默认展开的面板项便于用户在插入块后快速调整颜色、字号与边框。上下文ContexttermId 与 taxonomy该块不单独查询数据而是通过块上下文Block Context消费外部提供的术语数据usesContexttermId、taxonomy在典型的使用场景中术语上下文由**术语查询块core/term-template**通过providesContext提供在 term-template/edit.jsx 中可以看到其以{ termId: term.id, taxonomy }的结构向子块注入上下文从而让core/term-name在循环内针对每个术语分别渲染其名称。同时编辑器端的use-term-name.js实现了双层数据获取策略优先使用上下文当termId与taxonomy都存在时通过select( coreStore ).getEntityRecord( taxonomy, taxonomy, termId )从wordpress/core-data获取术语实体回退到模板解析当上下文缺失例如直接在站点编辑器里编辑某个术语归档模板时则解析当前模板的 slug——正则/^(category|tag|taxonomy-([^-]))$|^(((category|tag)|taxonomy-([^-]))-(.))$/用于识别形如category-news、tag-featured的术语归档模板提取出 taxonomy 与 termSlug再通过getEntityRecords( taxonomy, taxonomy, { slug: termSlug, per_page: 1 } )取回术语记录。动态渲染与服务端实现README 明确指出该块属于动态块Dynamic Block渲染发生在服务端帖子内容中不保存渲染后的 HTML仅保存块注释标记!-- wp:term-name /--服务端渲染逻辑位于 index.php 的render_block_core_term_name()其流程为数据来源解析若块上下文中存在termId与taxonomy则调用get_term( $termId, $taxonomy )获取术语否则回退到get_queried_object()并校验返回对象是否为WP_Term实例保证在分类/标签归档页场景下的正确回退空值保护术语不存在或返回WP_Error时直接返回空字符串不输出任何标记标签选择依据level属性决定p或h1h6链接处理若isLink为真通过get_term_link()获取术语归档链接esc_url()转义后生成a href...术语名/a样式类合成当设置了textAlign时追加has-text-align-{value}类当设置了链接文本颜色style.elements.link.color.text时追加has-link-color类包装属性使用get_block_wrapper_attributes()生成包含类与主题样式变量的包装属性输出最终以sprintf拼装标签 包装属性术语名称/标签返回。块注册通过register_block_type_from_metadata( __DIR__ . /term-name, [ render_callback ... ] )完成并在init钩子上执行见 index.php。服务端文件头部注释标注了该块自6.9.0版本引入since 6.9.0。编辑器端实现与数据 Hook编辑器端的入口在 index.js通过initBlock()完成注册edit指向 edit.jsxsave未提供动态块不保存内容并挂载了deprecated迁移数组。术语数据获取的核心 Hook 是 use-term-name.js 中的useTermName( termId, taxonomy )返回{ hasContext, term }hasContext标识是否拥有上下文数据有上下文时返回core-data中的术语实体无上下文时返回模板解析得到的术语。其中模板解析函数useTemplateBasedTermData()特意通过字符串core/editor访问编辑器 store以避免引入wordpress/editor包依赖源码中有wordpress/data-no-store-string-literals的 eslint 豁免注释这种按需加载的思路对自定义动态块同样具有参考价值。样式实现该块的样式位于 style.scss目前仅有一条规则.wp-block-term-name { // 该块支持自定义内边距border-box 使内边距计算更可预测。 box-sizing: border-box; }即wp-block-term-name容器统一使用border-box盒模型保证用户设置内边距spacing.padding时宽高计算符合直觉。其余视觉样式颜色、字号、行高等均由块编辑器根据supports配置生成的行内 CSS 变量控制服务端渲染时通过get_block_wrapper_attributes()输出。兼容性与属性迁移仓库中的 deprecated.js 定义了该块的v1 版本迁移v1 的属性结构包含了独立的textAligntype: string属性且save: () null动态块始终无保存内容迁移函数migrateTextAlign见 utils/migrate-text-align.js会将顶层textAlign属性搬移进style.typography.textAlign随后从属性中移除isEligible通过!! attributes.textAlign判定是否命中旧版本数据。这一机制保证老版本块数据在升级后能无缝转换为新的样式结构textAlign由独立属性收敛为typography样式的一部分与块自身的supports.typography.textAlign能力保持一致。典型使用场景与注意事项在术语模板/查询循环中使用将core/term-name放入core/term-template循环内借助termId、taxonomy上下文自动渲染每个术语的名称设置level为 16 可让术语名称作为页面/列表标题出现。在归档模板中直接使用上下文缺失时服务端回退到get_queried_object()编辑器端回退到模板 slug 解析因此在分类、标签等归档模板中直接使用也能正确显示当前术语名称。链接开关需要术语名称可点击跳转到归档页时开启isLink注意编辑器预览中的伪链接#term-name-pseudo-link只是占位真实链接由服务端get_term_link()生成。动态块约束由于不保存 HTML该块的supports.html为false文本内容无法在代码编辑器中直接改写样式完全依赖块编辑器的控件面板。相关源码与测试入口块元数据packages/block-library/src/term-name/block.json编辑器实现packages/block-library/src/term-name/edit.jsx数据 Hookpackages/block-library/src/term-name/use-term-name.js服务端渲染packages/block-library/src/term-name/index.php迁移逻辑packages/block-library/src/term-name/deprecated.js样式packages/block-library/src/term-name/style.scss上下文提供方packages/block-library/src/term-template/edit.jsx深入阅读这些文件可以完整还原core/term-name从「块上下文注入 → 编辑器端数据获取 → 服务端动态渲染」的完整链路并为开发自定义术语相关动态块提供可直接借鉴的实现范式。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考