WordPress 提供了多个 API，允许您修改编辑器体验。

编辑器设置

修改编辑器最常见的方式是通过 block_editor_settings_all PHP 过滤器，该过滤器在将设置发送到已初始化的编辑器之前应用。此过滤器允许插件和主题作者对编辑器的行为进行广泛控制。

在 WordPress 5.8 之前，此钩子被称为 block_editor_settings，现已弃用。如果您需要支持旧版本的 WordPress，可能需要一种方法来检测应使用哪个过滤器。您可以通过检查是否存在 WP_Block_Editor_Context 类来判断是否可以安全使用 block_editor_settings，该类是在 5.8 中引入的。

block_editor_settings_all 钩子向回调函数传递两个参数：

  • $settings – 一个包含可配置设置的数组，用于编辑器。
  • $context – WP_Block_Editor_Context 的一个实例，这是一个包含有关当前编辑器信息的对象。

以下示例修改了最大上传文件大小。将此添加到插件或主题的 functions.php 文件中以进行测试。

add_filter( 'block_editor_settings_all', 'example_filter_block_editor_settings_when_post_provided', 10, 2 );

function example_filter_block_editor_settings_when_post_provided( $editor_settings, $editor_context ) {
    if ( ! empty( $editor_context->post ) ) {
        $editor_settings['maxUploadFileSize'] = 12345;
    }
    return $editor_settings;
}

编辑器设置有很多，在此文档文章中无法一一列出，但这里有一些可以使用 block_editor_settings_all 过滤器执行的示例。

要查看所有可用设置，请打开编辑器，然后在浏览器的 开发者工具 中打开控制台。输入命令 wp.data.select( 'core/block-editor' ).getSettings() 以显示所有编辑器设置的当前值。

限制代码编辑器访问

codeEditingEnabled 默认值为 true，它控制用户是否可以在视觉编辑器之外访问代码编辑器。在某些情况下，您可能不希望某些用户能够访问此视图。

如果将此设置设置为 false，用户将无法在视觉编辑器和代码编辑器之间切换。设置菜单中的选项将不可用，用于切换编辑器类型的键盘快捷键也不会触发。以下是一个示例：

add_filter( 'block_editor_settings_all', 'example_restrict_code_editor' );

function example_restrict_code_editor( $settings ) {
    $can_active_plugins = current_user_can( 'activate_plugins' );

    // 为无法激活插件的用户（管理员）禁用代码编辑器。
    if ( ! $can_active_plugins ) {
        $settings[ 'codeEditingEnabled' ] = false;
    }

    return $settings;
}

限制可视化编辑器访问

与 codeEditingEnabled 设置类似，richEditingEnabled 允许您控制谁可以访问可视化编辑器。如果为 true，用户可以使用可视化编辑器编辑内容。

该设置的默认值是 user_can_richedit 函数返回的值。它检查用户是否可以访问可视化编辑器以及用户的浏览器是否支持它。

限制响应式编辑

responsiveEditingEnabled 设置默认值为 true，它控制编辑器“查看”菜单中是否提供“响应式样式”选项。当其为 false 时，该选项不会渲染，全局样式中的视口状态控件也会隐藏，因此用户无法针对单个视口定位样式更改。悬停等伪状态仍然可用。主题或全局样式中已定义的响应式样式不受影响。

add_filter( 'block_editor_settings_all', 'example_disable_responsive_editing' );

function example_disable_responsive_editing( $settings ) {
    $settings['responsiveEditingEnabled'] = false;
    return $settings;
}

限制块状态编辑

blockStatesEditingEnabled 设置默认值为 true，它控制块检查器和全局样式中是否提供块的状态控件。当其为 false 时，不会渲染这些控件，因此用户无法从这些界面中将块样式应用于状态。视口状态控件不受影响，仍由 responsiveEditingEnabled 控制。已在 theme.json、全局样式或块的 style 属性中保存的状态样式不受影响。

add_filter( 'block_editor_settings_all', 'example_disable_block_states_editing' );

function example_disable_block_states_editing( $settings ) {
    $settings['blockStatesEditingEnabled'] = false;
    return $settings;
}

设置默认图像大小

在编辑器中，图像默认设置为 large 图像大小。您可以使用 imageDefaultSize 设置对此进行修改，如果您配置了自己的自定义图像大小，这将特别有用。以下示例将默认图像大小更改为 medium。

add_filter( 'block_editor_settings_all', 'example_set_default_image_size' );

function example_set_default_image_size( $settings ) {
    $settings['imageDefaultSize'] = 'medium';
    return $settings;
}

禁用 Openverse

Openverse 集成默认情况下在所有 WordPress 网站上启用，并由 enableOpenverseMediaCategory 设置控制。要禁用 Openverse，请应用以下过滤器：

add_filter( 'block_editor_settings_all', 'example_disable_openverse' );

function example_disable_openverse( $settings ) {
    $settings['enableOpenverseMediaCategory'] = false;
    return $settings;
}

禁用字体库

字体库允许用户在他们的网站上安装新字体，默认情况下启用，并由 fontLibraryEnabled 设置控制。要禁用字体库，请应用以下过滤器：

