Gutenberg 块编辑模式Block Editing Mode权威指南从useBlockEditingMode到编辑器状态管理的完整解析【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberguseBlockEditingMode是 Gutenberg 块编辑器Block Editor中一个高度专用的 React Hook它用于读取——或按需设置——单个块的编辑模式。该模式决定了在编辑器中为这一块呈现何种用户界面是完全禁用编辑、仅保留内容编辑、还是恢复默认的完整编辑体验。本文以 block-editing-mode 组件文档 为核心骨架深入剖析三种模式disabled、contentOnly、default的语义、继承规则、派生机制以及从 Hook 到 Store、再到 Reducer 的完整实现链路并通过仓库内的真实源码与测试用例验证每一项结论帮助你掌握在自定义块中精准控制编辑体验的实战能力。一、什么是 Block Editing ModeBlock Editing Mode 是块编辑器用来约束某个块编辑界面的一类状态。它本身不改变块的内容或保存结果只决定用户在编辑器中面对什么样的 UI 与交互能力。从文档定义看模式共有三个取值取值含义disabled完全禁止编辑该块即该块无法被选中更不能修改contentOnly隐藏所有非内容 UI例如工具栏中的辅助控件、块的移动手柄block movers、块设置面板等default允许该块正常编辑即完整的默认编辑体验文档明确指出该 Hook 的核心价值在于模式只约束“界面”因此非常适合用来为特定块打造“专注内容”的编辑体验——比如在站点编辑器的内容锁定场景下只允许用户修改段落文本而隐藏排版、颜色等结构性控件。1.1 与“块锁定”的关系Block Editing Mode 与templateLock模板锁定和块锁定Block Lock是两个紧密相关但职责不同的机制templateLock: contentOnly是触发派生模式的关键源头详见第三节块锁定lock属性控制的是移动、移除等操作权限而编辑模式控制的是“界面可见性”。从 store 私有选择器 的注释可以看到两者的明确分工isBlockLockedByUser这类选择器“只考虑 block lock不考虑blockEditingMode等可能阻止用户修改块的功能”原因在于编辑模式是用户无法通过 UI 修改的——它由块自身声明或由系统派生。二、Hook 实战读取与设置编辑模式2.1 读取当前模式最常见用法无参数调用时Hook 返回当前块的编辑模式这也是最常用的用法块根据模式决定是否渲染某些控件。import { BlockControls, useBlockEditingMode, useBlockProps, } from wordpress/block-editor; function MyBlock( { attributes, setAttributes } ) { const blockEditingMode useBlockEditingMode(); return ( { blockEditingMode default ( BlockControls groupblock MyToolbarControl / /BlockControls ) } div { ...useBlockProps() }/div / ); }当模式为contentOnly或disabled时BlockControls中的自定义工具栏控件被隐藏只有default模式才显示完整控件。这一模式在核心块库中被大量采用例如音频块 edit.jsx 中hasNonContentControls blockEditingMode default用于决定是否渲染替换媒体等非内容控件封面块 edit/index.jsx 同样以blockEditingMode default判定是否显示非内容控件手风琴块 edit.jsx 通过blockEditingMode contentOnly判断是否处于内容限定模式。这些用法印证了文档的说法读取模式、按需隐藏控件是绝大多数场景下的首选方式。2.2 设置模式声明式向 Hook 传入一个模式值即可为该块设置编辑模式import { useBlockEditingMode, useBlockProps, } from wordpress/block-editor; function MyBlock( { attributes, setAttributes } ) { useBlockEditingMode( disabled ); return div { ...useBlockProps() }/div; }调用useBlockEditingMode( disabled )后该块被完全禁止编辑既不能选中也无法修改内容。文档强调传入undefined时当前模式保持不变——这是“读取模式”与“设置模式”共用一个 API 的关键约定。2.3 参数与返回值速查项目说明mode类型Stringmode默认值undefined仅读取不改变当前模式mode可选值disabled、contentOnly、default返回值String即当前块的实际编辑模式2.4 源码级实现剖析Hook 的真实实现位于 block-editing-mode/index.js其核心逻辑可分为三部分上下文读取通过useBlockEditContext()取得当前编辑上下文若上下文中没有clientId即空字符串说明调用点不在任何块内部。全局模式订阅仅在clientId为空时才通过useSelect订阅getBlockEditingMode()选择器获取编辑器根节点的模式注释明确说明这是“避免不必要的订阅”。声明式副作用当传入mode时借助useEffect调用setBlockEditingMode( clientId, mode )派发 action组件卸载或mode变化时调用unsetBlockEditingMode( clientId )清理该块的模式。两次变更都被标记为__unstableMarkNextChangeAsNotPersistent()即不进入撤销/重做历史。返回值逻辑同样值得注意clientId存在时返回context[ blockEditingModeKey ]上下文缓存的模式否则返回全局模式。这个blockEditingModeKey是一个Symbol在 block-edit/context.js 中定义并在 block-edit/index.jsx 中由Edit组件写入上下文供整棵渲染子树共享。三、模式的继承与传播规则3.1 内嵌块不级联只有一个例外文档给出了两条关键规则模式不会级联到内嵌块唯一的例外一个块被设置为disabled时其内嵌块也会被禁用——除非该内嵌块显式声明了自己的模式。也就是说contentOnly不会自动传播给子块而disabled会向下传播但显式设置优先级更高。这一规则在 Reducer 中有精确对应。在 store/reducer.js 的getDerivedBlockEditingModesForTree中// Disabled explicit block editing modes are inherited by children. // Its an expensive calculation, so only do it if there are disabled blocks. if ( hasDisabledBlocks ) { // 从父链向上查找最近的显式模式 let ancestorBlockEditingMode; let parent state.blocks.parents.get( clientId ); while ( parent ! undefined ) { if ( state.blocks.blockEditingModes.has( parent ) ) { ancestorBlockEditingMode state.blocks.blockEditingModes.get( parent ); } if ( ancestorBlockEditingMode ) { break; } parent state.blocks.parents.get( parent ); } // 只有祖先是 disabled 时才继承 if ( ancestorBlockEditingMode disabled ) { derivedBlockEditingModes.set( clientId, disabled ); return; } }代码注释“Disabled explicit block editing modes are inherited by children”与文档规则完全一致且实现上有两个细节值得注意该计算“比较昂贵”因此仅当状态中确实存在disabled块时hasDisabledBlocks才执行父链遍历父链遍历找到最近的显式模式即停止且只继承disabledcontentOnly不会向下传播。3.2 编辑器根节点全局模式如果 Hook 在块上下文之外调用即没有clientId模式会被设置到编辑器根节点clientId 。根节点遵循同样的规则根节点为disabled→所有块都被禁用根节点为contentOnly→不会传播到各块。这与上一节的内嵌规则一致disabled向下传播、contentOnly不传播。测试用例也覆盖了这一点例如 selectors.jsdom.test.jsx 中构造了blockEditingModes: new Map( [ [ , disabled ] ] )的全局禁用状态来验证选择器行为。3.3 派生模式Derived Modes除了块自身显式声明模式还可以派生而来。文档指出在templateLock: contentOnly祖先之下未显式声明模式的块会被派生出模式若该块是内容块拥有role: content的属性或声明了supports.contentRole则派生为contentOnly否则派生为disabled显式声明的模式优先于派生模式。从源码看这一逻辑实现在 store/reducer.js 的contentOnlyParents分支if ( contentOnlyParents.length ) { const hasContentOnlyParent !! findParentInClientIdsList( state, clientId, contentOnlyParents ); if ( hasContentOnlyParent ) { if ( isContentBlock( blockName ) ) { derivedBlockEditingModes.set( clientId, contentOnly ); } else { derivedBlockEditingModes.set( clientId, disabled ); } } }而遍历开始处还有一个关键前置判断// If the block already has an explicit block editing mode set, // dont override it. if ( state.blocks.blockEditingModes.has( clientId ) ) { return; }正是这行“显式优先”的保护实现了文档所说的“An explicitly set mode wins over these derived modes”。值得注意的是contentOnlyParents的构成比文档描述更丰富它聚合了三类来源contentOnlyTemplateLockedClientIdstemplateLock: contentOnly的块unsyncedPatternClientIds非同步模式块通过attributes.metadata.patternName标识templatePartClientIds模板部件受disableContentOnlyForTemplateParts设置控制。也就是说文档中提到的templateLock: contentOnly是派生模式的主要但非唯一来源——非同步模式和模板部件也参与派生。3.4 内容块的判定“内容块”的判定实现在 blocks 包的 utils.ts 的isContentBlockexport function isContentBlock( name: string ): boolean { const blockType getBlockType( name ); const attributes blockType?.attributes; // 并非所有块都有属性但它们可能支持 contentRole。 const supportsContentRole blockType?.supports?.contentRole; if ( supportsContentRole ) { // ... } // 否则检查是否存在 role: content 的属性 }该函数被锁定为私有 APIapi/index.ts 中的privateApis供 block-editor 的 Reducer、选择器与私有选择器通过unlock( blocksPrivateApis )调用。相关单元测试位于 utils.jsdom.test.js 的isContentBlock用例覆盖了“拥有 content role 属性返回 true”与“没有则返回 false”两种情形。四、Store 层的完整实现链路4.1 两个状态容器显式模式与派生模式从 Reducer 与选择器的结构看Block Editing Mode 在状态中分两处存储state.blocks.blockEditingModes一个MapclientId, mode记录显式声明的模式SET_BLOCK_EDITING_MODE/UNSET_BLOCK_EDITING_MODE两个 action 维护state.derivedBlockEditingModes一个MapclientId, mode记录派生的模式由withDerivedBlockEditingModes高阶 Reducer 维护。getBlockEditingMode选择器selectors.js按顺序合并两者export function getBlockEditingMode( state, clientId ) { if ( clientId null ) { clientId ; } // 先查派生模式同步模式、缩放模式等场景 if ( state.derivedBlockEditingModes?.has( clientId ) ) { return state.derivedBlockEditingModes.get( clientId ); } // 再查显式模式 if ( state.blocks.blockEditingModes.has( clientId ) ) { return state.blocks.blockEditingModes.get( clientId ); } // 都没有则默认 default return default; }注意这里的查询顺序派生模式优先于显式模式。这与 Hook 与文档中“显式模式优先”的表述并不矛盾——因为派生模式的产生过程本身就排除了“已显式声明”的块Reducer 中的if ( state.blocks.blockEditingModes.has( clientId ) ) return;所以两条路径永远不会对一个块同时生效选择器的顺序只是兜底保证。4.2 派生模式的维护高阶 ReducerwithDerivedBlockEditingModesstore/reducer.js是一个包裹原 Reducer 的高阶函数其核心职责是当块树发生变化时增量更新派生模式而不是每次全量重算REMOVE_BLOCKS删除被移除子树中所有块的派生模式先删除、后添加以正确处理MOVE_BLOCKS_TO_POSITION这类“先删后加”的动作RECEIVE_BLOCKS/INSERT_BLOCKS对新插入的块树计算派生模式UPDATE_BLOCK_ATTRIBUTES处理非同步模式块的metadata.patternName属性增删同步更新派生模式受disableContentOnlyForUnsyncedPatterns设置开关控制。此外还有一个特例当SET_EDITOR_MODE动作发生时即使nextState state也要重算因为编辑器模式如缩放模式 zoomed out不存储在 block-editor 状态中改变它不会产生新状态却会影响派生模式——例如缩放模式下section 根块派生出contentOnly非 section 块派生为disabled。4.3 显式模式的维护Reducer 与 Actions显式模式由 reducer.js 的blockEditingModes子 Reducer 处理两个 actionSET_BLOCK_EDITING_MODE写入Map若模式相同则短路返回原状态UNSET_BLOCK_EDITING_MODE从Map中删除。对应地actions.js 导出setBlockEditingMode( clientId , mode )与unsetBlockEditingMode( clientId )两个 action creator默认clientId都是根节点。Reducer 测试reducer.js 测试 的blockEditingModes用例验证了默认返回空MapSET_BLOCK_EDITING_MODE正确写入UNSET_BLOCK_EDITING_MODE正确删除重置块时保留仍然存在块的模式、清除已删除块的模式。4.4 显式模式覆盖派生模式的测试佐证store/test/reducer.js 中有一组非常直接的用例标题即是文档规则的测试化表达allows explicitly set blockEditingModes to override the contentOnly template locking——显式模式覆盖contentOnly模板锁定派生的模式allows explicitly set blockEditingModes to override the unsynced pattern editing modes——覆盖非同步模式派生allows explicitly set blockEditingModes to override the template part editing modes——覆盖模板部件派生。这三条用例共同构成了“显式优先”原则的完整测试覆盖。五、编辑模式如何影响编辑器行为模式并非孤立的“状态标签”它被数十个选择器、Hooks 与 UI 组件读取直接决定编辑器的具体行为。以下是几个有代表性的消费方canEditBlock/canRemoveBlock/canMoveBlockselectors.js当根块的编辑模式为disabled时块不可编辑、不可移动、不可删除直接阻断结构性的修改操作isBlockSubtreeDisabledprivate-selectors.js递归判断子树是否整体禁用供列表视图等场景使用getEnabledBlockParents同上过滤掉disabled祖先用于定位“可编辑的”有效父链选择覆盖层判断selectors.js当模式不是default时返回false因为“如果模式是disabled覆盖层是多余的块无法被选中如果是contentOnly选中后也没有可交互的控件”——这是 UI 层对模式的直接响应插入判断private-selectors.js 的isContainerInsertableToInContentOnlyModecontentOnly模式下容器块只允许插入内容块且对 section 块有特殊处理section 块的模式是defaultcontentOnly只设置在其子块上拖拽排序actions.jsmoveBlocksToPosition会先检查两个块的模式任一为disabled则直接返回阻止移动样式 Hookhooks/style.jsx通过useBlockEditingMode()决定是否渲染块样式相关的全局样式控件。这些消费方的存在说明编辑模式是一个横跨“可否操作”与“显示什么”两个维度的统一开关。六、常见场景与实战建议6.1 只读块禁用编辑useBlockEditingMode( disabled );适合需要“展示但不可交互”的场景如统计信息、徽章、只读的引用块。注意disabled会连带禁用内嵌块若某内嵌块需要保留编辑能力需在其内部显式设置default显式优先于继承。6.2 内容专注模式隐藏结构控件useBlockEditingMode( contentOnly );适合想让用户只关注内容本身的场景工具栏辅助控件、移动手柄、块设置面板全部隐藏。注意它不会向下传播子块各自独立判断。6.3 条件渲染工具栏控件const blockEditingMode useBlockEditingMode(); return ( { blockEditingMode default ( BlockControls groupblock MyToolbarControl / /BlockControls ) } div { ...useBlockProps() }/div / );这是最常见的组合用法读取模式、按需显示控件核心块库中大量采用此模式。6.4 与模板锁定的配合若要为整棵子树开启内容专注体验可以在父块上使用templateLock: contentOnly未显式声明模式的子块会被自动派生为contentOnly内容块或disabled非内容块而显式声明的块不受影响。这是文档明确推荐的组合方式。七、小结Block Editing Mode 是 Gutenberg 中“界面约束”与“操作约束”的统一抽象三种模式disabled/contentOnly/default分别对应禁止编辑、内容专注、完整编辑继承规则简单但精确disabled向下传播contentOnly不传播显式声明永远优先派生机制让templateLock: contentOnly、非同步模式、模板部件、缩放模式等场景无需块自身参与即可获得正确的编辑约束实现层面由useBlockEditingModeHook、getBlockEditingMode选择器、blockEditingModes与derivedBlockEditingModes双状态 Map、withDerivedBlockEditingModes高阶 Reducer共同支撑完整链路可从 block-editing-mode/index.js 一路追踪到 store/reducer.js 与 store/selectors.js。对自定义块开发者而言理解这一机制意味着你可以在不破坏编辑器整体一致性的前提下为特定块精确裁剪编辑体验——既符合 Gutenberg 的设计哲学也经得起真实用户场景的考验。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考