企业官网建设流程全解析

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 class="wp-block-heading">Markup example</h3> <!-- /wp:heading -->

通过过滤器全局设置默认值

你还可以借助 区块过滤器 为所有 Heading 区块（或特定区块）全局设置该属性的默认值。下面的 PHP 示例为所有core/heading区块移除 H1、H2 和 H6：

function 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-row（Row）：attributes: { layout: { type: 'flex', flexWrap: 'nowrap' } }；
• group-stack（Stack）：attributes: { 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中按如下方式入队（enqueue）：

function 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 Editing）

View 菜单中的 "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）。需要注意两点：

1. 已保存的状态样式不受影响：已存在于theme.json、Global Styles 或区块style属性中的状态样式，在编辑器中和前端都会继续生效；
2. 与视口状态控件互不影响：该设置不作用于视口（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_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