add_filter( 'block_editor_settings_all', 'example_disable_font_library' );

function example_disable_font_library( $settings ) {
    $settings['fontLibraryEnabled'] = false;
    return $settings;
}

禁用块检查器标签页

大多数块在检查器中显示两个标签页，一个用于设置，另一个用于样式。您可以使用 blockInspectorTabs 设置禁用这些标签页。

add_filter( 'block_editor_settings_all', 'example_disable_inspector_tabs_by_default' );

function example_disable_inspector_tabs_by_default( $settings ) {
    $settings['blockInspectorTabs'] = array( 'default' => false );
    return $settings;
}

您还可以修改哪些块具有检查器标签页。以下是一个禁用特定块标签页的示例。

add_filter( 'block_editor_settings_all', 'example_disable_tabs_for_my_custom_block' );

function example_disable_tabs_for_my_custom_block( $settings ) {
    $current_tab_settings = _wp_array_get( $settings, array( 'blockInspectorTabs' ), array() );
    $settings['blockInspectorTabs'] = array_merge(
        $current_tab_settings,
        array( 'my-plugin/my-custom-block' => false )
    );

    return $settings;
}

块目录

块目录允许用户直接从 WordPress.org 插件目录 在编辑器中安装新的块插件。您可以通过删除加载它的操作来禁用此功能，该操作是 wp_enqueue_editor_block_directory_assets。为此，请使用 remove_action，如下所示：

remove_action( 'enqueue_block_editor_assets', 'wp_enqueue_editor_block_directory_assets' );

块模式

远程模式，例如来自 WordPress.org 模式目录 的模式，默认情况下在编辑器中对用户可用。此功能由 should_load_remote_block_patterns 控制，默认值为 true。您可以通过将过滤器设置为 false (__return_false) 来禁用远程模式。

add_filter( 'should_load_remote_block_patterns', '__return_false' );

编辑器功能

以下过滤器可用于扩展编辑器的功能。

editor.PostFeaturedImage.imageSize

您可以使用此过滤器来修改“文章特色图像”组件中显示的图像尺寸。默认值为 'post-thumbnail'，当指定的图像尺寸在媒体对象中不存在时，将回退到 full 图像尺寸。它模仿了经典编辑器中的 admin_post_thumbnail_size 过滤器。

import { addFilter } from '@wordpress/hooks';

const withImageSize = function ( size, mediaId, postId ) {
    return 'large';
};

addFilter(
    'editor.PostFeaturedImage.imageSize',
    'my-plugin/with-image-size',
    withImageSize
);

editor.PostPreview.interstitialMarkup

您还可以过滤生成预览时显示的中间消息。以下是一个示例：

import { addFilter } from '@wordpress/hooks';

const customPreviewMessage = function () {
    return '<b>正在生成文章预览！</b>';
};

addFilter(
    'editor.PostPreview.interstitialMarkup',
    'my-plugin/custom-preview-message',
    customPreviewMessage
);

media.crossOrigin

此过滤器用于设置或修改来自其他来源的媒体元素（即 <audio>、<img>、<link>、<script>、<video>）的 crossOrigin 属性。有关 crossOrigin 属性、其值以及它如何应用于每个元素的更多信息，请参阅此 文章。

其实际应用的一个例子是图像块的转换功能，允许在 <canvas> 中使用跨域图像。以下是一个示例：

import { addFilter } from '@wordpress/hooks';

addFilter(
    'media.crossOrigin',
    'my-plugin/with-cors-media',
    // 回调函数接受第二个 `mediaSrc` 参数，该参数引用
    // 实际外部媒体的 URL，如果您想据此决定
    // crossOrigin 的值，这将非常有用。
    ( crossOrigin, mediaSrc ) => {
        if ( mediaSrc.startsWith( 'https://example.com' ) ) {
            return 'use-credentials';
        }
        return crossOrigin;
    }
);

编辑器 REST API 预加载路径

您可以使用 block_editor_rest_api_preload_paths 来过滤将用于为块编辑器预加载常用数据的 REST API 路径数组。以下是一个示例：

add_filter( 'block_editor_rest_api_preload_paths', 'example_filter_block_editor_rest_api_preload_paths_when_post_provided', 10, 2 );

function example_filter_block_editor_rest_api_preload_paths_when_post_provided( $preload_paths, $editor_context ) {
    if ( ! empty( $editor_context->post ) ) {
        array_push( $preload_paths, array( '/wp/v2/blocks', 'OPTIONS' ) );
    }
    return $preload_paths;
}

客户端媒体处理

客户端媒体处理使用 WebAssembly 在浏览器中处理图像压缩、调整大小、格式转换、旋转和缩略图生成。以下过滤器和参数控制其行为。

如需完整概览，请参阅 架构说明 和 开发者指南。

wp_client_side_media_processing_enabled

此 PHP 过滤器控制是否启用客户端媒体处理。默认值为 true。

// 完全禁用客户端媒体处理。
add_filter( 'wp_client_side_media_processing_enabled', '__return_false' );

您也可以有条件地禁用它：

