发布于 由admin

探究 WordPress `get_block_editor_settings()` 函数源码：编辑器配置的动态修改与过滤器应用。

各位观众老爷们，晚上好！今天咱们聊聊 WordPress 编辑器背后的“百宝箱”—— get_block_editor_settings()。

大家好啊！我是你们的老朋友，今天咱们不聊风花雪月，专攻硬核技术，一起扒一扒 WordPress 编辑器里那个神奇的函数：get_block_editor_settings()。 别看名字长，它可是个宝贝，藏着编辑器各种配置的秘密，还能让你像捏泥人一样随意修改。准备好你的代码编辑器，咱们开始吧！

一、 get_block_editor_settings() 是个啥？

简单来说，get_block_editor_settings() 就是一个函数，它负责收集和整理 WordPress 区块编辑器（Gutenberg）的所有配置信息，然后打包成一个数组返回给你。这个数组里包含了编辑器需要的所有东西，比如：

  • 区块类型（Block Types）： 支持哪些区块，每个区块长什么样，有什么属性。
  • 样式（Styles）： 编辑器里用的 CSS 样式表。
  • 模板（Templates）： 页面或文章可以使用的预设模板。
  • 翻译（Translations）： 编辑器里显示的文字翻译。
  • 设置（Settings）： 各种全局设置，比如默认区块、字体大小、颜色等等。

想象一下，get_block_editor_settings() 就像一个经验丰富的管家，把编辑器需要的所有东西都准备好，然后交给你这个“上帝之手”来掌控。

二、 源码剖析：我们从哪里入手？

想知道 get_block_editor_settings() 到底怎么工作的，最好的方法当然是看源码啦！这个函数位于 wp-includes/block-editor.php 文件里。打开这个文件，你会看到一大坨代码，别慌，咱们慢慢分析。

function get_block_editor_settings( $settings = array() ) {
    global $post;

    $default_settings = array(
        'availableTemplates'   => array(),
        'allowedBlockTypes'    => true, // `true` === All blocks.
        'disableCustomColors'  => false,
        'disableCustomFontSizes' => false,
        'disableCustomGradients' => false,
        'enableCustomFields'   => get_post_type_supports( ! empty( $post ) ? $post->post_type : 'post', 'custom-fields' ),
        'isRTL'                => is_rtl(),
        'styles'               => array(),
        'imageSizes'           => array(),
        'richTextFormats'      => array(),
        '__experimentalBlockPatterns' => WP_Block_Patterns_Registry::get_instance()->get_all_registered(),
        '__experimentalBlockPatternCategories' => WP_Block_Pattern_Categories_Registry::get_instance()->get_all_registered(),
    );

    $settings = array_merge( $default_settings, $settings );

    // 各种复杂的逻辑... (此处省略 N 行代码)

    $settings = apply_filters( 'block_editor_settings_all', $settings, $post );

    return $settings;
}

源码解读：

  1. $default_settings： 这是个重要的数组，定义了编辑器的默认设置。你可以看到，里面包含了各种各样的选项，比如 allowedBlockTypes（允许使用的区块类型）、disableCustomColors（禁用自定义颜色）等等。
  2. array_merge( $default_settings, $settings )： 这个函数把你传入的 $settings 数组和默认设置合并起来。这意味着你可以通过传入自己的 $settings 数组来覆盖默认设置。
  3. apply_filters( 'block_editor_settings_all', $settings, $post )： 这行代码是关键！它使用了 WordPress 的过滤器（Filter）机制，允许你通过 block_editor_settings_all 这个钩子来修改最终的设置数组。

三、 动态修改：过滤器大显身手

apply_filters() 函数是 WordPress 插件和主题开发中非常重要的一个工具。它允许你在特定的代码执行点插入自己的代码，从而修改 WordPress 的默认行为。

在这里，apply_filters( 'block_editor_settings_all', $settings, $post ) 允许你通过 block_editor_settings_all 过滤器来修改 get_block_editor_settings() 函数返回的设置数组。

具体步骤：

  1. 添加过滤器： 在你的插件或主题的 functions.php 文件中，使用 add_filter() 函数来添加一个过滤器。
  2. 编写回调函数： 编写一个回调函数，这个函数接收 $settings 数组作为参数，你可以修改这个数组，然后返回修改后的数组。

举个栗子：

假设你想禁用编辑器中的自定义颜色选择器。你可以这样做：

function my_custom_block_editor_settings( $settings, $post ) {
    $settings['disableCustomColors'] = true;
    return $settings;
}
add_filter( 'block_editor_settings_all', 'my_custom_block_editor_settings', 10, 2 );

