区块样式变体（简称“区块样式”）允许您为单个区块创建替代样式。已注册的样式会显示在用户界面中，使用户能够快速在默认样式和任何替代样式之间切换。

不幸的是，许多功能在其名称中都使用了术语“变体”。这有时会造成混淆。需要注意的是，区块样式变体与 全局样式变体 和 区块变体 是完全不同的东西。

通常，您会看到区块样式变体被称为“区块样式”，正如本文所示，但这也不应与 区块样式表 混淆。这两种功能可以一起使用，但它们不是同一回事。

什么是区块样式？

在底层，区块样式无非是添加到区块包装元素上的 CSS 类，名称为 .is-style-{name}。这允许您添加自定义 CSS 以某种方式更改区块的设计。

在此截图中，您可以在样式面板下看到为图像块注册了多个区块样式，并且选择了核心圆角选项：

WordPress 帖子编辑器显示内容画布中具有圆角样式的图像块。

这里发生的一切是，核心 WordPress 和主题都为图像块注册了区块样式，并且用户选择了这些样式之一。然后，该已注册样式的 CSS 被应用于一个区块。

归根结底，区块样式只是通过添加类到区块并使用 CSS 对其进行自定义的标准方法。

用户一次只能将一个样式应用于一个区块。他们无法使用标准设计工具将它们组合在一起。如果您需要提供更多选项，请考虑构建自定义设计工具。阅读 WordPress 开发者博客上的 超越区块样式 教程系列以了解如何操作。

基于 PHP 的区块样式

大多数主题作者希望使用 PHP 注册区块样式。如果您需要通过 JavaScript 处理它们，请跳到“基于 JavaScript 的区块样式”部分。

使用 PHP 注册区块样式

要注册一个区块样式，请使用 register_block_style() PHP 函数。该函数的签名如下：

register_block_style( 
	string $block_name, 
	array $style_properties
): bool

该函数接受两个参数，并根据注册是否成功返回 true 或 false：

  • $block_name: 区块的名称，包括命名空间和标识符（例如，core/image）。
  • $style_properties: 可用于配置样式的参数数组：
    • name: (必需) 唯一的标识符/标识符，用于生成类（例如，.is-style-{name}）。
    • label: (必需) 人类可读的标签，可以翻译。
    • inline_style: 当样式在使用时打印的内联 CSS。
    • style_handle: 用于加载样式的已注册样式表的句柄。
    • is_default: 是否应将此样式选为区块的默认样式（默认为 false）。

style_handle 目前存在一个 bug，它仅在编辑器中加载样式表，而不在前端加载。在解决此链接的工单之前，不建议使用它。

让我们尝试创建一个给图像块“手绘”外观的区块样式，以便在编辑器中选择时看起来像这样：

WordPress 帖子编辑器显示内容画布中具有手绘样式的图像块。

要注册此区块样式，您需要通过 register_block_style() 函数对其进行配置，并将其作为 init 钩子的回调添加。

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

add_action( 'init', 'themeslug_register_block_styles' );

function themeslug_register_block_styles() {
	register_block_style( 'core/image', array(
		'name'         => 'hand-drawn',
		'label'        => __( 'Hand Drawn', 'themeslug' ),
		'inline_style' => '.wp-block-image.is-style-hand-drawn img {
			border: 2px solid currentColor;
			overflow: hidden;
			box-shadow: 0 4px  10px 0 rgba( 0, 0, 0, 0.3 );
			border-radius: 255px 15px 225px 15px/15px 225px 15px 255px !important;
		}'
    ) );
}

如果您的 inline_style 参数包含几行 CSS 代码，您可能希望将 CSS 添加到自定义 区块样式表 中。

使用 PHP 取消注册区块样式

要取消注册通过 PHP 注册的区块样式，请使用 unregister_block_style() 函数。以下是其签名的概览：

unregister_block_style(
	string $block_name, 
	string $block_style_name 
): bool

该函数接受两个参数，并根据注册是否成功返回 true 或 false：

  • $block_name: 区块的名称，包括其命名空间和标识符（例如，core/image）。
  • $block_style_name: 通过 PHP 注册的区块样式的名称/标识符。

要取消注册您之前注册的 hand-drawn 区块样式，您需要向 init 钩子添加一个操作函数（注意：操作调用具有较晚的优先级 99，以便它在先前的注册函数之后运行，该函数默认为 10）：

add_action( 'init', 'themeslug_register_block_styles', 999 );

function themeslug_register_block_styles() {
	unregister_block_style( 'core/image', 'hand-drawn' );
}

您只能取消注册通过 PHP 注册的区块样式。如果区块样式是通过 JavaScript 注册的，则必须也使用 JavaScript 来取消注册它。有关更多信息，请参见下面的“使用 JavaScript 取消注册区块样式”部分。