add_filter( 'wp_client_side_media_processing_enabled', 'example_disable_for_editors' );

function example_disable_for_editors( $enabled ) {
    if ( current_user_can( 'edit_posts' ) && ! current_user_can( 'manage_options' ) ) {
        return false;
    }
    return $enabled;
}

当禁用时，所有上传都将回退到传统的服务器端处理管道。

客户端处理遵循的过滤器

客户端处理通过 REST API 从服务器读取以下现有的 WordPress 过滤器，并在基于浏览器的图像处理过程中应用它们：

  • big_image_size_threshold — 缩放前的最大图像尺寸。超过此阈值的图像将在客户端进行缩放。默认值：2560px。
  • image_editor_output_format — 将输入 MIME 类型映射到输出 MIME 类型以实现自动格式转换（例如，JPEG → WebP）。在客户端转码期间应用。
  • image_save_progressive — 控制渐进式（JPEG）或交错（PNG、GIF）编码。在客户端压缩和格式转换期间应用。
  • wp_image_maybe_exif_rotate — 控制基于 EXIF 的图像旋转。当客户端处理处于活动状态时，服务器端旋转将被禁用，改由客户端处理。
  • wp_editor_set_quality（对于 JPEG 输出还有 jpeg_quality）— 编码质量（1–100）。服务器会为每个注册的尺寸解析这些过滤器，并将结果报告在上传响应的大小感知 image_quality 字段中，客户端在子尺寸调整和转码期间会应用该值。没有单独的 JavaScript 质量过滤器。
  • image_strip_meta — 控制是否从生成的图像中剥离元数据。导出到 REST 索引；当为 false 时，客户端保留所有元数据（EXIF、XMP、IPTC），而不是仅保留颜色配置文件（和 HDR 增益映射）而剥离所有内容。
  • image_max_bit_depth — 限制生成图像的位深度（与高比特深度的 AVIF/HDR 源相关）。导出到 REST 索引并由客户端编码器尊重，并调整为 AVIF 编码器支持的位深度（8、10 或 12 位）。

注意：当客户端处理处于活动状态时，三个服务器端钩子永远不会触发，因为没有涉及服务器端的 WP_Image_Editor：wp_image_editors、image_make_intermediate_size 和 image_memory_limit。请参阅指南中的 服务器端插件兼容性 以获取替代信号。

注意：没有用于确定哪些 MIME 类型有资格进行客户端处理的过滤器。支持的集合在 packages/upload-media/src/store/constants.ts 中固定为 CLIENT_SIDE_SUPPORTED_MIME_TYPES（image/jpeg、image/png、image/gif、image/webp、image/avif）。不在此集合中的文件将回退到服务器端处理，或者对于 HEIC/HEIF 文件，回退到单独的基于画布的解码路径。

REST API 参数

客户端处理在上传媒体时使用以下额外的 REST API 参数：

  • generate_sub_sizes（布尔值，默认值：true）— 当在 POST /wp/v2/media 上设置为 false 时，服务器跳过缩略图生成。客户端处理将其设置为 false，以便它可以自行生成和旁加载缩略图。
  • convert_format（布尔值，默认值：true）— 当在 POST /wp/v2/media 或 POST /wp/v2/media/{id}/sideload 上设置为 false 时，服务器跳过通过 image_editor_output_format 过滤器的格式转换。用于客户端已经执行转换的情况。
  • url（字符串）— 当传递给 POST /wp/v2/media 而不是文件主体时，服务器下载远程图像并将其旁加载。用于将外部图像导入媒体库，而无需使用在跨域隔离编辑器中失败的浏览器跨域 fetch。

动画 GIF 转换为视频

不透明的动画 GIF 会在客户端转换为配套的 MP4/WebM 视频，并且图像块上的“显示为视频”控件允许用户将其切换为视频块的“GIF”变体。没有用于此行为的专用过滤器——它由上述相同的 wp_client_side_media_processing_enabled 主开关控制，并且在浏览器缺乏 WebCodecs 视频编码时回退到上传原始 GIF。有关详细信息，请参阅 架构文档 和 指南。

记录错误

UI 某部分的 JavaScript 错误不应导致整个应用程序崩溃。为解决用户的问题，React 库使用了 “错误边界” 的概念。错误边界是 React 组件，它们捕获其子组件树中任何地方的 JavaScript 错误，并显示备用 UI，而不是显示崩溃的组件树。

editor.ErrorBoundary.errorLogged 操作允许你挂钩到 Error Boundaries，并提供对错误对象以及 React 的错误信息对象的访问权限，其 componentStack 属性描述了错误在组件树中抛出的位置。

你可以使用此操作来获取由边界处理的错误对象。例如，你可能希望将它们发送到外部错误跟踪工具。以下是一个示例：

import { addAction } from '@wordpress/hooks';

addAction(
    'editor.ErrorBoundary.errorLogged',
    'mu-plugin/error-capture-setup',
    ( error, errorInfo ) => {
        // Error 是异常的 error 对象。
        // 你可以将其 console.log 输出或发送到外部错误跟踪工具。
        console.log ( error, errorInfo?.componentStack );
    }
);