企业官网建设流程全解析

Gutenberg 核心文本区块全解析：从 Text 分类索引到 15 个core/*区块的 block.json 元数据

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

本文以 Gutenberg 仓库中的核心区块参考索引 category-text.md 为主体，逐块解读 Text（文本）分类下 15 个核心区块的名称、描述、关键属性与样式支持；同时结合 block-library 源码 与 文档生成脚本 的实现，说明这份索引是如何由block.json自动产出的，帮助读者在撰写、审查或扩展文本类内容区块时快速定位元数据定义与实现证据。

1. 索引页从哪来：一套基于block.json的自动文档机制

阅读之前需要先明确一个前提：category-text.md 不是一篇手工维护的长文，而是一份由脚本生成的区块目录索引。它的全部内容被包裹在一对机器标记之间：

<!-- START TOKEN(Autogenerated block API docs) --> - Code — `core/code`: Display code snippets that respect your spacing and tabs. - Details — `core/details`: Hide and show additional content. … - Poetry — `core/verse`: Insert poetry. Use special spacing formats. Or quote song lyrics. <!-- END TOKEN(Autogenerated block API docs) -->

生成逻辑位于 generate-block-docs.mjs：脚本扫描 packages/block-library/src 下每个包含block.json的目录（见getBlockDirs()，第 105–117 行），按category字段归组，再按CATEGORY_LABELS将text映射为 “Text” 分类页（第 89–98 行）。分类索引页由generateCategoryPageSection()生成：每个条目取block.json的title、name、description，拼成- [标题] — \区块名`: 描述` 的形式（第 889–908 行）。

值得强调的是其“可再生”设计：

• 每区块详情页（packages/block-library/src/{block}/README.md）与分类索引页都使用 START/END TOKEN 分隔自动内容，手工撰写的内容（token 之外的部分）在重新生成时会被保留，token 之间则被整体替换（writeBlockReadme()的三态逻辑，第 827–870 行）；
• 区块详情的属性表、Supports 列表、上下文、样式表、CSS 选择器等小节全部直接来自block.json（generateBlockApiSection()，第 621–815 行）；
• “Block Markup”示例优先读取 test/integration/fixtures/blocks 下的core__{block}.html集成测试夹具，缺省时才按属性默认值合成一段块注释（generateBlockCommentExample()，第 587–611 行）；
• 根package.json中提供了docs:blocks、docs:blocks-detail等 npm 脚本（package.json 第 124–126 行），即修改block.json后重新运行文档脚本，索引页与区块 README 会自动同步。

同一目录下还有总览页 core-blocks/README.md，其中对文本分类区块给出了更详细的 Supports/Attributes 摘要，并约定了两种标记：删除线表示被显式禁用的能力，**Experimental:**表示仅在 Gutenberg 插件激活时可用（README.md 第 5–7 行）。

2. Text 分类区块完整清单

以下 15 个区块即索引页<!-- START TOKEN -->与<!-- END TOKEN -->之间的全部内容，本文后续小节逐一结合各区块的block.json展开。

清单中值得注意的结构关系：List Item 是 List 的“内区块”（inner block）（parent: ["core/list"]），Footnotes 依赖postId/postType上下文，而Missing 与 Freeform 分别承担“无法识别区块”与“经典编辑器兼容”两个兜底职责。这些细节见下文。

3. 文本区块的元数据共性：block.json里的规律

逐一展开之前，先提炼这 15 份block.json的共性，理解它们能大幅降低阅读单块的成本。

（1）统一的字段骨架。所有文本区块的block.json都声明了"$schema": "https://schemas.wp.org/trunk/block.json"与"apiVersion": 3，以及name（core/xxx形式）、title（编辑器标题）、category: "text"、description（区块库插入器中的描述文本）和textdomain（国际化域）。例如 Paragraph 的 block.json 中description即 “Start with the basic building block of all narrative.”，与索引页的描述逐字一致——这印证了索引页确实只从block.json取值。

（2）style与editorStyle成对出现。大多数文本区块声明两个 CSS 类名，如 Paragraph 的"editorStyle": "wp-block-paragraph-editor"与"style": "wp-block-paragraph"（第 87–88 行）。前者仅编辑器内生效，后者用于前台输出的区块包装元素，主题据此覆盖区块样式。

（3）supports决定了区块在编辑器中可定制的范围。文本区块普遍声明以下支持项：

• typography：fontSize、lineHeight为基础，许多还开启textAlign与一系列__experimental*子项（字体族、字重、斜体、字间距、大小写转换、书写方向、文字阴影、fitText等）；
• color：普遍开启gradients、link与__experimentalDefaultControls（默认展示背景色/文字色控件）；
• spacing：margin/padding可选，且普遍通过__experimentalDefaultControls关闭了 margin/padding 的默认控件；
• anchor：允许为区块添加 HTML 锚点；
• interactivity.clientNavigation: true：启用客户端导航（站点内链接不整页刷新）；
• align：取值因块而异，如 Paragraph 为[ "wide", "full" ]（第 30 行），Quote/Pullquote 为[ "left", "right", "wide", "full" ]，Code 仅[ "wide" ]。

（4）rich-text类型属性 +selector是文本内容的核心模式。Paragraph 的content属性定义如下（paragraph/block.json 第 11–16 行）：

"content": { "type": "rich-text", "source": "rich-text", "selector": "p", "role": "content" }

source: "rich-text"表示内容以富文本形式保存在块注释内部的 HTML 中，selector: "p"指明从哪个元素提取，role: "content"标记其为内容角色（供 AI 等工具识别正文）。各区块按语义选择不同选择器：Heading 用"h1,h2,h3,h4,h5,h6"，Code 用code，Preformatted 与 Poetry 用pre，List 的values用"ol,ul"且multiline: "li"（跨多个<li>取整段 HTML，list/block.json 第 17–24 行）。

（5）keywords服务插入器搜索。如 List 声明[ "bullet list", "ordered list", "numbered list" ]（list/block.json 第 9 行），Details 声明[ "summary", "toggle", "disclosure" ]（details/block.json 第 8 行），使用/斜杠插入器键入这些词即可命中对应区块。

4. 重点区块逐一深入

4.1 Paragraph 与 Heading：叙事的两个基石

Paragraph（core/paragraph）是块编辑器中默认的段落载体。除上文示例的content外，它还有三个属性（paragraph/block.json 第 10–28 行）：

• dropCap：boolean，默认false，首字下沉开关；
• placeholder：string，编辑占位文本；
• direction：string，enum: [ "ltr", "rtl" ]，段落书写方向。

它独有的一个能力是首行缩进：supports.typography开启textIndent，且selectors中为缩进指定了专门的选择器.wp-block-paragraph + .wp-block-paragraph（第 81–86 行）——即只有“紧跟在另一个段落之后的段落”才应用缩进，避免段落在区块开头被误缩进。同时splitting: true表示支持把区块按换行拆分为多个（编辑器中的 Split Blocks 操作）。

Heading（core/heading）的结构几乎相同，差异在：

• content选择器为"h1,h2,h3,h4,h5,h6"（heading/block.json 第 14 行），标题级别由 HTML 标签本身携带；
• 额外属性level（number，默认值 2）与levelOptions（array，可用于收窄可选级别）（第 17–23 行）；
• 显式开启className: true，允许自定义类名；
• 开启__experimentalSlashInserter: true（第 73 行），即可在斜杠菜单中插入。

两者的keywords（Paragraph 为"text"，Heading 为"title", "subtitle"）也印证了各自的搜索语义。

4.2 List 与 List Item：父子结构与嵌套列表

List（core/list）是典型的容器区块：allowedBlocks: [ "core/list-item" ]声明它只能容纳 List Item（list/block.json 第 7 行），并通过listView: true支持列表视图管理子项。它的属性集（第 11–37 行）：

List Item（core/list-item）则声明parent: [ "core/list" ]限定只能出现在 List 内，同时allowedBlocks: [ "core/list" ]允许在项内再嵌一个 List，从而表达嵌套列表（list-item/block.json 第 7–8 行）。它的selectors也值得注意：root: ".wp-block-list > li"、border: ".wp-block-list:not(.wp-block-list .wp-block-list) > li"（第 66–69 行）——边框样式只作用于最外层列表的li，避免嵌套列表被重复描边。

4.3 Quote 与 Pullquote：两种不同的引用强调

Quote（core/quote）对应<blockquote>。其value属性用source: "html"+multiline: "p"提取引用内多个<p>的完整 HTML，citation则是从<cite>取出的富文本（quote/block.json 第 10–28 行）。它还声明了两套区块样式：

"styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "plain", "label": "Plain" } ]

即除默认样式外还有一个plain变体。选中的样式会以is-style-{name}形式附加到区块包装元素的类名上；仓库文档 block-styles.md 就以给core/quote注册fancy-quote样式为例讲解该机制。下图展示了在区块检查器中为 Quote 选择自定义样式的界面：

Pullquote（core/pullquote）与 Quote 共享value/citation两个属性（分别取<p>与<cite>，pullquote/block.json 第 9–22 行），但定位不同：它用于从正文中“抽出”一段话做更强的视觉强调。这一点在元数据里有直接证据——它声明了__experimentalStyle默认样式（第 77–82 行）：

"__experimentalStyle": { "typography": { "fontSize": "1.5em", "lineHeight": "1.6" } }

即 Pullquote 的前台输出默认以 1.5em 字号、1.6 行高呈现，比正文显著放大。此外两者都支持background（背景图/渐变）、dimensions.minHeight，并开启__experimentalOnEnter/__experimentalOnMerge（Quote，第 60–61 行）等编辑行为。

4.4 Code、Preformatted 与 Verse：三类保留空白格式

这三个区块的content属性都带有__unstablePreserveWhiteSpace: true，意味着编辑器在序列化时保留用户输入的原始空格与制表符：

Code 区块的keywords未显式声明，但title: "Code"与description（“Display code snippets that respect your spacing and tabs.”）已在索引页中体现。

4.5 Details：基于<details>/<summary>的原生折叠

Details（core/details）用 HTML 原生的<details>元素实现“显示/隐藏”交互，其属性设计值得参考（details/block.json 第 10–30 行）：

• summary：rich-text类型，selector: "summary"，即折叠时可见的摘要行；
• showContent：boolean，默认false，对应<details open>的初始状态；
• name：source: "attribute"+attribute: "name"+selector: ".wp-block-details"，直接从包装元素的name属性读写（用于多区块时的唯一标识）；
• placeholder：编辑占位文本。

它同时声明layout.allowEditing: false、allowedBlocks: true与html: false：容器内区块布局不可手动切换、允许放入任意区块、且禁用“另存为自定义 HTML”。keywords中的summary、toggle、disclosure与 HTML 语义对应。

4.6 Table：用嵌套 query 属性表达行列结构

Table（core/table）是文本分类中属性结构最复杂的区块。它没有平铺的内容属性，而是把表格拆成三个source: "query"的数组属性（table/block.json 第 9–158 行）：

• head：selector: "thead tr"，body：selector: "tbody tr"，foot：selector: "tfoot tr"；
• 每一行是一个cells数组，selector: "td,th"，再向下嵌套每个单元格的属性：content（rich-text）、tag（默认td，source: "tag"即读取标签名）、scope（读scope属性）、align（读data-align属性）、colspan、rowspan。

这种“查询—查询—属性”的三层结构让编辑器能够精确增删行列与合并单元格。另外：

• hasFixedLayout默认true（<table>的固定布局）；
• caption为富文本，selector: "figcaption"；
• 内置两样式：regular（默认，标签 “Default”）与stripes（斑马纹）（第 210–217 行）；
• selectors中root: ".wp-block-table > table"、spacing: ".wp-block-table"，说明间距类施加在外层包装上、字号/颜色类施加在<table>上；
• 颜色与边框支持均带__experimentalSkipSerialization: true（第 162–201 行），即这些定制通过 style 内联等机制应用而非序列化进区块标记。

4.7 Math：LaTeX 与 MathML 的双轨属性

Math（core/math）只有两个属性（math/block.json 第 44–54 行）：

"attributes": { "latex": { "type": "string", "role": "content" }, "mathML": { "type": "string", "source": "html", "selector": "math" } }

latex没有source，说明 LaTeX 源码只作为纯属性保存在块注释里，供编辑时回显；mathML则从已保存 HTML 的<math>元素提取（source: "html"+selector: "math"）。从源码结构看，这种“LaTeX 属性 + MathML HTML”的组合意味着前台展示依赖 MathML 输出，而编辑源始终是可回改的 LaTeX 字符串；仓库中packages/latex-to-mathml/包的存在（见 packages 目录）从结构上印证了 LaTeX→MathML 的转换链路。注意其supports.html: false：Math 区块不允许在编辑器中切换为原始 HTML 模式。

4.8 Footnotes：上下文驱动的“隐式”区块

Footnotes（core/footnotes）元数据中最关键的不是属性（它没有任何属性），而是上下文与可见性（footnotes/block.json 第 10–37 行）：

"usesContext": [ "postId", "postType" ], "supports": { "html": false, "multiple": false, "reusable": false, "inserter": false, … }

• usesContext声明它需要上层区块（如 Query/Post Template）提供当前文章的postId与postType，据此在页面底部渲染该文章的脚注集合；
• inserter: false+multiple: false表示它不出现在常规插入器、也不允许同页多实例——它是一个由文章结构自动出现的“收尾”区块，而非作者手动放置的普通文本区块。

4.9 Classic（core/freeform）与 Unsupported（core/missing）：兼容与兜底

Classic 区块是块编辑器与经典编辑器的桥：其唯一属性content为"type": "string", "source": "raw"（freeform/block.json 第 9–14 行），即把经典编辑器产生的整段原始 HTML 原样包进一个区块；同时关闭className、lock、reusable、renaming、visibility、customCSS等定制项（第 15–23 行），编辑器内部以经典编辑界面呈现（editorStyle: "wp-block-freeform-editor"）。仓库中 packages/block-library/src/classic.scss 与目录freeform/的命名（导入时import * as classic from './freeform'，见 index.jsx 顶部导入区）体现了“classic 是用户可见标题、freeform 是实现目录”的对应关系。

Unsupported 区块（core/missing）则处理“站点不认识某个区块”的情况（典型如停用插件后残留的块注释）。它保留原始信息用于将来恢复：originalName（原区块名）、originalUndelimitedContent、originalContent（source: "raw"，原始标记）（missing/block.json 第 9–20 行），并关闭插入器（inserter: false）与几乎全部定制能力，使其仅作为编辑器中的占位与警告载体存在。

5. 在仓库中如何定位与验证这些区块

• 元数据与实现：每个区块位于 packages/block-library/src/{slug} 目录（如 packages/block-library/src/quote），block.json定义静态元数据，同目录的edit/save脚本实现编辑器渲染与序列化；
• 注册入口：packages/block-library/src/index.jsx 集中导入并注册全部核心区块（import * as quote from './quote'等）；文件头注释同时说明：实验性区块仅注册到 Gutenberg 插件（__experimentalRegisterExperimentalCoreBlocks），核心 WordPress 会通过isBlockMetadataExperimental过滤它们；
• 集成测试夹具：test/integration/fixtures/blocks/下每个区块对应core__{slug}.json/core__{slug}.html一对文件，用于验证序列化/反序列化往返一致性，也是文档生成器“Block Markup”一节的素材来源；PHP 侧另有 phpunit/block-fixture-test.php 组织相关测试；
• 更新文档：改动任一block.json后，运行npm run docs:blocks（汇总入口docs:build亦包含它，见 package.json 第 124–126 行）即可再生本索引页与各区块 README，无需手工编辑 token 之间的内容；
• 参考体系对照：属性各字段（type/source/selector/role）的完整语义见 block-attributes.md，supports各子项见 block-supports.md——文档生成器正是把block.json字段锚定到这两个参考页的小节上（ATTRIBUTE_ANCHORS映射，generate-block-docs.mjs 第 68–76 行）。

6. 小结

category-text.md 以极短的篇幅给出了 Text 分类 15 个核心区块的“名册”：从最基础的 Paragraph/Heading，到结构化内容的 List/Table，到特殊排版的 Code/Preformatted/Verse，到交互性的 Details，再到 Math、Footnotes 以及 Classic、Unsupported 两个兼容兜底角色。理解这份索引的正确方式不是把它当静态清单，而是把它与三个可追溯来源联动起来——各区块的block.json（能力与属性的唯一事实来源）、packages/block-library/src/下的 edit/save 实现、以及tools/docs/generate-block-docs.mjs这条自动文档管线。掌握“索引条目 → block.json 字段 → 编辑器行为”的对应关系后，无论是查阅某个区块支持哪些样式定制，还是为新文本区块定义元数据，都能在仓库内快速找到依据。

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