Gutenberg 区块编辑器 BlockCard 组件区块卡片 UI 的用法、Props 全解析与源码实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本文以 Gutenberg 仓库中block-card组件的官方文档为主体系统讲解BlockCard组件在区块检视器Block Inspector与插入器悬停预览两个场景中的用法并结合 组件源码 补全文档未覆盖的完整 Props包括已废弃的blockType、父级导航allowParentNavigation等帮助你能够在自定义区块编辑器 UI 中正确使用该组件并理解其背后依赖的编辑器数据流。组件定位区块信息的“名片”BlockCard是wordpress/block-editor包导出的组件用于渲染一张展示区块标题、图标与描述的“卡片”card。根据 组件文档它在编辑器中有两个固定的出现位置区块检视器Block Inspector选中某个区块后右侧检视面板顶部的卡片插入器悬停预览在插入面板Block Inserter中悬停某个区块时弹出的模态预览底部。从源码结构看这两个场景分别由以下文件消费该组件区块检视器packages/block-editor/src/components/block-inspector/index.jsximport BlockCard from ../block-card用于单区块检视时的卡片头部包括父/子区块的双卡片布局与区块状态控件插入器预览面板packages/block-editor/src/components/inserter/preview-panel.jsx在非复用区块的悬停预览中渲染标题、图标与描述。此外卡片所需的“显示信息”标题、图标、描述、是否同步区块等并非硬编码而是通过 useBlockDisplayInformation Hook 从编辑器数据中解析得出这一点后文会展开。基础用法文档给出的最小示例如下以默认样式渲染一张区块卡片传入图标、标题、描述与自定义名称。import { BlockCard } from wordpress/block-editor; import { paragraph } from wordpress/icons; const MyBlockCard () ( BlockCard icon{ paragraph } titleParagraph descriptionStart with the basic building block of all narrative. nameCustom Block / );需要注意的使用前提BlockCard属于 Block Editor 组件只能在BlockEditorProvider提供的组件树内使用。因为组件内部通过useSelect/useDispatch访问blockEditor数据 store见 源码脱离 Provider 环境将无法正常工作。Props 完整解析文档列出了 4 个基础 Props源码的 JSDoc 注释还补充了若干文档未提及的 Props。下面将两者合并以当前仓库源码为准icon类型String|Object区块图标。可以是 WordPress Dashicons 的名称也可以是自定义的svg元素。从源码看该值最终被传给内部BlockIcon组件并附加showColors因此支持彩色图标见 index.jsx 第 173 行。title类型String区块标题。源码中当同时传入name且卡片不是父/子卡片时name显示为主标题文本title会以Badge徽标形式附在标题之后见 index.jsx 第 175-184 行。description类型String区块描述。注意源码中的渲染条件只有当卡片既不是父卡片parentClientId也不是子卡片isChild时才渲染描述文本index.jsx 第 191-195 行。这意味着在父/子双卡片布局中描述会被省略以压缩空间。name类型String显示在标题前的自定义区块名称。典型来源是区块的metadata.name例如复用区块/模板部件实例的自定义标签由useBlockDisplayInformation解析后传入。blockType已废弃类型Object可选状态自 Gutenberg 5.7 起废弃源码中保留了兼容性逻辑若传入blockType会调用deprecated()发出警告并从该对象上解构出title、icon、description三个属性作为替代index.jsx 第 83-89 行。官方建议的替代方案是直接传入title、icon、description三个独立 Props。新代码不应再使用此 Props。className类型String可选附加到卡片根元素的类名与内置的block-editor-block-card、is-parent、is-child等类名合并通过clsx。在区块检视器中同步复用/模板部件区块会附加is-synced类使图标着色为--wp-block-synced-color见 style.scss 第 52-54 行。allowParentNavigation类型StringJSDoc 标注实为布尔语义可选允许卡片在特定情境下显示“返回父区块”的箭头。启用后组件会通过unlock( select( blockEditorStore ) )获取getBlockParents、getBlockName、shouldRenderBlockListView三个未公开 API找到最靠近当前clientId的、参与 List View 的祖先区块作为parentBlockClientId渲染一个带chevronLeft/chevronRight图标的小按钮RTL 布局下箭头方向自动反转点击后调用selectBlock( parentBlockClientId )将选中态跳回父区块index.jsx 第 91-113 行 与 第 133-156 行。按钮的label会通过getBlockType( parentBlockName )?.title生成为Go to %s block找不到父区块时回退为Go to parent block。parentClientId类型String可选当卡片表示的是父区块时传入其clientId。此时根元素附加is-parent类标题元素由h2降级为div避免嵌套标题层级问题见 index.jsx 第 117 行图标与标题整体被包裹进一个OptionalParentSelectButton点击后selectBlock( parentClientId )第 164-172 行不渲染描述文本。isChild类型StringJSDoc 标注实为布尔语义可选标识卡片代表一个子区块。此时根元素附加is-child类并在标题左侧渲染一个箭头指示图标RTL 布局下方向反转用于视觉缩进表达“从属于父卡片”index.jsx 第 157-163 行。clientId类型String可选当前区块的clientId。它是allowParentNavigation生效的前提——组件据此在useSelect中查找祖先链依赖数组见 第 112 行。controls类型Element可选渲染在区块标题右侧的控件区域位于标题行的space-between布局的右端。区块检视器在此挂载BlockStatesControl区块样式状态选择器见 block-inspector/index.jsx 第 472-503 行。children类型Element可选渲染在标题下方的插槽内容。真实场景一区块检视器中的双卡片布局区块检视器是BlockCard最复杂的使用方。在 BlockInspectorSingleBlock 中可以看到两种典型传参模式子区块卡片父级 section 存在时{ hasParentChildBlockCards ( BlockCard { ...parentBlockInformation } className{ parentBlockInformation?.isSynced is-synced } parentClientId{ editedContentOnlySection } / ) }当前选中区块卡片BlockCard { ...blockInformation } description{ showStateBadges ? undefined : blockInformation.description } allowParentNavigation className{ isBlockSynced is-synced } isChild{ hasParentChildBlockCards } clientId{ renderedBlockClientId } controls{ /* BlockStatesControl 区块状态控件 */ } /其中hasParentChildBlockCards由editedContentOnlySection被编辑内容的 section 区块与renderedBlockClientId不相等推导而来blockInformation/parentBlockInformation分别来自两次useBlockDisplayInformation调用处于样式状态编辑时showStateBadges为真描述被置为undefined由下方的状态徽标BlockStateBadges替代显示。这解释了前面提到的渲染规则父卡片因带parentClientId而省略描述子卡片因isChild带箭头缩进且省略描述二者上下堆叠is-parent减少底部内边距、is-child减少顶部内边距见 style.scss 第 8-14 行。真实场景二插入器悬停预览InserterPreviewPanel 在用户悬停插入面板中的区块项时渲染若该区块项有example或是复用区块isReusableBlock( item )上半部分渲染BlockPreview基于getBlockFromExample构建示例块并按侧边栏宽度缩放否则无预览可用显示No preview available.文案非复用区块时底部渲染BlockCard直接传入title、icon、description三个基础 Props{ ! isReusable ( BlockCard title{ title } icon{ icon } description{ description } / ) }这是文档所述“作为模态出现”的场景的最小化用法。数据来源useBlockDisplayInformation区块检视器中BlockCard收到的title/icon/description/name等并非来自区块类型定义本身而是由 useBlockDisplayInformation Hook 按clientId解析。其解析优先级从源码结构看为图案Pattern若区块属性含metadata.patternName且该区块是 section 区块标题固定为 “Pattern”图标为symbol名称取图案标题或metadata.name激活的区块变体Variation通过getActiveBlockVariation( blockName, attributes, undefined, innerContent )匹配变体命中后标题、图标、描述均优先取变体定义match.title || blockType.title等形式区块类型回退均不命中时回退到blockType的title、icon、description。此外该 Hook 还会计算isSyncedisReusableBlock( blockType ) || isTemplatePart( blockType )即复用区块或模板部件同步区块的title通过getBlockLabel( blockType, attributes )生成通常是自定义标签name来自attributes?.metadata?.namepositionLabel/positionType当attributes.style.position.type为sticky或fixed时分别返回 “Sticky” / “Fixed”。理解这条数据链有助于解释为什么同一区块类型在不同变体或自定义名称下检视器卡片显示的标题与名称会不同。样式结构速览style.scss 定义的类名结构如下便于在自定义 CSS 中做定位覆盖类名作用.block-editor-block-card卡片根元素内边距$grid-unit-20.block-editor-block-card.is-parent父卡片底部内边距缩小.block-editor-block-card.is-child子卡片顶部内边距缩小.block-editor-block-card__parent-select-button父卡片图标/标题的可点击按钮去除默认按钮内边距.block-editor-block-card__title标题行flex 布局、可换行、overflow-wrap: anywhere.block-editor-block-card__name主名称文本3px 垂直内边距使标题与图标等高.block-editor-block-card .block-editor-block-icon/__child-indicator-icon图标与子区块箭头尺寸固定为$button-size-small.block-editor-block-card.is-synced .block-editor-block-icon同步区块图标着色var(--wp-block-synced-color)相关组件BlockCard与以下组件紧密协作BlockEditorProvider使用BlockCard的前提环境组件树必须位于其下BlockIconpackages/block-editor/src/components/block-icon/卡片内图标的实际渲染者BlockInspectorpackages/block-editor/src/components/block-inspector/卡片的主要宿主InserterPreviewPanelpackages/block-editor/src/components/inserter/preview-panel.jsx插入器悬停预览的宿主useBlockDisplayInformationpackages/block-editor/src/components/use-block-display-information/index.js为卡片提供动态标题、图标与名称。小结BlockCard是 Gutenberg 区块编辑器中承载“区块身份展示”的轻量组件。对文档中列出的icon、title、description、name四个基础 Props源码还补充了blockType已废弃、className、allowParentNavigation、parentClientId、isChild、clientId、controls、children等能力支撑了检视器中的父/子双卡片导航与插入器悬停预览两类核心场景。开发自定义检视器 UI 或需要展示区块元信息时建议在BlockEditorProvider环境下优先复用该组件并以独立 Props 替代已废弃的blockType传参方式。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 7:31:50 · 阅读 1.2k Gutenberg 区块编辑器 BlockCard 组件：区块卡片 UI 的用法、Props 全解析与源码实现
Gutenberg 区块编辑器 BlockCard 组件区块卡片 UI 的用法、Props 全解析与源码实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本文以 Gutenberg 仓库中block-card组件的官方文档为主体系统讲解BlockCard组件在区块检视器Block Inspector与插入器悬停预览两个场景中的用法并结合 组件源码 补全文档未覆盖的完整 Props包括已废弃的blockType、父级导航allowParentNavigation等帮助你能够在自定义区块编辑器 UI 中正确使用该组件并理解其背后依赖的编辑器数据流。组件定位区块信息的“名片”BlockCard是wordpress/block-editor包导出的组件用于渲染一张展示区块标题、图标与描述的“卡片”card。根据 组件文档它在编辑器中有两个固定的出现位置区块检视器Block Inspector选中某个区块后右侧检视面板顶部的卡片插入器悬停预览在插入面板Block Inserter中悬停某个区块时弹出的模态预览底部。从源码结构看这两个场景分别由以下文件消费该组件区块检视器packages/block-editor/src/components/block-inspector/index.jsximport BlockCard from ../block-card用于单区块检视时的卡片头部包括父/子区块的双卡片布局与区块状态控件插入器预览面板packages/block-editor/src/components/inserter/preview-panel.jsx在非复用区块的悬停预览中渲染标题、图标与描述。此外卡片所需的“显示信息”标题、图标、描述、是否同步区块等并非硬编码而是通过 useBlockDisplayInformation Hook 从编辑器数据中解析得出这一点后文会展开。基础用法文档给出的最小示例如下以默认样式渲染一张区块卡片传入图标、标题、描述与自定义名称。import { BlockCard } from wordpress/block-editor; import { paragraph } from wordpress/icons; const MyBlockCard () ( BlockCard icon{ paragraph } titleParagraph descriptionStart with the basic building block of all narrative. nameCustom Block / );需要注意的使用前提BlockCard属于 Block Editor 组件只能在BlockEditorProvider提供的组件树内使用。因为组件内部通过useSelect/useDispatch访问blockEditor数据 store见 源码脱离 Provider 环境将无法正常工作。Props 完整解析文档列出了 4 个基础 Props源码的 JSDoc 注释还补充了若干文档未提及的 Props。下面将两者合并以当前仓库源码为准icon类型String|Object区块图标。可以是 WordPress Dashicons 的名称也可以是自定义的svg元素。从源码看该值最终被传给内部BlockIcon组件并附加showColors因此支持彩色图标见 index.jsx 第 173 行。title类型String区块标题。源码中当同时传入name且卡片不是父/子卡片时name显示为主标题文本title会以Badge徽标形式附在标题之后见 index.jsx 第 175-184 行。description类型String区块描述。注意源码中的渲染条件只有当卡片既不是父卡片parentClientId也不是子卡片isChild时才渲染描述文本index.jsx 第 191-195 行。这意味着在父/子双卡片布局中描述会被省略以压缩空间。name类型String显示在标题前的自定义区块名称。典型来源是区块的metadata.name例如复用区块/模板部件实例的自定义标签由useBlockDisplayInformation解析后传入。blockType已废弃类型Object可选状态自 Gutenberg 5.7 起废弃源码中保留了兼容性逻辑若传入blockType会调用deprecated()发出警告并从该对象上解构出title、icon、description三个属性作为替代index.jsx 第 83-89 行。官方建议的替代方案是直接传入title、icon、description三个独立 Props。新代码不应再使用此 Props。className类型String可选附加到卡片根元素的类名与内置的block-editor-block-card、is-parent、is-child等类名合并通过clsx。在区块检视器中同步复用/模板部件区块会附加is-synced类使图标着色为--wp-block-synced-color见 style.scss 第 52-54 行。allowParentNavigation类型StringJSDoc 标注实为布尔语义可选允许卡片在特定情境下显示“返回父区块”的箭头。启用后组件会通过unlock( select( blockEditorStore ) )获取getBlockParents、getBlockName、shouldRenderBlockListView三个未公开 API找到最靠近当前clientId的、参与 List View 的祖先区块作为parentBlockClientId渲染一个带chevronLeft/chevronRight图标的小按钮RTL 布局下箭头方向自动反转点击后调用selectBlock( parentBlockClientId )将选中态跳回父区块index.jsx 第 91-113 行 与 第 133-156 行。按钮的label会通过getBlockType( parentBlockName )?.title生成为Go to %s block找不到父区块时回退为Go to parent block。parentClientId类型String可选当卡片表示的是父区块时传入其clientId。此时根元素附加is-parent类标题元素由h2降级为div避免嵌套标题层级问题见 index.jsx 第 117 行图标与标题整体被包裹进一个OptionalParentSelectButton点击后selectBlock( parentClientId )第 164-172 行不渲染描述文本。isChild类型StringJSDoc 标注实为布尔语义可选标识卡片代表一个子区块。此时根元素附加is-child类并在标题左侧渲染一个箭头指示图标RTL 布局下方向反转用于视觉缩进表达“从属于父卡片”index.jsx 第 157-163 行。clientId类型String可选当前区块的clientId。它是allowParentNavigation生效的前提——组件据此在useSelect中查找祖先链依赖数组见 第 112 行。controls类型Element可选渲染在区块标题右侧的控件区域位于标题行的space-between布局的右端。区块检视器在此挂载BlockStatesControl区块样式状态选择器见 block-inspector/index.jsx 第 472-503 行。children类型Element可选渲染在标题下方的插槽内容。真实场景一区块检视器中的双卡片布局区块检视器是BlockCard最复杂的使用方。在 BlockInspectorSingleBlock 中可以看到两种典型传参模式子区块卡片父级 section 存在时{ hasParentChildBlockCards ( BlockCard { ...parentBlockInformation } className{ parentBlockInformation?.isSynced is-synced } parentClientId{ editedContentOnlySection } / ) }当前选中区块卡片BlockCard { ...blockInformation } description{ showStateBadges ? undefined : blockInformation.description } allowParentNavigation className{ isBlockSynced is-synced } isChild{ hasParentChildBlockCards } clientId{ renderedBlockClientId } controls{ /* BlockStatesControl 区块状态控件 */ } /其中hasParentChildBlockCards由editedContentOnlySection被编辑内容的 section 区块与renderedBlockClientId不相等推导而来blockInformation/parentBlockInformation分别来自两次useBlockDisplayInformation调用处于样式状态编辑时showStateBadges为真描述被置为undefined由下方的状态徽标BlockStateBadges替代显示。这解释了前面提到的渲染规则父卡片因带parentClientId而省略描述子卡片因isChild带箭头缩进且省略描述二者上下堆叠is-parent减少底部内边距、is-child减少顶部内边距见 style.scss 第 8-14 行。真实场景二插入器悬停预览InserterPreviewPanel 在用户悬停插入面板中的区块项时渲染若该区块项有example或是复用区块isReusableBlock( item )上半部分渲染BlockPreview基于getBlockFromExample构建示例块并按侧边栏宽度缩放否则无预览可用显示No preview available.文案非复用区块时底部渲染BlockCard直接传入title、icon、description三个基础 Props{ ! isReusable ( BlockCard title{ title } icon{ icon } description{ description } / ) }这是文档所述“作为模态出现”的场景的最小化用法。数据来源useBlockDisplayInformation区块检视器中BlockCard收到的title/icon/description/name等并非来自区块类型定义本身而是由 useBlockDisplayInformation Hook 按clientId解析。其解析优先级从源码结构看为图案Pattern若区块属性含metadata.patternName且该区块是 section 区块标题固定为 “Pattern”图标为symbol名称取图案标题或metadata.name激活的区块变体Variation通过getActiveBlockVariation( blockName, attributes, undefined, innerContent )匹配变体命中后标题、图标、描述均优先取变体定义match.title || blockType.title等形式区块类型回退均不命中时回退到blockType的title、icon、description。此外该 Hook 还会计算isSyncedisReusableBlock( blockType ) || isTemplatePart( blockType )即复用区块或模板部件同步区块的title通过getBlockLabel( blockType, attributes )生成通常是自定义标签name来自attributes?.metadata?.namepositionLabel/positionType当attributes.style.position.type为sticky或fixed时分别返回 “Sticky” / “Fixed”。理解这条数据链有助于解释为什么同一区块类型在不同变体或自定义名称下检视器卡片显示的标题与名称会不同。样式结构速览style.scss 定义的类名结构如下便于在自定义 CSS 中做定位覆盖类名作用.block-editor-block-card卡片根元素内边距$grid-unit-20.block-editor-block-card.is-parent父卡片底部内边距缩小.block-editor-block-card.is-child子卡片顶部内边距缩小.block-editor-block-card__parent-select-button父卡片图标/标题的可点击按钮去除默认按钮内边距.block-editor-block-card__title标题行flex 布局、可换行、overflow-wrap: anywhere.block-editor-block-card__name主名称文本3px 垂直内边距使标题与图标等高.block-editor-block-card .block-editor-block-icon/__child-indicator-icon图标与子区块箭头尺寸固定为$button-size-small.block-editor-block-card.is-synced .block-editor-block-icon同步区块图标着色var(--wp-block-synced-color)相关组件BlockCard与以下组件紧密协作BlockEditorProvider使用BlockCard的前提环境组件树必须位于其下BlockIconpackages/block-editor/src/components/block-icon/卡片内图标的实际渲染者BlockInspectorpackages/block-editor/src/components/block-inspector/卡片的主要宿主InserterPreviewPanelpackages/block-editor/src/components/inserter/preview-panel.jsx插入器悬停预览的宿主useBlockDisplayInformationpackages/block-editor/src/components/use-block-display-information/index.js为卡片提供动态标题、图标与名称。小结BlockCard是 Gutenberg 区块编辑器中承载“区块身份展示”的轻量组件。对文档中列出的icon、title、description、name四个基础 Props源码还补充了blockType已废弃、className、allowParentNavigation、parentClientId、isChild、clientId、controls、children等能力支撑了检视器中的父/子双卡片导航与插入器悬停预览两类核心场景。开发自定义检视器 UI 或需要展示区块元信息时建议在BlockEditorProvider环境下优先复用该组件并以独立 Props 替代已废弃的blockType传参方式。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考