基于 JavaScript 的区块样式

要通过 JavaScript 注册或取消注册区块样式，您需要在 enqueue_block_editor_assets 钩子上加载一个 JavaScript 文件。

首先，在主题中创建一个 /assets/js/block-editor.js 文件（您可以更改此名称或将其添加到任何位置，但下面的示例假设此名称和位置）。

然后将此代码添加到主题的 functions.php 文件中以加载您的脚本：

add_action( 'enqueue_block_editor_assets', 'themeslug_block_editor_assets' );

function themeslug_block_editor_assets() {
	wp_enqueue_script(
		'themeslug-block-editor',
		get_theme_file_uri( 'assets/js/block-editor.js' ),
		array( 
			'wp-blocks', 
			'wp-dom-ready', 
			'wp-edit-post' 
		)
	);
}

使用 JavaScript 注册区块样式

要通过 JavaScript 注册一个区块样式，您将使用 registerBlockStyle() 函数，它类似于 register_block_style() PHP 函数。它只是使用 JavaScript 语法。

让我们使用之前的相同示例并注册一个“手绘”图像块样式。将此代码添加到您的 /assets/js/block-editor.js 文件：

wp.blocks.registerBlockStyle( 'core/image', {
	name: 'hand-drawn',
	label: 'Hand Drawn'
} );

您还可以将 isDefault 参数设置为 true，如果这应该是默认区块样式（默认为 false）。

对于添加自定义 CSS，您需要加载自定义 区块样式表 或通过其他方式添加您的 CSS。

使用 JavaScript 取消注册区块样式

还有一个 unregisterBlockStyle() JavaScript 函数，它与 unregister_block_style() PHP 函数等效。您可以使用它来取消注册任何通过 JavaScript 注册的区块样式。

为了避免块样式注册与取消注册之间的冲突（即竞态条件），您需要确保在已注册区块样式之后取消注册它。执行此操作的最佳方法是在 wp.domReady 上的函数回调中添加它，这确保了您在 DOM 加载后取消注册。

要取消注册您通过 JavaScript 注册的 hand-drawn 区块样式，将此内容添加到您的 /assets/js/block-editor.js 文件：

wp.domReady( function () {
	wp.blocks.unregisterBlockStyle( 'core/image', 'hand-drawn' );
} );

您只能取消注册通过 JavaScript 注册的区块样式。如果区块样式是通过 PHP 注册的，则必须也使用 PHP 来取消注册它。有关更多信息，请参见上面的“使用 PHP 取消注册区块样式”部分。

通过 theme.json 自定义区块样式

可以自定义核心 WordPress 区块样式的设计。这意味着您可能根本不需要添加自定义 CSS 即可获得所需的外观。

如果可能，也建议使用此方法进行自定义，因为它们会出现在 外观 > 编辑器 > 样式 界面中。此外，您的主题用户可以根据需要对其进行自己的更改。

让我们尝试修改核心按钮块的轮廓样式，使其具有创建双重边框效果的投影：

WordPress 帖子编辑器显示内容画布中具有实线边框投影的三个轮廓按钮。

为此，打开您的 theme.json 文件。您需要针对 styles.blocks.core/button.variations.outline 属性。它就像任何其他可以通过 theme.json 添加的 样式。

尝试在您的 theme.json 文件中使用此代码片段：

{
	"version": 2,
	"styles": {
		"blocks": {
			"core/button": {
				"variations": {
					"outline": {
						"border": {
							"color": "var:preset|color|black",
							"radius": "0",
							"style": "solid",
							"width": "3px"
						},
						"shadow": "var:preset|shadow|outlined",
						"spacing": {
							"padding": {
								"top": "0.5rem",
								"bottom": "0.5rem",
								"left": "1.5rem",
								"right": "1.5rem"
							}
						}
					}
				}
			}
		}
	}
}

请随意调整它以符合您的喜好，然后享受修改其他区块样式的乐趣。

目前无法通过 theme.json 自定义您自定义注册的区块样式。您只能对核心 WordPress 当前注册的样式进行样式设置。有关更多信息，请查看 GitHub 上的相关 功能请求。

以下是您可以通过 theme.json 自定义的核心 WordPress 区块及其样式：

  • core/button: outline, fill
  • core/image: rounded
  • core/quote: plain
  • core/site-logo: rounded
  • core/separator: wide, dots
  • core/social-links: logos-only, pill-shape
  • core/table: stripes
  • core/tag-cloud: outline

若要深入了解核心区块的样式设置，请阅读 WordPress 开发者博客上的 通过 theme.json 自定义核心区块样式变体。