gutenbergdocs/docs/reference-guides/block-api/block-variations.md

区块变体

区块变体API允许您为区块定义多个版本（变体）。区块变体通过一组初始属性或内部区块与原始区块区分开来。当您将区块变体插入编辑器时，这些属性和/或内部区块会被应用。

变体是在不从头构建全新区块的情况下，创建现有区块迭代版本的绝佳方式。

为了更好地理解此API，请以嵌入区块为例。该区块包含多种可嵌入内容类型（WordPress、YouTube等）的众多变体。每个嵌入区块变体共享相同的底层功能，如编辑、保存等。除了名称和描述信息外，主要区别在于providerNameSlug属性。以下是嵌入区块变体的简化示例。完整规范请查看源代码。

variations: [
	{
		name: 'wordpress',
		title: 'WordPress',
		description: __( '嵌入WordPress文章。' ),
		attributes: { providerNameSlug: 'wordpress' },
	},
	{
		name: 'youtube',
		title: 'YouTube',
		description: __( '嵌入YouTube视频。' ),
		attributes: { providerNameSlug: 'youtube' },
	},
],

定义区块变体

区块变体通过包含以下字段的对象定义：

• name（类型string）– 唯一且机器可读的名称
• title（可选，类型string）– 人类可读的变体标题
• description（可选，类型string）– 人类可读的变体描述
• category（可选，类型string）- 在搜索界面中用于按分类排列区块类型的分类标识
• keywords（可选，类型string[]）- 帮助用户在搜索时发现变体的术语数组（可翻译）
• icon（可选，类型string | Object）– 帮助可视化变体的图标，可与区块类型保持相同样式
• attributes（可选，类型Object）– 覆盖区块属性的值
• innerBlocks（可选，类型Array[]）– 嵌套区块的初始配置
• example（可选，类型Object）– 为区块预览提供结构化数据。设置为undefined可禁用预览。详见区块注册API
• scope（可选，类型WPBlockVariationScope[]）- 默认为block和inserter。变体适用的作用域列表，可用选项包括：
  • block - 被区块用于筛选特定区块变体。Columns和Query区块包含此类变体，这些变体会传递给实验性BlockVariationPicker组件，该组件负责显示变体并允许用户选择
  • inserter - 在插入器中显示区块变体
  • transform - 在变体转换组件中显示区块变体
• isDefault（可选，类型boolean）– 默认为false。指示当前变体是否为默认变体（详见下文）
• isActive（可选，类型Function|string[]）- 用于确定选中区块时变体是否处于活动状态的函数或区块属性数组。该函数接受blockAttributes和variationAttributes参数（详见下文）

从技术上讲，您可以创建没有唯一name的区块变体，但不推荐这样做。唯一的name允许编辑器区分您的变体与其他可能存在的变体，还允许在需要时注销您的变体，并对isDefault设置产生影响（详见下文）。

创建区块变体

在区块注册过程中，可通过为variations键提供规范的变体对象数组来声明区块变体，如上例所示。更多详细信息请参阅区块注册API。

若要为现有区块（如核心区块）创建变体，请使用wp.blocks.registerBlockVariation()。该函数接受区块名称和定义变体的对象。

wp.blocks.registerBlockVariation( 'core/embed', {
	name: 'custom-embed',
	attributes: { providerNameSlug: 'custom' },
} );

通过PHP注册区块变体

区块变体也可使用get_block_type_variations过滤器钩子在PHP中注册。当需要基于已注册的文章类型、分类法或其他WordPress数据动态生成变体时，这种方法特别有用。

以下是为core/image区块注册自定义变体的示例：

function my_custom_image_variation( $variations, $block_type ) {
    // 仅修改图片区块的变体
    if ( 'core/image' !== $block_type->name ) {
        return $variations;
    }

    // 添加自定义变体
    $variations[] = array(
		'name'        => 'wide-image',
		'title'       => __( '宽幅图片', 'textdomain' ),
		'description' => __( '宽幅图片', 'textdomain' ),
		'scope'       => array( 'inserter' ),
		'isDefault'   => false,
		'attributes'  => array(
			'align' => 'wide', // 标识为自定义链接类型
		),
    );

    return $variations;
}
add_filter( 'get_block_type_variations', 'my_custom_image_variation', 10, 2 );

当请求区块类型的变体时会调用get_block_type_variations过滤器。它接收两个参数：

• $variations：当前已注册的区块类型变体数组
• $block_type：完整的区块类型对象

注意：通过PHP注册的变体将与使用registerBlockVariation()通过JavaScript注册的任何变体合并。

查看如何使用PHP注册区块变体博客文章获取更多信息

移除区块变体

区块变体也可以轻松移除。为此，请使用wp.blocks.unregisterBlockVariation()。该函数接受区块名称和需要注销的变体name。

wp.blocks.unregisterBlockVariation( 'core/embed', 'youtube' );

区块变体与区块样式

区块样式与区块变体的主要区别在于：区块样式仅向区块应用CSS类，从而能以替代方式进行样式设计。更多详细信息请参阅区块样式API。

若要设置初始属性或内部区块，则属于区块变体范畴。在定义区块变体时，也可以通过className属性覆盖默认区块样式。