代码解释：

  • my_custom_block_editor_settings()：这是你的回调函数，它接收 $settings 和 $post 两个参数。
  • $settings['disableCustomColors'] = true;：这行代码把 disableCustomColors 设置为 true，从而禁用了自定义颜色选择器。
  • add_filter( 'block_editor_settings_all', 'my_custom_block_editor_settings', 10, 2 );：这行代码把你的回调函数添加到 block_editor_settings_all 过滤器上。 10 是优先级，2 是回调函数接收的参数个数。

现在，当你打开编辑器时，你会发现自定义颜色选择器不见了！

四、 实战演练：更多修改技巧

除了禁用自定义颜色，你还可以用过滤器做很多其他事情，比如：

  • 限制允许使用的区块类型：
function my_allowed_block_types( $allowed_block_types, $post ) {
    return array(
        'core/paragraph',
        'core/image',
        'core/heading',
    );
}
add_filter( 'allowed_block_types_all', 'my_allowed_block_types', 10, 2 );

这段代码只允许使用段落、图片和标题这三种区块。 注意这里用的是allowed_block_types_all过滤器，这是个更底层的过滤器，专门用来控制允许的区块类型。

  • 添加自定义样式：
function my_custom_editor_styles( $settings, $post ) {
    $settings['styles'][] = array(
        'name'  => 'my-custom-style',
        'label' => '我的自定义样式',
        'style' => 'p { color: red; }',
    );
    return $settings;
}
add_filter( 'block_editor_settings_all', 'my_custom_editor_styles', 10, 2 );

这段代码添加了一个名为 my-custom-style 的自定义样式，它会把段落文字变成红色。

  • 修改图片尺寸：
function my_custom_image_sizes( $settings, $post ) {
    $settings['imageSizes'][] = array(
        'name'   => 'my-custom-size',
        'slug'   => 'my-custom-size',
        'width'  => 800,
        'height' => 600,
    );
    return $settings;
}
add_filter( 'block_editor_settings_all', 'my_custom_image_sizes', 10, 2 );

这段代码添加了一个名为 my-custom-size 的自定义图片尺寸，尺寸为 800×600。

五、 常用配置项一览表

为了方便大家查阅，我把 get_block_editor_settings() 函数返回的设置数组中常用的配置项整理成了一个表格：

配置项 类型 描述 示例
availableTemplates array 可用的页面模板。 array( array( 'name' => 'my-template', 'label' => '我的模板' ) )
allowedBlockTypes array/bool 允许使用的区块类型。如果为 true，则允许所有区块。 array( 'core/paragraph', 'core/image' ) 或者 true
disableCustomColors bool 是否禁用自定义颜色选择器。 true
disableCustomFontSizes bool 是否禁用自定义字体大小选择器。 true
styles array 编辑器中使用的 CSS 样式表。 array( array( 'name' => 'my-style', 'label' => '我的样式', 'style' => 'p { color: blue; }' ) )
imageSizes array 可用的图片尺寸。 array( array( 'name' => 'my-size', 'slug' => 'my-size', 'width' => 400, 'height' => 300 ) )
richTextFormats array 富文本格式，例如粗体、斜体等。 array( 'core/bold', 'core/italic' )
enableCustomFields bool 是否启用自定义字段。 true
isRTL bool 是否是 RTL (从右到左) 语言。 true
__experimentalBlockPatterns array 实验性的区块模式。 array( array( 'name' => 'my-pattern', 'title' => '我的模式', 'content' => '<!-- wp:paragraph -->...' ) )
__experimentalBlockPatternCategories array 实验性的区块模式分类。 array( array( 'name' => 'my-category', 'label' => '我的分类' ) )

六、 注意事项：别踩坑！

  • 优先级： 当添加多个过滤器到同一个钩子上时，它们的执行顺序由优先级决定。优先级数值越小，执行顺序越靠前。
  • 参数数量： 确保你的回调函数接收的参数数量和 add_filter() 函数中指定的参数数量一致。
  • 代码位置： 确保你的代码放在正确的位置，通常是在插件或主题的 functions.php 文件中。
  • 调试： 如果你的修改没有生效，可以使用 var_dump() 或 error_log() 函数来调试你的代码，看看 $settings 数组到底是什么样的。

七、 总结：掌控你的编辑器

get_block_editor_settings() 函数是 WordPress 区块编辑器的一个强大的工具，它允许你动态地修改编辑器的配置，从而定制你的编辑体验。 通过 block_editor_settings_all 过滤器，你可以轻松地禁用自定义颜色、限制区块类型、添加自定义样式等等。 只要你掌握了这些技巧，你就可以像掌控自己的后花园一样掌控你的编辑器！

好了，今天的讲座就到这里。希望大家有所收获，下次再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注