Gutenberg 编辑器功能裁剪完全指南禁用区块、变体、样式与编辑能力【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读本文聚焦于 WordPress Gutenberg 项目The Block Editor project for WordPress and beyond中裁剪编辑器体验Curating the Editor Experience的核心主题——禁用 Post Editor 与 Site Editor 中的特定功能。你将从这篇文章中掌握七大类功能裁剪方案限制插入器中的区块、收敛标题级别下拉、移除核心 Patterns、禁用区块变体如 Row/Stack、移除区块样式如 Image 的 Rounded、限制代码编辑器访问以及通过编辑器设置关闭响应式编辑、状态编辑和富文本格式选项。全文所有示例均可在主题的functions.php与前端脚本中直接落地并附上仓库源码级佐证帮助你理解每个开关背后的真实实现。说明本文属于 文档目录 中 Curating the Editor Experience裁剪编辑器体验系列与 block-locking.md区块锁定、filters-and-hooks.md过滤器与钩子等互为补充共同构成一套完整的编辑器定制工具箱。限制区块选项白名单与黑名单当你不希望用户能够接触到某些区块时可以控制插入器Inserter中可用的区块集合常用两种思路白名单Allow List禁用除名单之外的所有区块黑名单Deny List通过unregisterBlockType注销特定的区块。具体实现请参见 区块过滤器文档 中的 Using an allow list 与 Using a deny list 两节。这一层是是否有这个区块可用的控制而下面的levelOptions则是更细粒度地控制一个区块内部有哪些选项可选。裁剪标题级别levelOptions属性适用区块与工作原理内置Core带有标题级别下拉框的区块都支持levelOptions属性包括Heading、Site Title、Site Tagline、Query Title、Post Title、Comments Title区块。该属性接受一个数字数组1对应 H1、2对应 H2依此类推。以 Heading 区块为例block.json 中声明了levelOptions: { type: array }levelOptions的作用仅是控制下拉框 UI 中展示哪些级别是一种轻量级裁剪不需要任何区块弃用deprecation操作也不会改动已保存的标记markup——已有的标题级别原样保留。从源码实现看它本质上是通过注销标题级别的变体variation来实现的。heading/index.js 中有如下逻辑// Unregister heading level variations based on levelOptions attribute. // This is for backwards compatibility, as extenders can now unregister the // variation directly: wp.blocks.unregisterBlockVariation( core/heading, h1 ). const levelOptions getBlockType( name )?.attributes?.levelOptions?.default; if ( levelOptions ) { [ 1, 2, 3, 4, 5, 6 ].forEach( ( level ) { if ( ! levelOptions.includes( level ) ) { unregisterBlockVariation( name, h${ level } ); } } ); }这意味着代码会遍历 H1–H6 六个级别变体凡是不在levelOptions默认值中的级别都会被unregisterBlockVariation注销从而从下拉中消失。同时源码注释也指出扩展者现在可以直接调用wp.blocks.unregisterBlockVariation( core/heading, h1 )来注销某个级别——levelOptions的这套逻辑主要是为了向后兼容。在区块标记中直接使用你可以把levelOptions直接写进区块标记里这在**区块模板block templates、模板部件template parts和模式patterns**中尤为常用。下面的标记通过levelOptions:[3,4,5]禁用了 Heading 区块的 H1、H2 与 H6!-- wp:heading {level:3,levelOptions:[3,4,5],className:wp-block-heading} -- h3 classwp-block-headingMarkup example/h3 !-- /wp:heading --通过过滤器全局设置默认值你还可以借助 区块过滤器 为所有 Heading 区块或特定区块全局设置该属性的默认值。下面的 PHP 示例为所有core/heading区块移除 H1、H2 和 H6function example_modify_heading_levels_globally( $args, $block_type ) { if ( core/heading ! $block_type ) { return $args; } // Remove H1, H2, and H6. $args[attributes][levelOptions][default] [ 3, 4, 5 ]; return $args; } add_filter( register_block_type_args, example_modify_heading_levels_globally, 10, 2 );该过滤器挂在register_block_type_args上直接改写区块注册参数中的attributes.levelOptions.default。你可以在此基础上做更多定制例如基于用户能力capability等条件动态决定允许哪些标题级别——比如对编辑角色开放 H2–H4对管理员开放全部级别。注意levelOptions只影响编辑器 UI 的展示范围前端渲染的h1–h6标记不受影响。禁用 Pattern Directory核心模式库WordPress 核心自带一批 Patterns。若希望彻底移除这些核心 Patterns 在插入器中的可访问性可以在主题的functions.php中添加function example_theme_support() { remove_theme_support( core-block-patterns ); } add_action( after_setup_theme, example_theme_support );通过remove_theme_support( core-block-patterns )去掉对核心模式的支持后这些 Patterns 便不再出现在插入器的 Patterns 标签中。该操作只影响核心自带的模式集合主题自身注册的 Patterns 以及 Patterns 定制文档 中描述的自定义模式仍可正常使用。禁用区块变体以 Row 与 Stack 为例有些区块实际上是区块变体block variations。最典型的例子就是 Row 和 Stack——它们其实都是 Group 区块的变体。在源码 group/variations.js 中可以看到Group 区块注册了group、group-row、group-stack、group-grid四个变体其中group-rowRowattributes: { layout: { type: flex, flexWrap: nowrap } }group-stackStackattributes: { layout: { type: flex, orientation: vertical } }。因此想要禁用 Row 区块本质上就是注销group-row这个变体。由于区块变体是通过 JavaScript 注册的也必须用 JavaScript 注销。以下代码禁用 Row 变体wp.domReady( () { wp.blocks.unregisterBlockVariation( core/group, group-row ); });假设上述代码位于主题根目录的disable-variations.js文件中则在主题的functions.php中按如下方式入队enqueuefunction example_disable_variations_script() { wp_enqueue_script( example-disable-variations-script, get_template_directory_uri() . /disable-variations.js, array( wp-dom-ready ), wp_get_theme()-get( Version ), true ); } add_action( enqueue_block_editor_assets, example_disable_variations_script );要点依赖数组中的wp-dom-ready确保脚本在 DOM 就绪后执行此时unregisterBlockVariation才安全可用挂载钩子必须是enqueue_block_editor_assets保证只在编辑器环境加载传入脚本句柄、get_template_directory_uri() . /disable-variations.js作为源、wp_get_theme()-get( Version )作为版本号、true表示放到页脚加载。若还需要禁用 Stack可同样注销group-stack变体由于变体机制是通用的其他区块的变体也可以按相同思路处理。禁用区块样式以 Image 的 Rounded 为例部分核心区块自带区块样式block styles。例如 Image 区块就内置了一个名为 Rounded圆角的样式。你可能不希望用户把图片变成圆角或者更希望他们使用边框半径border-radius控件来替代该样式。无论哪种动机禁用不需要的区块样式都很简单。关于禁用方式的规则区块样式可以用 JavaScript 或 PHP 注册。如果样式是用 JavaScript 注册的就必须用 JavaScript 禁用如果样式是用 PHP 注册的则两种方式都可以。所有核心Core区块样式都是用 JavaScript 注册的。因此禁用 Image 区块的 Rounded 样式代码如下wp.domReady( () { wp.blocks.unregisterBlockStyle( core/image, rounded ); });这段 JavaScript 的入队方式与前面区块变体示例完全一致放入disable-variations.js之类的文件用enqueue_block_editor_assets钩子加载。若你希望使用 PHP 注册或注销样式可参考官方 block styles 文档中关于 register/unregister 的说明——核心要点是JavaScript 注册的样式必须用wp.blocks.unregisterBlockStyle在wp.domReady中注销PHP 注册的样式则可用unregister_block_style函数处理。禁用代码编辑器Code Editor代码编辑器允许用户查看页面或文章的底层区块标记。这个视图对经验丰富的用户很实用但普通用户在不了解区块标记语法的情况下编辑内容很容易意外破坏标记结构。若希望限制访问可在functions.php中添加function example_restrict_code_editor_access( $settings ) { $settings[ codeEditingEnabled ] false; return $settings; } add_filter( block_editor_settings_all, example_restrict_code_editor_access );该过滤器通过block_editor_settings_all把编辑器设置中的codeEditingEnabled置为false。这一设置是编辑器默认设置之一见 editor/store/defaults.js 中codeEditingEnabled: true的默认声明——设置为false后编辑器 UI 中切换到代码编辑器的入口将被移除。上述代码会阻止所有用户访问代码编辑器。你还可以在此基础上叠加能力capability检查只对特定用户如仅管理员或拥有edit_files能力的角色禁用例如function example_restrict_code_editor_access( $settings ) { if ( ! current_user_can( manage_options ) ) { $settings[ codeEditingEnabled ] false; } return $settings; }禁用响应式编辑Responsive EditingView 菜单中的 Responsive styles响应式样式选项允许用户将样式变更仅应用于单一视口viewport。如果你希望样式编辑始终应用于所有视口可在functions.php中添加function example_disable_responsive_editing( $settings ) { $settings[ responsiveEditingEnabled ] false; return $settings; } add_filter( block_editor_settings_all, example_disable_responsive_editing );对应设置默认值为responsiveEditingEnabled: true见 editor/store/defaults.js。需要注意该设置关闭的是编辑器内的按视口编辑能力已经在theme.json或 Global Styles 中定义好的响应式样式在前端仍会正常生效不会被清除。也就是说禁用后主题作者依然可以通过theme.json声明各断点样式只是不再允许用户内容编辑者在编辑器里做只改移动端这样的视口级微调。禁用区块状态编辑Block States Editing区块检查器Block Inspector和 Global Styles 中的状态控件允许用户为区块的状态states如 Hover、Focus 等应用样式。要隐藏这些控件可在functions.php中添加function example_disable_block_states_editing( $settings ) { $settings[ blockStatesEditingEnabled ] false; return $settings; } add_filter( block_editor_settings_all, example_disable_block_states_editing );该设置默认值为blockStatesEditingEnabled: true见 editor/store/defaults.js 与 block-editor/store/defaults.js。需要注意两点已保存的状态样式不受影响已存在于theme.json、Global Styles 或区块style属性中的状态样式在编辑器中和前端都会继续生效与视口状态控件互不影响该设置不作用于视口viewport状态控件——视口相关开关由responsiveEditingEnabled控制。禁用 RichText 区块的格式化选项支持 RichText 的区块自带 WordPress 提供的默认格式化选项。若要移除某些格式必须使用 JavaScript 的unregisterFormatType。下面的代码全局禁用 Inline Image内联图片、Language语言、Keyboard Input键盘输入、Subscript下标和 Superscript上标选项wp.domReady( () { wp.richText.unregisterFormatType( core/image ); wp.richText.unregisterFormatType( core/language ); wp.richText.unregisterFormatType( core/keyboard ); wp.richText.unregisterFormatType( core/subscript ); wp.richText.unregisterFormatType( core/superscript ); });这段 JavaScript 同样按区块变体示例中的方式入队放进主题根目录的 JS 文件通过enqueue_block_editor_assets钩子、以wp-dom-ready为依赖加载。unregisterFormatType接收的是格式类型的注册名如core/image这些名称与 format-library 包中各格式的注册保持一致。结语一张可落地的裁剪清单汇总本文全部开关可形成一张开箱即用的裁剪清单裁剪目标手段实现位置区块可用范围白名单 / 黑名单过滤器见 block-filters.md标题级别下拉levelOptions属性 /register_block_type_args区块标记、functions.php核心 Patternsremove_theme_support( core-block-patterns )functions.php区块变体Row/Stackwp.blocks.unregisterBlockVariation编辑器 JS区块样式Rounded 等wp.blocks.unregisterBlockStyle编辑器 JS代码编辑器codeEditingEnabled falsefunctions.php响应式编辑responsiveEditingEnabled falsefunctions.php状态编辑blockStatesEditingEnabled falsefunctions.phpRichText 格式化选项wp.richText.unregisterFormatType编辑器 JS其中四类能力代码编辑器、响应式编辑、状态编辑均通过block_editor_settings_all过滤器修改编辑器设置默认值实现对应默认值可在 editor/store/defaults.js 中查阅而变体、样式、格式类型由于是 JS 注册的必须用 JS 在wp.domReady回调中注销。将这张清单与 theme.json 定制、过滤器与钩子 配合使用即可为不同用户角色交付高度定制的 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），仅供参考