如何使用区块API扩展WordPress核心区块

2018 年，WordPress 在 5.0 版本中引入了 Gutenberg 编辑器，带来了一种使用“区块”构建页面和帖子的新方法。起初，这些区块非常基本，但经过多年的发展，它们已经提供了更大的灵活性和更好的编辑体验。

不过，有时区块并不能完全满足你的需求。也许你想删除某些功能、添加新功能、默认应用特定样式，或者让某些设置更容易访问。在这种情况下，从头开始创建一个自定义区块似乎是一个不错的选择，但老实说，这对于一些小的调整来说实在是太麻烦了。如果能修改已经存在的区块，岂不是更简单？

这就是 Blocks API 的用武之地。本文将介绍如何使用 Blocks API 扩展 WordPress 核心区块，并提供可用于实际项目的实用示例。

了解WordPress区块API

WordPress 区块 API 是区块编辑器的基础，允许开发人员创建、修改和扩展块。API 提供了与区块交互的多种方式。您可以

• 修改区块设置 – 更改区块属性、默认值和行为。
• 添加或移除区块支持 – 启用或禁用排版、颜色和间距等功能。
• 注入自定义控件 – 在区块设置面板中添加新选项。
• 创建区块变体 – 制作现有区块的预配置版本，加快内容创建速度。

WordPress 中的每个区块，无论是段落区块、图片区块还是按钮区块，都由存储在 block.json 文件中的一组属性和设置来定义。该文件包含有关块的元数据，包括其名称、类别、默认属性和支持的功能。

WordPress允许您使用 PHP 或 JavaScript 修改这些值，但本文将解释如何使用块API中的过滤钩子。这可以确保您的修改在服务器上注册，而不需要调用额外的JavaScript文件。

例如，如果您想启用或禁用块的某些功能，最好的方法是使用 PHP 中的 register_block_type_args 过滤器。这种方法可以动态调整区块设置，而无需直接修改block.json文件。

修改区块支持

WordPress 区块带有预定义的支持，可以控制编辑器的选项。有些区块，如图片区块（core/image），默认启用了双色调滤镜，允许用户应用颜色叠加。

带有双色调滤镜的 WordPress 图像区块。

然而，尽管媒体和文本区块（core/media-text）允许用户插入图片，但它并不支持双色调。这意味着，虽然您可以在独立的图像块中应用双色调滤镜，但当图像被放置在媒体和文本区块中时，您就无法应用双色调滤镜了。

不支持双色调的媒体和文本区块

由于“媒体和文本”区块可以包含图片，因此启用双色调过滤器是合理的。我们可以通过修改 supports 数组并指定正确的 CSS 选择器来启用双色调滤镜，这样过滤器就能正确应用了。我们可以使用 PHP 中的 register_block_type_args 过滤器启用它。

将以下代码添加到主题的 functions.php 文件中：

重要提示：如果您要将此添加到主题的 functions.php 文件中，最好在子主题中添加，以防主题更新时丢失更改。

function enable_duotone_for_media_text_block($args, $block_type) {
// Only modify the Media & Text block
if ( 'core/media-text' === $block_type ) {
$args['supports'] ??= [];
$args['supports']['filter'] ??= [];
$args['supports']['filter']['duotone'] = true;
$args['selectors'] ??= [];
$args['selectors']['filter'] ??= [];
$args['selectors']['filter']['duotone'] = '.wp-block-media-text .wp-block-media-text__media';
}
return $args;
}
add_filter('register_block_type_args', 'enable_duotone_for_media_text_block', 10, 2);

上面的代码在 supports 数组中启用了双色过滤器，并定义了正确的 CSS 选择器，以便将双色效果应用到 Media & Text 块中的图片。add_filter() 函数使用 10 作为优先级（过滤器运行时），并使用 2 来指定传递的参数数（$args,$block_type ）。

保存文件并重新加载后，您将在“过滤器”部分看到可用的 Duotone 控件。

启用双色调滤镜

