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.jsongenerateBlockApiSection()第 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展开。#标题区块名一句话描述源自索引页元数据定义位置1Codecore/codeDisplay code snippets that respect your spacing and tabs.code/block.json2Detailscore/detailsHide and show additional content.details/block.json3Footnotescore/footnotesDisplay footnotes added to the page.footnotes/block.json4Classiccore/freeformUse the classic WordPress editor.freeform/block.json5Headingcore/headingIntroduce new sections and organize content to help visitors (and search engines) understand the structure of your content.heading/block.json6Listcore/listAn organized collection of items displayed in a specific order.list/block.json7List Itemcore/list-itemAn individual item within a list.list-item/block.json8Mathcore/mathDisplay mathematical notation using LaTeX.math/block.json9Unsupportedcore/missingYour site doesnt include support for this block.missing/block.json10Paragraphcore/paragraphStart with the basic building block of all narrative.paragraph/block.json11Preformattedcore/preformattedAdd text that respects your spacing and tabs, and also allows styling.preformatted/block.json12Pullquotecore/pullquoteGive special visual emphasis to a quote from your text.pullquote/block.json13Quotecore/quoteGive quoted text visual emphasis. In quoting others, we cite ourselves. — Julio Cortázarquote/block.json14Tablecore/tableCreate structured content in rows and columns to display information.table/block.json15Poetrycore/verseInsert poetry. Use special spacing formats. Or quote song lyrics.verse/block.json清单中值得注意的结构关系List Item 是 List 的“内区块”inner blockparent: [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以及namecore/xxx形式、title编辑器标题、category: text、description区块库插入器中的描述文本和textdomain国际化域。例如 Paragraph 的 block.json 中description即 “Start with the basic building block of all narrative.”与索引页的描述逐字一致——这印证了索引页确实只从block.json取值。2style与editorStyle成对出现。大多数文本区块声明两个 CSS 类名如 Paragraph 的editorStyle: wp-block-paragraph-editor与style: wp-block-paragraph第 87–88 行。前者仅编辑器内生效后者用于前台输出的区块包装元素主题据此覆盖区块样式。3supports决定了区块在编辑器中可定制的范围。文本区块普遍声明以下支持项typographyfontSize、lineHeight为基础许多还开启textAlign与一系列__experimental*子项字体族、字重、斜体、字间距、大小写转换、书写方向、文字阴影、fitText等color普遍开启gradients、link与__experimentalDefaultControls默认展示背景色/文字色控件spacingmargin/padding可选且普遍通过__experimentalDefaultControls关闭了 margin/padding 的默认控件anchor允许为区块添加 HTML 锚点interactivity.clientNavigation: true启用客户端导航站点内链接不整页刷新align取值因块而异如 Paragraph 为[ wide, full ]第 30 行Quote/Pullquote 为[ left, right, wide, full ]Code 仅[ wide ]。4rich-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,h6Code 用codePreformatted 与 Poetry 用preList 的values用ol,ul且multiline: li跨多个li取整段 HTMLlist/block.json 第 17–24 行。5keywords服务插入器搜索。如 List 声明[ bullet list, ordered list, numbered list ]list/block.json 第 9 行Details 声明[ summary, toggle, disclosure ]details/block.json 第 8 行使用/斜杠插入器键入这些词即可命中对应区块。4. 重点区块逐一深入4.1 Paragraph 与 Heading叙事的两个基石Paragraphcore/paragraph是块编辑器中默认的段落载体。除上文示例的content外它还有三个属性paragraph/block.json 第 10–28 行dropCapboolean默认false首字下沉开关placeholderstring编辑占位文本directionstringenum: [ ltr, rtl ]段落书写方向。它独有的一个能力是首行缩进supports.typography开启textIndent且selectors中为缩进指定了专门的选择器.wp-block-paragraph .wp-block-paragraph第 81–86 行——即只有“紧跟在另一个段落之后的段落”才应用缩进避免段落在区块开头被误缩进。同时splitting: true表示支持把区块按换行拆分为多个编辑器中的 Split Blocks 操作。Headingcore/heading的结构几乎相同差异在content选择器为h1,h2,h3,h4,h5,h6heading/block.json 第 14 行标题级别由 HTML 标签本身携带额外属性levelnumber默认值 2与levelOptionsarray可用于收窄可选级别第 17–23 行显式开启className: true允许自定义类名开启__experimentalSlashInserter: true第 73 行即可在斜杠菜单中插入。两者的keywordsParagraph 为textHeading 为title, subtitle也印证了各自的搜索语义。4.2 List 与 List Item父子结构与嵌套列表Listcore/list是典型的容器区块allowedBlocks: [ core/list-item ]声明它只能容纳 List Itemlist/block.json 第 7 行并通过listView: true支持列表视图管理子项。它的属性集第 11–37 行属性类型/默认说明orderedboolean默认false有序ol或无序ul列表valuesstringsource: htmlselector: ol,ulmultiline: li整段列表项的 HTML 内容typestring有序列表编号类型如decimal、alpha等对应ol typestartnumber起始编号reversedboolean编号倒序placeholderstring占位文本List Itemcore/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两种不同的引用强调Quotecore/quote对应blockquote。其value属性用source: htmlmultiline: p提取引用内多个p的完整 HTMLcitation则是从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 选择自定义样式的界面Pullquotecore/pullquote与 Quote 共享value/citation两个属性分别取p与citepullquote/block.json 第 9–22 行但定位不同它用于从正文中“抽出”一段话做更强的视觉强调。这一点在元数据里有直接证据——它声明了__experimentalStyle默认样式第 77–82 行__experimentalStyle: { typography: { fontSize: 1.5em, lineHeight: 1.6 } }即 Pullquote 的前台输出默认以 1.5em 字号、1.6 行高呈现比正文显著放大。此外两者都支持background背景图/渐变、dimensions.minHeight并开启__experimentalOnEnter/__experimentalOnMergeQuote第 60–61 行等编辑行为。4.4 Code、Preformatted 与 Verse三类保留空白格式这三个区块的content属性都带有__unstablePreserveWhiteSpace: true意味着编辑器在序列化时保留用户输入的原始空格与制表符区块content选择器输出包裹差异点core/codecodeprecodealign仅支持widespacing.margin限制为[ top, bottom ]code/block.json 第 35 行即只允许上下外边距core/preformattedprepre同样保留空白但定位是“可排版文本”而非代码style: wp-block-preformattedcore/verseprepre面向诗歌/歌词额外支持background、dimensions.minHeight与更完整的 typography 子项verse/block.json 第 19–76 行Code 区块的keywords未显式声明但title: Code与description“Display code snippets that respect your spacing and tabs.”已在索引页中体现。4.5 Details基于details/summary的原生折叠Detailscore/details用 HTML 原生的details元素实现“显示/隐藏”交互其属性设计值得参考details/block.json 第 10–30 行summaryrich-text类型selector: summary即折叠时可见的摘要行showContentboolean默认false对应details open的初始状态namesource: attributeattribute: nameselector: .wp-block-details直接从包装元素的name属性读写用于多区块时的唯一标识placeholder编辑占位文本。它同时声明layout.allowEditing: false、allowedBlocks: true与html: false容器内区块布局不可手动切换、允许放入任意区块、且禁用“另存为自定义 HTML”。keywords中的summary、toggle、disclosure与 HTML 语义对应。4.6 Table用嵌套 query 属性表达行列结构Tablecore/table是文本分类中属性结构最复杂的区块。它没有平铺的内容属性而是把表格拆成三个source: query的数组属性table/block.json 第 9–158 行headselector: thead trbodyselector: tbody trfootselector: tfoot tr每一行是一个cells数组selector: td,th再向下嵌套每个单元格的属性contentrich-text、tag默认tdsource: tag即读取标签名、scope读scope属性、align读data-align属性、colspan、rowspan。这种“查询—查询—属性”的三层结构让编辑器能够精确增删行列与合并单元格。另外hasFixedLayout默认truetable的固定布局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 MathLaTeX 与 MathML 的双轨属性Mathcore/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: htmlselector: math。从源码结构看这种“LaTeX 属性 MathML HTML”的组合意味着前台展示依赖 MathML 输出而编辑源始终是可回改的 LaTeX 字符串仓库中packages/latex-to-mathml/包的存在见 packages 目录从结构上印证了 LaTeX→MathML 的转换链路。注意其supports.html: falseMath 区块不允许在编辑器中切换为原始 HTML 模式。4.8 Footnotes上下文驱动的“隐式”区块Footnotescore/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: falsemultiple: false表示它不出现在常规插入器、也不允许同页多实例——它是一个由文章结构自动出现的“收尾”区块而非作者手动放置的普通文本区块。4.9 Classiccore/freeform与 Unsupportedcore/missing兼容与兜底Classic 区块是块编辑器与经典编辑器的桥其唯一属性content为type: string, source: rawfreeform/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、originalContentsource: raw原始标记missing/block.json 第 9–20 行并关闭插入器inserter: false与几乎全部定制能力使其仅作为编辑器中的占位与警告载体存在。5. 在仓库中如何定位与验证这些区块元数据与实现每个区块位于 packages/block-library/src/{slug} 目录如 packages/block-library/src/quoteblock.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.mdsupports各子项见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考