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

作者 : King 本文共10606个字，预计阅读时间需要27分钟发布时间： 2025-05-11 共74人阅读

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 图像区块

带有双色调滤镜的 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 blockif ( '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" styleunregister_block_style( 'core/image', 'rounded' );// Register a new "Rounded" style with custom CSSregister_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 previewconst 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，我们可以一起使用它们来解决一个问题：保持设计的一致性，同时为用户分享应用正确样式的结构化方法。

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

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

为此，我们需要

使用样式 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);

有了这一点：