使用 register_block_type_args 为媒体和文本块启用双色调是动态修改区块行为的有效方法。不过，WordPress还提供了另一种修改区块设置的方法：使用 block_type_metadata  覆盖区块元数据。

这两种方法都可以自定义区块，但它们在区块注册过程的不同阶段起作用。

例如，我们想调整段落块（core/paragraph），使其只支持边距调整并禁用填充。一种方法是使用 register_block_type_args ：

function modify_paragraph_spacing_args($args, $block_type) {
if ($block_type === 'core/paragraph') {
$args['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $args;
}
add_filter('register_block_type_args', 'modify_paragraph_spacing_args', 10, 2);

这种方法在大多数情况下都很有效，但由于它是在区块已注册后才对其进行修改，因此有时会被后来修改同一区块的其他插件或主题所覆盖。

在这种情况下，一种更有条理的方法是使用 block_type_metadata 直接覆盖区块的元数据：

function mytheme_modify_paragraph_spacing($metadata) {
if ($metadata['name'] === 'core/paragraph') {
$metadata['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $metadata;
}
add_filter('block_type_metadata', 'mytheme_modify_paragraph_spacing');

这两种方法在本质上都没有优劣之分，只是取决于你想在什么时候修改区块，以及你希望这种修改有多持久。

注册区块样式

许多 WordPress 区块都有预定义的样式，用户可以在编辑器中进行选择。图片区块（core/image）就是一个很好的例子，它默认包含一个圆角样式。然而，默认的圆角往往过于极端，使图片看起来更像一个椭圆形，而不是一个风格整齐的元素。

默认圆角样式

与手动调整每张图片的边框半径相比，更好的方法是自定义圆角样式，使其应用更精细的圆角半径–也许可以添加一个微妙的阴影来营造现代感。这样，用户只需点击一个按钮，就能应用精心设计的样式，而无需每次都手动调整设置。

让我们使用图像块中的圆角样式，对其进行自定义，使边角略微变圆，而不是过度弯曲，并添加一个微妙的方框阴影，使其看起来更加精致。

由于块编辑器允许注册和取消注册块样式，因此我们可以删除默认的圆角样式，取而代之的是自定义版本。

具体方法如下：

function modify_image_block_rounded_style() {
// Remove the default "Rounded" style
unregister_block_style( 'core/image', 'rounded' );
// Register a new "Rounded" style with custom CSS
register_block_style(
'core/image',
array(
'name'         => 'rounded',
'label'        => __( 'Rounded', 'your-text-domain' ),
'inline_style' => '
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjust this value */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Optional shadow */
}
',
)
);
}
add_action( 'init', 'modify_image_block_rounded_style' );

该代码将默认的过于圆润的样式替换为精致的版本，应用 border-radius: 20px; 使边角更加柔和，并应用 box-shadow 使边角得到微妙的提升。

精致的圆角样式

使用外部CSS文件代替内联样式

虽然内联样式对于简单样式很有效，但对于可维护性来说并不理想。更好的方法是在外部 CSS 文件中定义样式，然后将其调用。

为此，请创建一个新的 CSS 文件，例如，custom-block-styles.css，并将此添加到该文件中：

/* Custom Rounded Image Block Style */
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjusted rounded corners */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Subtle shadow */
}

接下来，在functions.php 中调用 CSS 文件：

function enqueue_custom_block_styles() {
wp_enqueue_style(
'custom-block-styles',
get_template_directory_uri() . '/css/custom-block-styles.css',
array(),
'1.0'
);
}
add_action('wp_enqueue_scripts', 'enqueue_custom_block_styles');
add_action('enqueue_block_editor_assets', 'enqueue_custom_block_styles');

现在，您可以不使用内联样式，而直接在 PHP 中嵌入 CSS 来注册样式：

register_block_style(
'core/image',
array(
'name'  => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'style_handle' => 'custom-block-styles'
)
);

这样，您就可以在不接触 PHP 的情况下修改样式。

注册区块变体

区块变体可让你创建具有自定义设置的预定义区块版本，使用户只需单击一下就能更轻松地应用一致的设计。变体允许你插入一个已经应用了正确属性、样式或配置的块，而不是每次都手动修改块的设置。

WordPress 的一些核心区块实际上就是这样工作的。嵌入区块并不是一个单独的区块，它是针对 YouTube、Twitter 和 Spotify 等不同平台的一组变体。Row 区块和 Stack 区块也只是 Group 区块的变体，每个块都有不同的布局设置。

这种方法保持了模块化，允许 WordPress 在使用共享底层结构的同时提供量身定制的体验。

创建引言区块的“推荐”变体

虽然 WordPress 没有专门的“推荐”区块，但“引言”区块（core/quote）可用于此目的。我们可以定义“引言”区块的“推荐”变体，而不是让用户手动添加图片、对齐文本和格式化所有内容。

这种变体会自动包含一个图片区块、一个引用区块和两个段落区块，分别用于标注人名和公司。这样就能确保每篇推荐信都遵循相同的结构格式，而无需额外调整。

要在 WordPress 中注册一个区块变体，我们使用 JavaScript 中的 registerBlockVariation()。由于区块变体是在客户端处理的，因此我们需要调用一个 JavaScript 文件来注册我们的自定义推荐变体。

要实现这一点，请创建一个 JavaScript 文件（如custom-block-variations.js ）来定义“引言”区块的“推荐”变体。您可以在主题的 assets/js/ 目录中创建该文件，并添加以下代码：

wp.domReady(() => {
wp.blocks.registerBlockVariation(
'core/quote',
{
name: 'testimonial',
title: 'Testimonial',
description: 'A variation of the Quote block for testimonials.',
category: 'text',
attributes: {
className: 'is-style-testimonial',
},
innerBlocks: [
['core/image', { align: 'center', width: 100, height: 100 }],
['core/quote'],
['core/paragraph', { placeholder: 'Name', align: 'center', fontSize: 'medium', className: 'testimonial-name' }],
['core/paragraph', { placeholder: 'Company / Role', align: 'center', fontSize: 'small', className: 'testimonial-company' }]
],
scope: ['inserter'],
}
);
// Inject inline styles for the editor preview
const style = document.createElement('style');
style.innerHTML = `
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial p {
margin-bottom: 12px;
font-size: 1.1em;
}
.wp-block-quote.is-style-testimonial cite {
font-weight: bold;
display: block;
margin-top: 10px;
color: #0073aa;
}
.wp-block-quote.is-style-testimonial .wp-block-image {
display: flex;
justify-content: center;
margin: 0 auto 12px;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
`;
document.head.appendChild(style);
});

在上面的代码中，registerBlockVariation() 定义了“引语”区块的“推荐”变体，预先加载了一个图片区块、一个“引语”区块和两个段落区块，分别代表个人姓名和公司。图片区块以 100×100 像素为中心，用于显示统一的个人资料图片，而引用语区块则保持不变，作为推荐文字。

自定义类（is-style-testimonial）被应用于样式设计，使块具有浅色背景、微妙的阴影和居中的文本。去掉了默认的左边框，图片保持长宽比，边角略呈圆角，看起来更有质感。

接下来，由于 JavaScript 文件需要在区块编辑器中加载，我们必须在 functions.php 中调用 JavaScript 文件。

function enqueue_custom_block_variations() {
wp_enqueue_script(
'custom-block-variations',
get_template_directory_uri() . '/assets/js/custom-block-variations.js',
array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
filemtime( get_template_directory() . '/assets/js/custom-block-variations.js' ),
true
);
}
add_action( 'enqueue_block_editor_assets', 'enqueue_custom_block_variations' );

这将确保“推荐”区块的变化出现在区块编辑器中。

JavaScript 代码可确保区块在编辑器中显示正确，但我们还需要在前端应用样式，以便在发布时正确显示推荐语。在 functions.php 中添加以下代码

function register_testimonial_block_style() {
register_block_style(
'core/quote',
array(
'name'  => 'testimonial',
'label' => __( 'Testimonial', 'your-text-domain' ),
'inline_style' => '
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
',
)
);
}
add_action( 'init', 'register_testimonial_block_style' );

现在，每当用户插入一个推荐语区块时，它已经包含了图片、引语、姓名和公司字段，所有字段都已预先格式化，并且样式正确。这样就不需要手动调整，确保每个推荐都遵循同样简洁和专业的结构。

推荐语区块变体

这个区块变体没有强迫用户从头开始创建推荐信，而是提供了一个简化的工作流程，在保持网站设计一致性的同时增强了内容创建能力。

高级用例：结合支持和样式 API 创建品牌按钮

既然您已经知道了每个 API 的功能和工作原理，我们为什么不再进一步呢？与其单独使用 Supports API 或 Styles API，我们可以一起使用它们来解决一个问题：保持设计的一致性，同时为用户提供应用正确样式的结构化方法。

让我们考虑一个现实世界中的场景。一家公司希望其网站上的所有按钮都严格遵循品牌准则。他们不希望用户随意选择颜色、改变填充或应用时髦的排版。不过，他们也希望按钮具有灵活性，因此用户可以在两种预先批准的按钮样式中进行选择：

1. 主按钮 – 主要的行动号召按钮，采用纯色背景和粗体样式。
2. 副按钮 -更微妙的勾勒按钮，通常用于次要操作。

为此，我们需要

• 使用样式 API 定义两种按钮样式。
• 使用支持 API 删除不必要的设置，确保用户不会通过更改颜色、间距或排版来手动覆盖品牌。

通过将这两个 API 结合使用，我们既能提供结构化的选择，又能防止用户破坏设计系统。

Step 1：定义自定义按钮样式

首先在 functions.php 文件中添加以下代码：

function register_custom_button_styles() {
register_block_style(
'core/button',
array(
'name'  => 'primary-button',
'label' => __( 'Primary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-primary-button .wp-block-button__link {
background-color: #4D4D4D;
color: #ffffff;
padding: 12px 24px;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: 2px 2px 6px rgba(0, 0, 0, 0.1);
}
',
)
);
register_block_style(
'core/button',
array(
'name'  => 'secondary-button',
'label' => __( 'Secondary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-secondary-button .wp-block-button__link {
background-color: transparent;
color: #4D4D4D;
padding: 12px 24px;
border: 1px solid #4D4D4D;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: none;
}
',
)
);
}
add_action( 'init', 'register_custom_button_styles' );

现在，当用户插入按钮块时，他们会看到主按钮和副按钮作为样式选择。

自定义按钮样式

主按钮的背景是纯深灰色，而次按钮的背景是带边框的透明背景。两个按钮的填充、边框半径和字体样式都保持一致，确保整个网站的专业外观。

Step 2：限制按钮定制

虽然按钮样式现在是预定义的，但用户仍然可以使用 WordPress 的块编辑器设置手动覆盖它们。如果他们更改了颜色、衬垫或排版，按钮就可能不再符合品牌准则。

我们可以使用支持 API 禁用这些自定义选项，防止用户进行意外更改。将此添加到 functions.php 中：

function restrict_button_customization($args, $block_type) {
if ($block_type === 'core/button') {
// Disable specific color settings (text, background, link)
$args['supports']['color'] = [
'text'       => false, 
'background' => false, 
'link'       => false,  
];
// Disable typography settings (font size, font weight, line height)
$args['supports']['typography'] = false;
// Disable spacing settings (padding, margin)
$args['supports']['spacing'] = false;
}
return $args;
}
add_filter('register_block_type_args', 'restrict_button_customization', 10, 2);

有了这一点：

• 用户无法更改按钮颜色，因此所有按钮都必须符合品牌的配色方案。
• 删除排版控制，保持文本格式一致。
• 间距调整被禁用，用户无法修改填充和边距。

主按钮样式

现在，用户不用再随意创建按钮样式，只需在主样式和次样式之间进行选择，从而保持设计的专业性和条理性。

小结

我们只是从表面上了解了 WordPress 区块定制的可能性。WordPress 提供了大量的应用程序接口（API），可以轻松扩展和自定义区块，让开发人员可以定制编辑器体验，同时保持结构合理和用户友好。