Gutenberg 核心块深度解析core/column 列块的多属性架构、静态标记与源码实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergcore/column是 GutenbergWordPress 块编辑器项目中core/columns列组块的子容器块负责承载并渲染单个列内的嵌套内容。本文以该块的自动生成 API 文档为主体骨架结合当前仓库中 block.json、edit.jsx、save.jsx 等真实源码深入讲解其属性定义、能力支持Supports、序列化标记、编辑器交互逻辑与响应式样式帮助读者完整掌握这一静态块的设计与实现。块概览静态列块在 Gutenberg 中的定位根据 column/README.md 的官方定义core/column是columns 块中的一个单列A single column within a columns block。其核心元信息如下名称Namecore/column分类Categorydesign设计类API 版本API Version3对应 block.json 中的apiVersion: 3块类型Block Type静态块Static标记直接保存在文章内容中静态块的含义是块的最终 HTML 标记由save函数在保存时生成并写入post_content前端直接输出该标记不经过服务端渲染函数。这一点与动态块依赖 PHPrender_callback实时渲染形成对比也是理解下文Block Markup小节的基础。块关系core/column 与 core/columns 的父子契约文档明确指出core/column的直接父块Parent只有一个core/columns该约束定义在两个层面子块侧block.json 声明parent: [ core/columns ]即该块只允许作为core/columns的直接子块存在父块侧columns/block.json 声明allowedBlocks: [ core/column ]即core/columns只允许容纳core/column作为直接子块。这种双向约束保证了列组与列之间的严格层级关系columns直接包含多个column而每个column内部再通过InnerBlocks容纳段落paragraph、图片image等任意块。此外父块core/columns还提供了isStackedOnMobile移动端是否堆叠默认true属性与列间对齐能力与子块的verticalAlignment相互配合详见下文。Attributes 属性详解core/column的全部属性均通过 block.json 的attributes字段声明共三个Attribute类型枚举/说明默认值verticalAlignmentstring列内内容的垂直对齐方式top、center、bottom、stretch—widthstring列宽作为 CSSflex-basis使用支持%、px、em、rem、vw等长度单位—templateLockstring \| boolean内部块的模板锁定级别all、insert、contentOnly、false—三个属性的语义细节如下verticalAlignment垂直对齐控制列内内容在列高度方向上的对齐方式。在编辑器端edit.jsx通过BlockVerticalAlignmentToolbar提供[top, center, bottom, stretch]四个选项。值得注意的是设置列自身的对齐会同时重置父块core/columns的对齐属性——edit.jsx 中的updateAlignment先setAttributes更新自身再调用updateBlockAttributes( rootClientId, { verticalAlignment: null } )清除父块的统一对齐从而避免两级对齐设置相互冲突。width列宽flex-basis列宽以行内样式flex-basis的形式写入输出标记。源码对宽度值做了两类兼容处理数值类型向后兼容历史上API 版本 3 之前的模板中width可能是0–100的数字被视为百分比。当前 edit.jsx 与 save.jsx 均使用Number.isFinite( width ) ? width % : width将数字统一转换为百分数字符串百分比浮点精度修正save.jsx 中若宽度以%结尾且非整数会将其舍入到至多 12 位小数Math.round( parseFloat( width ) * 1e12 ) / 1e12 %避免长浮点数污染输出标记。在编辑器中宽度通过__experimentalUnitControl带单位输入框编辑可用单位由useSettings( spacing.units )读取兜底为[%, px, em, rem, vw]见 edit.jsx负数值会被钳制为0edit.jsx。templateLock模板锁定控制列内InnerBlocks的编辑约束取值与块 API 文档一致all完全锁定不可增删改内部块、insert禁止插入新块、contentOnly仅允许编辑内容不允许结构调整、false不锁定。该值会直接透传给编辑器端的useInnerBlocksPropsedit.jsx适合在主题模板中固定列内的块结构。Supports 能力支持详解core/column通过supports声明了丰富的样式与行为能力文档表格与 block.json 完全一致能力值说明anchortrue支持 HTML 锚点id可用于页内跳转reusablefalse禁用转为可复用块现为同步模式htmlfalse禁止自定义 HTML 编辑保证标记由块统一输出color.gradientstrue支持背景渐变color.headingtrue支持标题颜色color.buttontrue支持按钮颜色color.linktrue支持链接颜色shadowtrue支持阴影spacing.blockGaptrue支持列内块间距spacing.paddingtrue支持内边距typography.fontSizetrue支持字号typography.lineHeighttrue支持行高layouttrue支持布局控制interactivity.clientNavigationtrue支持客户端导航查看视图交互allowedBlockstrue支持限制内部允许的块类型在 block.json 中还存在文档表格之外的实验性支持项可作为深入了解的补充__experimentalOnEnter: true允许在列内按 Enter 换行__experimentalBordercolor / radius / style / width完整边框支持typography下的__experimentalFontFamily、__experimentalFontWeight、__experimentalFontStyle、__experimentalTextTransform、__experimentalTextDecoration、__experimentalLetterSpacing字体族、字重、字型、大小写变换、文本装饰与字间距color.__experimentalDefaultControlsbackground / text与spacing.__experimentalDefaultControlspadding / blockGap用于控制检查器中的默认显示。Block Markup静态标记与序列化格式作为静态块core/column的标记由保存端 save.jsx 生成并直接写入文章内容。文档给出的典型序列化标记为!-- wp:column -- div classwp-block-column !-- wp:paragraph -- pColumn One, Paragraph One/p !-- /wp:paragraph -- !-- wp:paragraph -- pColumn One, Paragraph Two/p !-- /wp:paragraph -- /div !-- /wp:column --要点解读!-- wp:column --与!-- /wp:column --是块的注释标记block comment delimiters包裹实际 DOM外层div固定携带wp-block-column类名由 save.jsx 的useBlockProps.save输出设置verticalAlignment时会追加is-vertically-aligned-top/center/bottom等类名save.jsx设置width时输出行内样式styleflex-basis: …save.jsx内部块通过useInnerBlocksProps.save递归序列化到div内save.jsx。历史标记迁移deprecated 机制仓库中 deprecated.jsx 记录了旧版块的标记形态早期width是number类型min: 0, max: 100直接输出style{ { flexBasis: width % } }。迁移逻辑migrate将数字转换为百分数字符串如50→50%isEligible通过isFinite( width )识别旧标记并触发自动迁移。这解释了为何当前源码需要反复兼容数字宽度这一历史形态。编辑器端实现宽度、对齐与 InnerBlocks 的协作编辑组件 edit.jsx 完整呈现了列块在编辑器中的交互逻辑宽度面板ColumnInspectorControls使用__experimentalToolsPanel与__experimentalToolsPanelItem提供可折叠的Settings面板其中UnitControl绑定width属性输入框宽度为calc(50% - 8px)支持选择器切换单位edit.jsx对齐工具栏BlockControls中的BlockVerticalAlignmentToolbar提供四个对齐按钮修改时同步清空父块core/columns的统一对齐edit.jsx行内样式通过useBlockProps将flexBasis注入编辑态 DOM确保编辑预览与前端输出一致edit.jsx嵌套容器useInnerBlocksProps接收templateLock、allowedBlocks并在无子块时渲染ButtonBlockAppender 添加按钮有子块时隐藏edit.jsx无障碍标签通过getBlockOrder计算列在父块中的位置生成形如Block: Column (1 of 3)的aria-label便于屏幕阅读器辨识当前列edit.jsx。块的注册入口在 index.js通过initBlock将metadata、edit、save、deprecated注册为core/column的设置对象init.js 负责在运行时完成初始化。响应式样式flex 布局与移动端堆叠列块的布局样式定义在父块样式文件 columns/style.scsswp-block-columns与wp-block-column共用桌面端≥break-medium即 ≥782px无显式宽度的列使用flex-basis: 0; flex-grow: 1均分剩余空间带flex-basis行内样式的列则flex-grow: 0保持固定宽度style.scss这正是width属性驱动列宽分配的原理移动端默认isStackedOnMobile为 true下列的flex-basis: 100% !important强制单列堆叠style.scss父块设置不在移动端堆叠时则flex-wrap: nowrap保持并排垂直对齐父块通过are-vertically-aligned-top/center/bottom类切换align-items列自身则通过is-vertically-aligned-*类由 save.jsx 输出控制内部内容的对齐。在模板与主题中使用 core/column由于块标记直接写入内容开发者可在主题模板如block.html中直接书写列结构。一个带宽度与模板锁定的示例!-- wp:columns -- div classwp-block-columns !-- wp:column {width:33.33%,templateLock:all} -- div classwp-block-column styleflex-basis:33.33% !-- wp:paragraph -- p侧栏内容/p !-- /wp:paragraph -- /div !-- /wp:column -- !-- wp:column {width:66.66%} -- div classwp-block-column styleflex-basis:66.66% !-- wp:paragraph -- p主内容区/p !-- /wp:paragraph -- /div !-- /wp:column -- /div !-- /wp:columns --其中!-- wp:column {width:33.33%,templateLock:all} --的 JSON 参数对应attributes中的属性名编辑器在加载时会按此解析属性并应用相应的行内样式与锁定策略。源码导航以下文件可供继续深入阅读column/README.md本块自动生成的 API 参考文档column/block.json属性与支持能力的唯一事实来源column/edit.jsx编辑器端渲染与交互逻辑column/save.jsx保存端的静态标记输出column/deprecated.jsx历史版本标记的向后兼容迁移column/index.js 与 column/init.js块的注册与初始化columns/block.json父块core/columns的元数据含isStackedOnMobile与布局默认值columns/style.scss列组的 flex 布局与移动端堆叠样式【免费下载链接】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/column 列块的多属性架构、静态标记与源码实现
Gutenberg 核心块深度解析core/column 列块的多属性架构、静态标记与源码实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergcore/column是 GutenbergWordPress 块编辑器项目中core/columns列组块的子容器块负责承载并渲染单个列内的嵌套内容。本文以该块的自动生成 API 文档为主体骨架结合当前仓库中 block.json、edit.jsx、save.jsx 等真实源码深入讲解其属性定义、能力支持Supports、序列化标记、编辑器交互逻辑与响应式样式帮助读者完整掌握这一静态块的设计与实现。块概览静态列块在 Gutenberg 中的定位根据 column/README.md 的官方定义core/column是columns 块中的一个单列A single column within a columns block。其核心元信息如下名称Namecore/column分类Categorydesign设计类API 版本API Version3对应 block.json 中的apiVersion: 3块类型Block Type静态块Static标记直接保存在文章内容中静态块的含义是块的最终 HTML 标记由save函数在保存时生成并写入post_content前端直接输出该标记不经过服务端渲染函数。这一点与动态块依赖 PHPrender_callback实时渲染形成对比也是理解下文Block Markup小节的基础。块关系core/column 与 core/columns 的父子契约文档明确指出core/column的直接父块Parent只有一个core/columns该约束定义在两个层面子块侧block.json 声明parent: [ core/columns ]即该块只允许作为core/columns的直接子块存在父块侧columns/block.json 声明allowedBlocks: [ core/column ]即core/columns只允许容纳core/column作为直接子块。这种双向约束保证了列组与列之间的严格层级关系columns直接包含多个column而每个column内部再通过InnerBlocks容纳段落paragraph、图片image等任意块。此外父块core/columns还提供了isStackedOnMobile移动端是否堆叠默认true属性与列间对齐能力与子块的verticalAlignment相互配合详见下文。Attributes 属性详解core/column的全部属性均通过 block.json 的attributes字段声明共三个Attribute类型枚举/说明默认值verticalAlignmentstring列内内容的垂直对齐方式top、center、bottom、stretch—widthstring列宽作为 CSSflex-basis使用支持%、px、em、rem、vw等长度单位—templateLockstring \| boolean内部块的模板锁定级别all、insert、contentOnly、false—三个属性的语义细节如下verticalAlignment垂直对齐控制列内内容在列高度方向上的对齐方式。在编辑器端edit.jsx通过BlockVerticalAlignmentToolbar提供[top, center, bottom, stretch]四个选项。值得注意的是设置列自身的对齐会同时重置父块core/columns的对齐属性——edit.jsx 中的updateAlignment先setAttributes更新自身再调用updateBlockAttributes( rootClientId, { verticalAlignment: null } )清除父块的统一对齐从而避免两级对齐设置相互冲突。width列宽flex-basis列宽以行内样式flex-basis的形式写入输出标记。源码对宽度值做了两类兼容处理数值类型向后兼容历史上API 版本 3 之前的模板中width可能是0–100的数字被视为百分比。当前 edit.jsx 与 save.jsx 均使用Number.isFinite( width ) ? width % : width将数字统一转换为百分数字符串百分比浮点精度修正save.jsx 中若宽度以%结尾且非整数会将其舍入到至多 12 位小数Math.round( parseFloat( width ) * 1e12 ) / 1e12 %避免长浮点数污染输出标记。在编辑器中宽度通过__experimentalUnitControl带单位输入框编辑可用单位由useSettings( spacing.units )读取兜底为[%, px, em, rem, vw]见 edit.jsx负数值会被钳制为0edit.jsx。templateLock模板锁定控制列内InnerBlocks的编辑约束取值与块 API 文档一致all完全锁定不可增删改内部块、insert禁止插入新块、contentOnly仅允许编辑内容不允许结构调整、false不锁定。该值会直接透传给编辑器端的useInnerBlocksPropsedit.jsx适合在主题模板中固定列内的块结构。Supports 能力支持详解core/column通过supports声明了丰富的样式与行为能力文档表格与 block.json 完全一致能力值说明anchortrue支持 HTML 锚点id可用于页内跳转reusablefalse禁用转为可复用块现为同步模式htmlfalse禁止自定义 HTML 编辑保证标记由块统一输出color.gradientstrue支持背景渐变color.headingtrue支持标题颜色color.buttontrue支持按钮颜色color.linktrue支持链接颜色shadowtrue支持阴影spacing.blockGaptrue支持列内块间距spacing.paddingtrue支持内边距typography.fontSizetrue支持字号typography.lineHeighttrue支持行高layouttrue支持布局控制interactivity.clientNavigationtrue支持客户端导航查看视图交互allowedBlockstrue支持限制内部允许的块类型在 block.json 中还存在文档表格之外的实验性支持项可作为深入了解的补充__experimentalOnEnter: true允许在列内按 Enter 换行__experimentalBordercolor / radius / style / width完整边框支持typography下的__experimentalFontFamily、__experimentalFontWeight、__experimentalFontStyle、__experimentalTextTransform、__experimentalTextDecoration、__experimentalLetterSpacing字体族、字重、字型、大小写变换、文本装饰与字间距color.__experimentalDefaultControlsbackground / text与spacing.__experimentalDefaultControlspadding / blockGap用于控制检查器中的默认显示。Block Markup静态标记与序列化格式作为静态块core/column的标记由保存端 save.jsx 生成并直接写入文章内容。文档给出的典型序列化标记为!-- wp:column -- div classwp-block-column !-- wp:paragraph -- pColumn One, Paragraph One/p !-- /wp:paragraph -- !-- wp:paragraph -- pColumn One, Paragraph Two/p !-- /wp:paragraph -- /div !-- /wp:column --要点解读!-- wp:column --与!-- /wp:column --是块的注释标记block comment delimiters包裹实际 DOM外层div固定携带wp-block-column类名由 save.jsx 的useBlockProps.save输出设置verticalAlignment时会追加is-vertically-aligned-top/center/bottom等类名save.jsx设置width时输出行内样式styleflex-basis: …save.jsx内部块通过useInnerBlocksProps.save递归序列化到div内save.jsx。历史标记迁移deprecated 机制仓库中 deprecated.jsx 记录了旧版块的标记形态早期width是number类型min: 0, max: 100直接输出style{ { flexBasis: width % } }。迁移逻辑migrate将数字转换为百分数字符串如50→50%isEligible通过isFinite( width )识别旧标记并触发自动迁移。这解释了为何当前源码需要反复兼容数字宽度这一历史形态。编辑器端实现宽度、对齐与 InnerBlocks 的协作编辑组件 edit.jsx 完整呈现了列块在编辑器中的交互逻辑宽度面板ColumnInspectorControls使用__experimentalToolsPanel与__experimentalToolsPanelItem提供可折叠的Settings面板其中UnitControl绑定width属性输入框宽度为calc(50% - 8px)支持选择器切换单位edit.jsx对齐工具栏BlockControls中的BlockVerticalAlignmentToolbar提供四个对齐按钮修改时同步清空父块core/columns的统一对齐edit.jsx行内样式通过useBlockProps将flexBasis注入编辑态 DOM确保编辑预览与前端输出一致edit.jsx嵌套容器useInnerBlocksProps接收templateLock、allowedBlocks并在无子块时渲染ButtonBlockAppender 添加按钮有子块时隐藏edit.jsx无障碍标签通过getBlockOrder计算列在父块中的位置生成形如Block: Column (1 of 3)的aria-label便于屏幕阅读器辨识当前列edit.jsx。块的注册入口在 index.js通过initBlock将metadata、edit、save、deprecated注册为core/column的设置对象init.js 负责在运行时完成初始化。响应式样式flex 布局与移动端堆叠列块的布局样式定义在父块样式文件 columns/style.scsswp-block-columns与wp-block-column共用桌面端≥break-medium即 ≥782px无显式宽度的列使用flex-basis: 0; flex-grow: 1均分剩余空间带flex-basis行内样式的列则flex-grow: 0保持固定宽度style.scss这正是width属性驱动列宽分配的原理移动端默认isStackedOnMobile为 true下列的flex-basis: 100% !important强制单列堆叠style.scss父块设置不在移动端堆叠时则flex-wrap: nowrap保持并排垂直对齐父块通过are-vertically-aligned-top/center/bottom类切换align-items列自身则通过is-vertically-aligned-*类由 save.jsx 输出控制内部内容的对齐。在模板与主题中使用 core/column由于块标记直接写入内容开发者可在主题模板如block.html中直接书写列结构。一个带宽度与模板锁定的示例!-- wp:columns -- div classwp-block-columns !-- wp:column {width:33.33%,templateLock:all} -- div classwp-block-column styleflex-basis:33.33% !-- wp:paragraph -- p侧栏内容/p !-- /wp:paragraph -- /div !-- /wp:column -- !-- wp:column {width:66.66%} -- div classwp-block-column styleflex-basis:66.66% !-- wp:paragraph -- p主内容区/p !-- /wp:paragraph -- /div !-- /wp:column -- /div !-- /wp:columns --其中!-- wp:column {width:33.33%,templateLock:all} --的 JSON 参数对应attributes中的属性名编辑器在加载时会按此解析属性并应用相应的行内样式与锁定策略。源码导航以下文件可供继续深入阅读column/README.md本块自动生成的 API 参考文档column/block.json属性与支持能力的唯一事实来源column/edit.jsx编辑器端渲染与交互逻辑column/save.jsx保存端的静态标记输出column/deprecated.jsx历史版本标记的向后兼容迁移column/index.js 与 column/init.js块的注册与初始化columns/block.json父块core/columns的元数据含isStackedOnMobile与布局默认值columns/style.scss列组的 flex 布局与移动端堆叠样式【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考