WordPress区块API使用教程：扩展核心区块功能

2018年，WordPress在5.0版本中推出了革命性的Gutenberg编辑器，引入了基于“区块”的页面和帖子构建方式。这一创新彻底改变了内容创作流程，最初虽然区块功能相对基础，但经过多年的迭代发展，如今已展现出惊人的灵活性和卓越的编辑体验。然而，在某些场景下，标准区块仍无法完全满足个性化需求。或许你需要精简某些功能、增添新特性、预设特定样式，或是让某些设置更易于访问。此时，开发一个全新的自定义区块固然可行，但对于细微调整而言，这显然过于繁琐。有没有更简单高效的方法呢？答案就是——修改现有的区块，这正是Blocks API大显身手的地方。本文将深入探讨如何借助Blocks API扩展WordPress核心区块，并提供多个实用案例供实际项目参考。

### 了解WordPress区块API

WordPress区块API是区块编辑器的基石，赋予开发人员创建、修改和扩展区块的强大能力。通过这一API，你可以：

– **修改区块设置**：灵活调整区块属性、默认值和行为
– **添加或移除区块支持**：控制排版、颜色和间距等功能的可用性
– **注入自定义控件**：在区块设置面板中添加个性化选项
– **创建区块变体**：制作预配置的区块版本，提升内容创作效率

每个WordPress区块——无论是段落、图片还是按钮——都由block.json文件定义的一组属性和设置构成。该文件存储着区块的元数据，包括名称、类别、默认属性和支持的功能。WordPress允许通过PHP或JavaScript修改这些值，但本文将重点介绍如何利用区块API中的过滤钩子实现这一目标。这种方法能确保修改在服务器端生效，无需额外加载JavaScript文件。

### 修改区块支持

WordPress区块自带预定义的支持功能，可控制编辑器的各项选项。以图片区块（core/image）为例，它默认支持双色调滤镜，允许用户添加颜色叠加效果。然而，媒体和文本区块（core/media-text）虽然支持插入图片，却缺少这一功能。这意味着在独立图片区块中可用的双色调滤镜，在媒体和文本区块中就无法应用。

为了解决这个问题，我们可以通过修改supports数组并指定正确的CSS选择器来启用双色调滤镜。以下是具体实现方法：

“`php
function enable_duotone_for_media_text_block($args, $block_type) {
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选择器，确保滤镜能正确应用于媒体和文本区块中的图片。add_filter()函数使用10作为优先级，并指定传递两个参数（$args,$block_type）。

保存文件后重新加载，你将在过滤器部分看到可用的Duotone控件。除了register_block_type_args，WordPress还提供了另一种修改区块设置的方法：使用block_type_metadata覆盖区块元数据。这两种方法都能实现区块自定义，但它们在区块注册过程的不同阶段发挥作用。

### 注册区块样式

许多WordPress区块都提供预定义样式供用户选择，图片区块（core/image）就是一个典型例子。默认的圆角样式往往过于夸张，影响视觉效果。与其手动调整每张图片的边框半径，不如自定义一个更精致的圆角样式，比如添加微妙的阴影来增强现代感。这样，用户只需点击一个按钮，就能应用精心设计的样式，无需重复手动调整。

以下是自定义图片区块圆角样式的代码：

“`php
function modify_image_block_rounded_style() {
// 移除默认的”Rounded”样式
unregister_block_style(‘core/image’, ’rounded’);

// 注册新的”Rounded”样式
register_block_style(‘core/image’, [
‘name’ => ’rounded’,
‘label’ => __(‘Rounded’, ‘your-text-domain’),
‘inline_style’ => ‘.wp-block-image.is-style-rounded img {
border-radius: 20px; /* 可调整此值 */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* 可选阴影 */
}’
]);
}
add_action(‘init’, ‘modify_image_block_rounded_style’);
“`

这段代码将默认的过度圆润的样式替换为更精致的版本，通过border-radius: 20px;使边角更柔和，并添加box-shadow产生微妙提升效果。

虽然内联样式适用于简单场景，但为了更好的可维护性，建议使用外部CSS文件。创建custom-block-styles.css文件，添加以下内容：

“`css
/* Custom Rounded Image Block Style */
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* 调整后的圆角 */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* 微妙阴影 */
}
“`

然后在functions.php中调用这个CSS文件：

“`php
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来注册样式：

