Block Variations 完全指南：WordPress 区块变体实战教程

发布于2024年7月2日2026年7月30日作者:XQcms

Block Variations（区块变体）是 WordPress 区块编辑器（Gutenberg）中一个具实用性的功能，允许开发者基于现有区块创建预设好的“变体版本”。打个比方，默认的“社交图标”区块只有一个，但 WordPress 内置了 Facebook、Twitter、YouTube 等几十种社交平台的变体，它们本质上是同一个区块，只是预设了不同的链接和图标——这就是 Block Variations 的典型应用场景。

本文会从零开始，带你理清 Block Variations 的概念、它与 Block Styles 的区别，以及如何在主题中注册、使用和移除区块变体。所有示例代码均基于 WordPress 官方新实践，无需构建工具即可直接运行。无论你是主题开发者还是插件作者，掌握这个 API 都能让你的编辑体验更上一层楼。

一、什么是 Block Variations？

Block Variations（区块变体）可以理解为某个区块的“预设版本”。它的核心价值在于：让用户插入区块时免去重复设置的麻烦。

举个例子，WordPress 的“社交图标”区块（Social Icons）本身只是一个空壳，但官方通过 Block Variations 预先定义了数十种社交平台的图标变体。用户插入时直接选择即可，无需手动输入每个平台的名称和图标——这正是 Block Variations 的设计初衷。

变体 vs 样式：别再混淆

这是新手容易踩的坑。一句话讲清楚：

Block Styles（区块样式）：改变区块的外观表现，通常通过 CSS 实现。比如让按钮从圆角变成直角，或者改变引用的背景色。
Block Variations（区块变体）：改变区块的内部配置，比如预设一组属性值、嵌套区块等。它影响的是区块的“初始状态”，而非样式。

选择标准：如果你的改动可以用 theme.json 或几行 CSS 搞定，就用 Block Styles。如果需要预设 attributes（属性）、innerBlocks（嵌套区块）或者更改默认值，那就得用 Block Variations。

二、实战：从零创建一个区块变体

一步：加载 JavaScript 文件

Block Variations 必须在编辑器环境（后台）中通过 JavaScript 注册。首先在主题目录下创建文件：/assets/js/block-variations.js。

然后，在主题的 functions.php 中加载这个脚本：

php

add_action( 'enqueue_block_editor_assets', 'theme_prefix_enqueue_block_variations' );

function theme_prefix_enqueue_block_variations() {
    wp_enqueue_script(
        'theme-prefix-block-variations',                // 句柄，标识
        get_theme_file_uri( 'assets/js/block-variations.js' ), // 文件路径
        array( 'wp-blocks', 'wp-dom-ready', 'wp-i18n' ),      // 依赖项
        wp_get_theme()->get( 'Version' ),                     // 版本号
        true                                                  // 在页脚加载
    );
}

这段代码的作用是在编辑器加载时引入我们的 JavaScript 文件。注意 dependencies（依赖项）中声明了 wp-blocks、wp-dom-ready 和 wp-i18n，它们分别提供注册变体的 API、DOM 就绪事件和国际化翻译函数。

二步：注册变体

打开 block-variations.js，开始注册我们的一个变体。以一个“大间距分隔符”为例，让 Spacer 区块默认高度为 180px：

javascript

const { registerBlockVariation } = wp.blocks;
const { __ } = wp.i18n;

registerBlockVariation( 'core/spacer', {
    name: 'theme-prefix/large-spacer',           // 标识，建议加前缀
    title: __( '大分隔符', 'theme-prefix' ),      // 显示名称
    description: __( '预设 180px 高度的分隔符', 'theme-prefix' ),
    keywords: [ 'space', 'spacer', 'large' ],    // 搜索关键词
    attributes: {
        height: '180px'                          // 覆盖默认属性
    },
    isActive: ( blockAttributes ) => {
        // 判断当前区块是否为此变体
        return blockAttributes.height === '180px';
    }
} );

关键参数解读：

name：必填，变体的标识，建议加上主题或插件前缀避免冲突。
attributes：这里可以覆盖原区块的任何属性。Spacer 的核心属性是 height，我们将其设为 180px。
isActive：一个函数，当编辑器选中某个区块时，通过比对属性值来判断该区块是否属于这个变体。返回 true 则变体高亮显示。

注册完成后，在编辑器插入 Spacer 区块时，就能看到“大分隔符”这个变体选项了。

三步：移除变体

如果你不想让某个变体出现在编辑器中，可以使用 unregisterBlockVariation。

注意：移除操作必须放在 wp.domReady 回调中，以确保所有变体都已注册完毕：

javascript

wp.domReady( () => {
    wp.blocks.unregisterBlockVariation( 
        'core/spacer', 
        'theme-prefix/large-spacer' 
    );
} );

这样做的好处是，你可以根据条件（比如当前页面模板、用户角色等）动态决定是否移除某个变体。

三、进阶：打造一个“文章查询”变体

Block Variations 的价值不仅在于设置简单的属性，它还能预设复杂的 innerBlocks（嵌套区块）。我们以“首页精选文章”为例，创建一个预设了查询条件、标题和文章列表的 Query Loop 变体：

javascript

registerBlockVariation( 'core/query', {
    name: 'theme-prefix/featured-posts',
    title: __( '精选文章列表', 'theme-prefix' ),
    attributes: {
        query: {
            perPage: 5,           // 每页显示 5 篇
            order: 'desc',
            orderBy: 'date',
            sticky: 'exclude'     // 不显示置顶文章
        }
    },
    innerBlocks: [
        [
            'core/post-title',
            { 
                level: 3,
                isLink: true
            }
        ],
        [
            'core/post-excerpt',
            { 
                excerptLength: 20 
            }
        ]
    ],
    isActive: ( attrs ) => {
        return attrs.query?.perPage === 5 && 
               attrs.query?.sticky === 'exclude';
    }
} );

当用户插入这个变体时，会自动创建一个包含标题和摘要的文章列表，且查询参数已预先配置好——这就是 Block Variations 在复杂场景下的真正威力。

四、值得注意的细节

1. 作用域（Scope）控制

通过 scope 参数，你可以控制变体在哪些地方可用：

javascript

scope: [ 'block', 'inserter' ]  // 仅在编辑器和插入器中可用

可选值包括 block（编辑时）、inserter（插入器）、transform（转换时）。如果不指定，默认全部开启。

2. 设置为默认变体

将 isDefault 设为 true，可以让该变体成为区块的默认版本。当用户插入区块未作选择时，自动使用这个配置。

3. 国际化支持

所有面向用户的文本（title、description、keywords）都应该用 __( '文本', 'text-domain' ) 包裹，以便翻译。

4. 属性获取小技巧

想要覆盖某个区块的属性，直接的方法是查阅 WordPress 官方文档或直接在源码中搜索该区块的 attributes 定义。比如 Spacer 的 height、Query Loop 的 query 对象。

五、总结

Block Variations 是 WordPress 主题和插件开发中不可忽视的利器。它让你能以低的成本为用户提供更智能的编辑体验，减少重复操作。掌握这项技能后，你可以：

为常用区块预设符合主题风格的默认值
创建复杂的嵌套区块模板（如首页布局、产品列表等）
根据业务场景动态启用或禁用变体选项

关键在于理清它与 Block Styles 的边界，并在实际项目中灵活运用。如果你的主题需要为用户提供“开箱即用”的编辑体验，Block Variations 绝对值得认真研究。

后一个小贴士：Block Variations 虽然方便，但也要克制使用——变体太多会让插入器变得臃肿。始终从用户真实需求出发，而非为了技术而技术。