variations: [
	{
		name: 'blue',
		title: __( '蓝色引用' ),
		isDefault: true,
		attributes: {
			color: 'blue',
			className: 'is-style-blue-quote'
		},
		icon: 'format-quote',
		isActive: ( blockAttributes, variationAttributes ) =>
			blockAttributes.color === variationAttributes.color
	},
],

使用isDefault标志

默认情况下，所有变体都会在插入器中与原始区块类型项共同显示。但为列出的任何变体设置isDefault标志将覆盖插入器中的常规区块类型。这是根据特定需求定制编辑器体验的强大工具。

例如，若希望媒体与文本区块默认在右侧显示图像，可创建如下变体：

wp.blocks.registerBlockVariation( 'core/media-text', {
	name: 'media-text-media-right',
	title: __( '媒体与文本' ),
	isDefault: true,
	attributes: {
		mediaPosition: 'right',
	},
} );

使用 isDefault 的注意事项

虽然 isDefault 在覆盖没有现有变体的区块时效果很好，但当存在其他变体时，您可能会遇到问题。

如果同一区块的另一个变体使用了 isDefault，您的变体不一定会成为默认变体。编辑器会尊重第一个注册的带有 isDefault 的变体，这可能不是您的变体。

解决方案是在注册带有 isDefault 的变体之前，先取消注册其他变体。这一注意事项进一步强调了始终为变体提供唯一 name 的建议。否则，该变体将无法被取消注册。

使用 isActive

虽然 isActive 属性是可选的，但建议使用它。区块编辑器使用此 API 来检查哪个变体处于活动状态，并在编辑器中选择该变体的实例时显示正确的变体标题、图标和描述。

如果未设置 isActive，编辑器将无法区分原始区块的实例和您的变体，因此将显示原始区块的信息。

该属性可以设置为字符串数组（string[]）或函数。建议尽可能使用字符串数组版本。

string[] 版本用于声明应将区块实例的哪些属性与给定变体的属性进行比较。每个属性都将被检查，如果所有属性都匹配，则该变体将处于活动状态。

例如，在核心的 Embed 区块中，providerNameSlug 属性用于确定嵌入提供程序（例如 “youtube” 或 “twitter”）。变体可以这样声明：

const variations = [
	{
		name: 'twitter',
		title: 'Twitter',
		icon: embedTwitterIcon,
		keywords: [ 'tweet', __( 'social' ) ],
		description: __( '嵌入推文。' ),
		patterns: [ /^https?:\/\/(www\.)?twitter\.com\/.+/i ],
		attributes: { providerNameSlug: 'twitter', responsive: true },
	},
	{
		name: 'youtube',
		title: 'YouTube',
		icon: embedYouTubeIcon,
		keywords: [ __( '音乐' ), __( '视频' ) ],
		description: __( '嵌入 YouTube 视频。' ),
		patterns: [
			/^https?:\/\/((m|www)\.)?youtube\.com\/.+/i,
			/^https?:\/\/youtu\.be\/.+/i,
		],
		attributes: { providerNameSlug: 'youtube', responsive: true },
	},
	// ...
];

那么 isActive 属性将如下所示：

isActive: [ 'providerNameSlug' ];

这将导致区块实例的 providerNameSlug 值与变体声明中的值（上述代码片段中的值）进行比较，以确定哪个嵌入变体处于活动状态。

自 WordPress 6.6.0 起，还支持嵌套对象路径。例如，假设一个区块变体具有 query 对象作为属性。可以仅基于该对象的 postType 属性（同时忽略其所有其他属性）来确定变体是否处于活动状态：

isActive: [ 'query.postType' ];

该属性的函数版本接受区块实例的 blockAttributes 作为第一个参数，以及为变体声明的 variationAttributes 作为第二个参数。可以通过比较这些参数来确定变体是否处于活动状态，并返回 true 或 false（表示此变体是否对此区块实例处于活动状态）。

以嵌入区块的相同示例为例，函数版本将如下所示：

isActive: ( blockAttributes, variationAttributes ) =>
	blockAttributes.providerNameSlug === variationAttributes.providerNameSlug,

isActive 匹配的特定性

注意：自 WordPress 6.6.0 起改进了处理方式。

如果有多个变体的 isActive 检查匹配给定的区块实例，并且所有变体都是字符串数组，则将选择特定性最高的变体。考虑以下示例：

wp.blocks.registerBlockVariation( 'core/paragraph', {
	name: 'paragraph-red',
	title: '红色段落',
	attributes: {
		textColor: 'vivid-red',
	},
	isActive: [ 'textColor' ],
} );

wp.blocks.registerBlockVariation( 'core/paragraph', {
	name: 'paragraph-red-grey',
	title: '红/灰段落',
	attributes: {
		textColor: 'vivid-red',
		backgroundColor: 'cyan-bluish-gray',
	},
	isActive: [ 'textColor', 'backgroundColor' ],
} );

如果某个区块实例具有属性 textColor: vivid-red 和 backgroundColor: cyan-bluish-gray，则两个变体的 isActive 条件都将匹配该区块实例。在这种情况下，将确定特定性更高的匹配为活动变体，其中特定性计算为每个 isActive 数组的长度。这意味着 红/灰段落 将显示为活动变体。

请注意，如果匹配变体的 isActive 属性是函数而不是 string[]，则无法确定其特定性。在这种情况下，第一个匹配的变体将被确定为活动变体。因此，通常建议为 isActive 属性使用 string[] 而不是 function。