各位好，我是今天的WordPress特约讲师，咱们今天聊聊WordPress编辑器背后的那些事儿，特别是那个神秘的get_default_block_editor_settings()函数。别担心，我会用尽可能简单的方式，带你剥开它的层层外衣，看看它到底是怎么工作的。
开场白：编辑器的“默认配置”是个啥？
想象一下，你打开WordPress编辑器，准备写一篇惊天地泣鬼神的文章。编辑器里有各种各样的块，各种各样的设置选项，比如字体大小、颜色、对齐方式等等。这些选项，有些是WordPress自带的，有些是主题或插件添加的。
那么问题来了：WordPress怎么知道默认情况下应该显示哪些块？哪些设置可用？这些默认值又从哪里来？
答案就在get_default_block_editor_settings()函数里。它就像一个大管家，负责收集、整理和提供编辑器的默认配置。
第一幕：get_default_block_editor_settings() 函数的真面目
先来看看get_default_block_editor_settings()函数的基本结构（位于wp-includes/block-editor.php）：
<?php
/**
* Retrieves the default block editor settings.
*
* @since 5.0.0
*
* @return array Default block editor settings.
*/
function get_default_block_editor_settings() {
global $post;
$settings = array(
'__experimentalFeatures' => array(), // 用于存放实验性功能的配置
'alignWide' => false, // 是否启用宽对齐选项
'allowedBlockTypes' => true, // 允许使用的块类型，true表示允许所有块
'bodyOpen' => '', // 在 `<body>` 标签后输出的内容
'canLockBlocks' => true, // 是否允许锁定块
'codeEditorSettings' => array(), // 代码编辑器设置
'defaultBlock' => '', // 默认插入的块类型
'disableCustomColors' => false, // 是否禁用自定义颜色
'disableCustomFontSizes' => false, // 是否禁用自定义字体大小
'disableCustomGradient' => false, // 是否禁用自定义渐变
'disablePostFormats' => false, // 是否禁用文章形式
'enableCustomFields' => false, // 是否启用自定义字段面板
'imageSizes' => array(), // 可用的图像尺寸
'isRTL' => is_rtl(), // 是否是RTL（从右到左）语言
'maxUploadFileSize' => wp_max_upload_size(), // 最大上传文件大小
'mediaPermalinks' => false, // 是否使用媒体文件的永久链接
'post' => null, // 当前文章对象
'preloadAssets' => array(), // 预加载的资源
'styles' => array(), // 编辑器样式
'template' => null, // 模板
'templateLock' => false, // 模板锁定
'titlePlaceholder' => null, // 标题占位符
'useFeaturedImage' => false, // 是否使用特色图像
'supportsLayout' => false, // 是否支持布局
'supportsTemplateMode' => false, // 是否支持模板模式
'__unstableEnableFullSiteEditing' => false, // 是否启用完整站点编辑
);
// ... 后续代码 ...
return $settings;
}看到了吗？这个函数返回一个庞大的数组$settings，里面包含了各种各样的键值对，每个键代表一个配置项，值则是该配置项的默认值。
第二幕：配置项逐个击破
咱们挑几个重要的配置项，详细说说：
'allowedBlockTypes' => true: 这个选项决定了编辑器里可以使用哪些块。true表示允许使用所有注册的块。如果你想限制用户只能使用某些块，可以把它设置成一个包含块名称的数组，例如array( 'core/paragraph', 'core/image' )。'disableCustomColors' => false: 这个选项决定了是否允许用户自定义颜色。false表示允许自定义颜色，true则禁用。'imageSizes' => array(): 这个选项定义了编辑器中可用的图像尺寸。WordPress会根据你设置的图像尺寸，生成不同大小的图片，方便你在编辑器中使用。'styles' => array(): 这个选项允许你添加自定义的编辑器样式。你可以用它来改变编辑器的外观，使其更符合你的主题风格。'template' => null: 这个选项允许你为文章或页面设置特定的块模板。模板可以定义文章或页面的结构，强制用户按照你的设计来排版。
第三幕：WordPress 如何修改默认配置？
get_default_block_editor_settings() 函数只是定义了默认值。WordPress 允许主题和插件通过过滤器(block_editor_settings_all)来修改这些默认配置。
add_filter( 'block_editor_settings_all', 'my_custom_block_editor_settings' );
function my_custom_block_editor_settings( $settings ) {
// 修改 allowedBlockTypes，只允许使用段落和图片块
$settings['allowedBlockTypes'] = array( 'core/paragraph', 'core/image' );
// 禁用自定义颜色
$settings['disableCustomColors'] = true;
// 添加自定义编辑器样式
$settings['styles'] = array(
array(
'name' => 'my-custom-style',
'label' => '我的自定义样式',
'style' => 'p.my-custom-style { color: red; font-weight: bold; }',
),
);
return $settings;
}这段代码做了三件事：
- 使用
add_filter函数，将my_custom_block_editor_settings函数挂载到block_editor_settings_all过滤器上。 - 在
my_custom_block_editor_settings函数中，修改了allowedBlockTypes、disableCustomColors和styles这三个配置项。 - 返回修改后的
$settings数组。
这样，当你打开编辑器时，就会发现只能使用段落和图片块，自定义颜色被禁用，并且编辑器中多了一个名为“我的自定义样式”的样式选项。
第四幕：配置项的来源
get_default_block_editor_settings()函数内部，也会调用其他函数来获取更具体的配置信息。例如：
wp_max_upload_size(): 这个函数获取WordPress允许上传的最大文件大小。is_rtl(): 这个函数判断当前语言是否是RTL（从右到左）语言。
此外，get_default_block_editor_settings()函数还会根据当前文章的类型、模板等信息，动态调整配置项的值。例如，如果当前文章使用了某个特定的模板，那么template配置项就会被设置为该模板的名称。
第五幕：实验性功能 (__experimentalFeatures)
注意get_default_block_editor_settings()函数中有一个名为__experimentalFeatures的配置项。这个配置项用于存放一些实验性功能。
'__experimentalFeatures' => array(),这些功能可能还在开发中，尚未完全稳定，所以被放在__experimentalFeatures下，以表明它们是实验性的。
可以通过过滤器block_editor_settings_all来启用或禁用这些实验性功能。
add_filter( 'block_editor_settings_all', 'my_experimental_features' );
function my_experimental_features( $settings ) {
$settings['__experimentalFeatures']['typography'] = true; // 启用 typography
$settings['__experimentalFeatures']['color'] = false; // 禁用 color
return $settings;
}第六幕：一些有趣的配置项细节
| 配置项 | 类型 | 描述 |
|---|---|---|
alignWide |
boolean | 是否启用宽对齐选项。如果启用，块可以设置为“宽”对齐，使其宽度超过内容区域。 |
bodyOpen |
string | 在 <body> 标签后输出的内容。这可以用于添加一些需要在页面加载时执行的JavaScript代码或CSS样式。 |
canLockBlocks |
boolean | 是否允许锁定块。如果允许锁定，用户可以锁定某些块，防止它们被移动、删除或修改。 |
codeEditorSettings |
array | 代码编辑器设置。这个配置项用于设置代码编辑器的各种选项，例如主题、字体大小、自动完成等。 |
defaultBlock |
string | 默认插入的块类型。当你创建一个新的文章或页面时，编辑器会自动插入这个块。 |
disablePostFormats |
boolean | 是否禁用文章形式。如果禁用，用户将无法选择文章形式，例如标准、图像、视频等。 |
enableCustomFields |
boolean | 是否启用自定义字段面板。如果启用，用户可以在编辑器中看到自定义字段面板，并添加或编辑自定义字段。 |
maxUploadFileSize |
integer | 最大上传文件大小，以字节为单位。 |
mediaPermalinks |
boolean | 是否使用媒体文件的永久链接。如果启用，媒体文件将使用永久链接，而不是默认的数字ID。 |
post |
WP_Post | 当前文章对象。这个配置项包含了当前文章的所有信息，例如标题、内容、作者、发布日期等。 |
preloadAssets |
array | 预加载的资源。这个配置项用于指定需要在编辑器加载时预加载的资源，例如JavaScript文件、CSS样式等。 |
templateLock |
string | 模板锁定。这个配置项用于锁定模板，防止用户修改模板的结构。可以设置为 all (锁定所有块) 或 insert (只允许插入新的块)。 |
titlePlaceholder |
string | 标题占位符。这个配置项用于设置标题输入框的占位符文本。 |
useFeaturedImage |
boolean | 是否使用特色图像。如果启用，编辑器将显示特色图像的选项。 |
supportsLayout |
boolean | 是否支持布局。这个选项与主题的theme.json文件相关，决定了是否支持块的布局选项。 |
supportsTemplateMode |
boolean | 是否支持模板模式。允许用户编辑文章或页面的模板。 |
__unstableEnableFullSiteEditing |
boolean | 是否启用完整站点编辑 (FSE)。这是一个不稳定的特性，允许用户使用块编辑器来编辑整个网站的结构，包括页眉、页脚等。 |
第七幕：实战演练：创建一个只允许特定块的编辑器
假设你想创建一个编辑器，只允许用户使用段落、标题和图片块。你可以这样做：
add_filter( 'block_editor_settings_all', 'my_limited_block_editor' );
function my_limited_block_editor( $settings ) {
$settings['allowedBlockTypes'] = array(
'core/paragraph',
'core/heading',
'core/image',
);
return $settings;
}这段代码会将allowedBlockTypes设置为一个包含core/paragraph、core/heading和core/image的数组，从而限制用户只能使用这三个块。
第八幕：结合theme.json文件进行配置
WordPress的theme.json文件也对编辑器的配置起着重要的作用。它可以用来设置颜色、字体、布局等各种选项。get_default_block_editor_settings()函数会读取theme.json文件中的配置，并将其合并到默认配置中。
例如，你可以在theme.json文件中设置默认的字体大小：
{
"settings": {
"typography": {
"fontSizes": [
{
"name": "Small",
"size": "16px",
"slug": "small"
},
{
"name": "Normal",
"size": "18px",
"slug": "normal"
},
{
"name": "Large",
"size": "20px",
"slug": "large"
}
]
}
}
}这样，在编辑器中，用户就可以选择 Small、Normal 和 Large 这三个字体大小。
第九幕：调试技巧
如果你想查看get_default_block_editor_settings()函数返回的完整配置信息，可以使用var_dump()函数：
add_filter( 'block_editor_settings_all', 'debug_block_editor_settings' );
function debug_block_editor_settings( $settings ) {
echo '<pre>';
var_dump( $settings );
echo '</pre>';
return $settings;
}这段代码会将完整的配置信息输出到页面上，方便你进行调试。记得在调试完成后，移除这段代码。
总结：get_default_block_editor_settings() 函数的意义
get_default_block_editor_settings()函数是WordPress编辑器配置的核心。它定义了编辑器的默认配置，并允许主题和插件通过过滤器来修改这些配置。理解了这个函数的工作原理，你就可以更好地控制编辑器的行为，定制出符合你需求的编辑器。
希望今天的讲解对你有所帮助。下次有机会再和大家分享更多WordPress的知识。谢谢大家！