“`php
register_block_style(‘core/image’, [
‘name’ => ’rounded’,
‘label’ => __(‘Rounded’, ‘your-text-domain’),
‘style_handle’ => ‘custom-block-styles’
]);
“`

这样，无需直接修改PHP代码，就能轻松修改样式。

### 注册区块变体

区块变体允许创建具有预设设置的区块版本，用户只需单击即可应用一致的设计。变体让用户插入已应用正确属性、样式或配置的区块，而非每次手动修改设置。WordPress的一些核心区块实际上就是变体的应用，如嵌入区块包含YouTube、Twitter和Spotify等平台的变体，Row区块和Stack区块也只是Group区块的不同布局变体。

创建引言区块（core/quote）的”推荐”变体是一个很好的实践。虽然WordPress没有专门的”推荐”区块，但引言区块可用于此目的。我们可以定义一个包含图片区块、引言区块和两个段落区块的变体，分别用于标注人名和公司，确保每篇推荐信都遵循统一结构。

以下是注册引言区块”推荐”变体的JavaScript代码：

“`javascript
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’]
});

// 添加编辑器预览样式
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);
});
“`

这段代码定义了引言区块的”推荐”变体，预先加载了图片区块、引言区块和两个段落区块。图片区块以100×100像素为中心，用于显示统一的个人资料图片；引言区块保持不变，作为推荐文字。自定义类is-style-testimonial被应用于样式设计，使区块具有浅色背景、微妙阴影和居中文本，去掉了默认左边框，图片保持长宽比，边角略呈圆角，更显质感。

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

“`php
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中添加以下代码：

“`php
function register_testimonial_block_style() {
register_block_style(‘core/quote’, [
‘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，我们可以解决一个实际问题：保持设计一致性，同时为用户提供应用正确样式的结构化方法。

假设一家公司希望其网站上的所有按钮都严格遵循品牌准则，不允许用户随意选择颜色、改变填充或应用特殊排版。但同时也希望按钮具有灵活性，因此用户可以在两种预先批准的按钮样式中选择：

– 主按钮：主要行动号召按钮，采用纯色背景和粗体样式
– 副按钮：更微妙的轮廓按钮，用于次要操作

以下是结合这两个API实现这一目标的步骤：

**第一步：定义自定义按钮样式**

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

“`php
function register_custom_button_styles() {
register_block_style(‘core/button’, [
‘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’, [
‘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’);
“`

现在，当用户插入按钮块时，他们会看到主按钮和副按钮作为样式选项。主按钮采用纯深灰色背景，副按钮则是带边框的透明背景。两个按钮的填充、边框半径和字体样式都保持一致，确保整个网站的专业外观。

**第二步：限制按钮定制**

虽然按钮样式现在是预定义的，但用户仍然可以使用WordPress的块编辑器设置手动覆盖它们。如果他们更改了颜色、填充或排版，按钮就可能不再符合品牌准则。我们可以使用Supports API禁用这些自定义选项，防止用户进行意外更改：

“`php
function restrict_button_customization($args, $block_type) {
if ($block_type === ‘core/button’) {
// 禁用特定颜色设置
$args[‘supports’][‘color’] = [ ‘text’ => false, ‘background’ => false, ‘link’ => false ];
// 禁用排版设置
$args[‘supports’][‘typography’] = false;
// 禁用间距设置
$args[‘supports’][‘spacing’] = false;
}
return $args;
}
add_filter(‘register_block_type_args’, ‘restrict_button_customization’, 10, 2);
“`

有了这个设置：用户无法更改按钮颜色，因此所有按钮都必须符合品牌的配色方案；删除排版控制，保持文本格式一致；间距调整被禁用，用户无法修改填充和边距。主按钮样式现在更加规范，用户只需在主样式和次样式之间进行选择，从而保持设计的专业性和条理性。

### 小结

我们只是初步探索了WordPress区块定制的可能性。WordPress提供了丰富的API，可以轻松扩展和自定义区块，让开发人员能够定制编辑器体验，同时保持结构合理和用户友好。通过合理运用Blocks API，你可以创建更灵活、更强大的编辑器，为用户提供更流畅的内容创作体验。无论是修改区块支持、注册区块样式，还是创建区块变体，这些技术都能帮助你打造出符合特定需求的WordPress编辑器，让内容创作变得更加高效和便捷。