Gutenberg 导航遮罩关闭块core/navigation-overlay-close全解析属性、编辑器 UI 与服务端渲染实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergcore/navigation-overlay-close是 GutenbergWordPress 块编辑器中用于关闭导航遮罩Navigation Overlay的专用按钮块它解决了移动端/小屏导航菜单展开后“如何一键收起”这一交互问题。本文以 packages/block-library/src/navigation-overlay-close/README.md 为骨架结合该块的block.json、编辑器端edit.jsx、服务端index.php与样式源码逐层拆解它的元数据声明、属性与 Supports 配置、编辑器界面、服务端渲染逻辑以及“仅在导航遮罩模板部件内可插入”的约束机制帮助你彻底理解并能够自定义这一动态块。块概览一个动态渲染的“关闭按钮”从 README 中可以看到该块的核心元信息名称Namecore/navigation-overlay-close分类Categorydesign设计API 版本API Version3块类型Block TypeDynamic动态块由服务端渲染不在文章内容中保存 HTML关键词Keywordsclose、overlay、navigation、menu这些声明定义在 block.json 中$schema: https://schemas.wp.org/trunk/block.json服务端通过register_block_type_from_metadata()读取该文件完成注册前端注册则由 index.js 中的init()调用initBlock()完成。“Dynamic / 服务端渲染”意味着它属于动态块文章内容里只保存块注释不保存最终 HTML。块标记Block Markup为!-- wp:navigation-overlay-close /--最终渲染出的button按钮由服务端在请求时生成。这也是为什么关闭按钮上的文案“Close”能随站点语言自动翻译的原因之一——服务端渲染的默认文本走的是 WordPress 的 i18n 机制。属性Attributes详解displayMode 与 textREADME 中给出了该块的两个属性完整定义位于 block.json属性类型默认值说明displayModestringicon枚举Enumicon、text、bothtextstring—自定义关闭按钮文案displayMode决定按钮呈现形式。icon只显示关闭图标×text只显示文字both同时显示图标与文字。type声明为string并通过enum做取值校验在 block 编辑器中这一约束会阻止属性被设为枚举之外的值。text关闭按钮的自定义文案。默认值为空为空时服务端与编辑器都会回退到翻译后的Close。属性在编辑器与服务端是如何被消费的编辑器端edit.jsx中const { displayMode, text } attributes; const showIcon displayMode icon || displayMode both; const showText displayMode text || displayMode both; // Use translated default if text is empty const displayText text || __( Close );服务端index.php中同样处理$text empty( $attributes[text] ) ? __( Close ) : $attributes[text]; $display_mode empty( $attributes[displayMode] ) ? icon : $attributes[displayMode]; $show_icon both $display_mode || icon $display_mode; $show_text both $display_mode || text $display_mode;可以看到编辑器与服务端对属性的解释完全一致保证了“所见即所得”编辑器中预览的图标/文字组合与前端渲染结果一一对应。Supports 支持项颜色、间距与排版控制README 罗列了该块的supports声明完整定义含实验性默认控件在 block.jsoncolorgradients:false不提供渐变背景__experimentalDefaultControls.background:true默认显示背景色控件__experimentalDefaultControls.text:true默认显示文字颜色控件spacingpadding:true支持内边距__experimentalDefaultControls.padding:truetypographyfontSize:true、lineHeight:true实验性支持__experimentalFontFamily、__experimentalFontWeight、__experimentalFontStyle、__experimentalTextTransform、__experimentalTextDecoration、__experimentalLetterSpacing__experimentalDefaultControls.fontSize:true注意README 中的 Supports 表是自动生成文档的“稳定”子集而block.json中还包含一批__experimental前缀的排版/默认控件声明字体族、字重、字风格、文字变换、文字装饰、字间距。这些以__experimental开头的支持项属于实验性 API可能在后续版本调整实际能力以当前仓库 block.json 为准。这些 Supports 让用户无需写 CSS 就能在侧边栏中调整按钮的背景色、文字颜色、内边距与排版字号、行高、字重等并且通过__experimentalDefaultControls让最常用的控件在面板默认展开。由于 style.scss 中按钮显式继承了颜色与字体见下文“样式”一节主题的theme.json与全局样式设置能够以块级优先级覆盖这些继承值。编辑器端实现Settings 面板与内联编辑edit.jsx 是该块的编辑器界面实现核心逻辑分为两块1. 检查器侧边栏Display Mode显示模式切换通过InspectorControls包裹一个ToolsPanel其中放置ToggleGroupControl供用户在Icon / Text / Both三种模式间切换edit.jsxToolsPanel label{ __( Settings ) } resetAll{ () setAttributes( { displayMode: icon } ) } dropdownMenuProps{ dropdownMenuProps } ToolsPanelItem label{ __( Display Mode ) } isShownByDefault hasValue{ () displayMode ! icon } onDeselect{ () setAttributes( { displayMode: icon } ) } ToggleGroupControl label{ __( Display Mode ) } value{ displayMode } onChange{ ( value ) setAttributes( { displayMode: value } ) } isBlock ToggleGroupControlOption valueicon label{ __( Icon ) } / ToggleGroupControlOption valuetext label{ __( Text ) } / ToggleGroupControlOption valueboth label{ __( Both ) } / /ToggleGroupControl /ToolsPanelItem /ToolsPanel注意resetAll与onDeselect都把displayMode重置为icon——这与block.json中的默认值icon保持一致。2. 画布内编辑图标与富文本画布中的button预览根据showIcon/showText渲染图标来自wordpress/icons的close图标与文本文本部分使用RichText实现内联编辑edit.jsxbutton { ...blockProps } typebutton aria-label{ ! showText ? __( Close ) : undefined } { showIcon Icon icon{ close } / } { showText ( RichText identifiertext value{ displayText } onChange{ ( value ) setAttributes( { text: value } ) } tagNamespan classNamewp-block-navigation-overlay-close__text allowedFormats{ [ core/bold, core/italic ] } / ) } /button几个值得注意的实现细节RichText的tagName为span、className为wp-block-navigation-overlay-close__text与服务端渲染输出的 span 类名完全对齐见下文确保编辑态与前台样式一致。allowedFormats限定为core/bold与core/italic即文案只允许加粗和斜体避免富文本污染按钮语义。当纯图标模式showText为 false时按钮通过aria-labelClose提供无障碍替代文本服务端渲染在相同条件下也会输出aria-label详见下一节。服务端渲染实现render_block_core_navigation_overlay_close作为动态块该块没有save输出 HTML而是由 index.php 中的render_block_core_navigation_overlay_close()回调完成渲染文档注释标记since 7.0.0即该块自 Gutenberg 7.0 起引入function render_block_core_navigation_overlay_close( $attributes ) { $text empty( $attributes[text] ) ? __( Close ) : $attributes[text]; $display_mode empty( $attributes[displayMode] ) ? icon : $attributes[displayMode]; $show_icon both $display_mode || icon $display_mode; $show_text both $display_mode || text $display_mode; $button_text ; if ( $show_icon ) { $button_text . svg xmlnshttp://www.w3.org/2000/svg viewBox0 0 24 24 width24 height24 aria-hiddentrue focusablefalsepath dM13 11.8l6.1-6.3-1.1-1-6.1 6.2-6.1-6.2-1.1 1 6.1 6.3-6.5 6.7 1.1 1 6.5-6.6 6.5 6.6 1.1-1z //svg; } if ( $show_text ) { $button_text . span classwp-block-navigation-overlay-close__text . wp_kses_post( $text ) . /span; } $wrapper_attributes get_block_wrapper_attributes(); $html_content sprintf( button %1$s typebutton %2$s %3$s/button, $wrapper_attributes, ! $show_text ? aria-label . __( Close ) . : , $button_text ); return $html_content; }渲染逻辑可以归纳为四点默认值回退text为空时回退到翻译后的ClosedisplayMode为空时按icon处理。图标内联输出图标不是外部图片引用而是直接内联输出 24×24 的 SVGaria-hiddentrue focusablefalse对辅助技术隐藏路径数据与编辑器图标见 icon.jsx同源均为“×”闭合形状。文本安全输出文案经wp_kses_post过滤后包裹在wp-block-navigation-overlay-close__textspan 中与编辑器端RichText的类名一致。无障碍属性纯图标/图文模式下只要没有显示文本就输出aria-labelClosetypebutton固定防止表单提交语义。块注册通过register_block_type_from_metadata( __DIR__ . /navigation-overlay-close, ... )绑定render_callback并挂载到init钩子index.php。插入限制机制只能放在导航遮罩模板部件里该块不能随意插入任意位置index.js 通过blockEditor.__unstableCanInsertBlockType过滤器限制其插入范围addFilter( blockEditor.__unstableCanInsertBlockType, core/navigation-overlay-close/restrict-to-overlay-template-parts, ( canInsert, blockType ) { if ( blockType.name ! core/navigation-overlay-close ) { return canInsert; } if ( ! canInsert ) { return canInsert; } return isWithinNavigationOverlay(); } );只有目标块是core/navigation-overlay-close时才拦截原有canInsert已是 false 则直接放行否则调用isWithinNavigationOverlay()判断当前编辑上下文是否位于“导航遮罩模板部件”内。isWithinNavigationOverlay()定义于 packages/block-library/src/utils/is-within-overlay.js它通过字符串访问core/editorstore避免 block-library 包对wordpress/editor产生硬依赖在postType wp_template_part时取实体记录并判断area NAVIGATION_OVERLAY_TEMPLATE_PART_AREA。该常量的值为navigation-overlay定义于 navigation/constants.js。也就是说普通文章/页面编辑器里看不到这个块只有编辑导航遮罩模板部件area 为navigation-overlay时才能插入从机制上保证了该按钮始终服务于遮罩场景。样式实现继承与按钮重置style.scss 定义了按钮外观关键点有二继承父级排版由于button的用户代理样式会破坏font/color继承样式用:where()选择器显式继承颜色与全部排版属性style.scss。:where()零特异性写法让theme.json和全局样式的块级值仍然能够获胜。按钮基础重置inline-flex布局、gap: 0.5em、去边框去背景、cursor: pointer并对内联 SVG 固定 24×24、fill: currentColor焦点态提供outline-offset: 2px保证键盘可达性style.scss。样式通过block.json中的style: wp-block-navigation-overlay-close在前后台按需加载。与导航遮罩块的协作在 navigation/index.php 中的实际应用该块的最终用途体现在 navigation/index.php 的遮罩渲染流程中导航块通过overlay属性选中某个模板部件作为自定义遮罩渲染时会检查遮罩 HTML 中是否包含关闭按钮block_core_navigation_overlay_html_has_close_block见 navigation/index.php若遮罩中存在关闭按钮且导航是交互式的则用WP_HTML_Tag_Processor为关闭按钮添加 Interactivity API 指令block_core_navigation_add_directives_to_overlay_close实现点击后收起遮罩的交互行为navigation/index.php同时会递归禁用遮罩内嵌套导航块的遮罩菜单防止“遮罩套遮罩”的嵌套问题disable_overlay_menu_for_nested_navigation_blocks见 navigation/index.php。因此一个典型的用法是在“导航遮罩模板部件”中放置该关闭按钮再让导航块的overlay属性指向该模板部件从而获得完全自定义的移动端菜单展开/收起体验。小结core/navigation-overlay-close是一个小而精的动态块它用两个属性displayMode、text控制图标/文字组合用一套完整且可扩展的supports声明接入颜色、间距与排版控制编辑器端通过ToolsPanelToggleGroupControlRichText提供直观的编辑体验服务端渲染负责输出带无障碍属性的内联 SVG 按钮插入范围则被严格限制在导航遮罩模板部件内并与导航块的 Interactivity API 指令协同工作。阅读本文时可将 README.md 作为快速参考将 block.json、index.php、edit.jsx 与 style.scss 作为深入研读的实现入口它们共同构成了该块从元数据到渲染输出的完整链路。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考