WordPress 区块样式变体完全指南
WordPress 区块编辑器（也就是古腾堡）提供了一套灵活的样式系统，让主题开发者能够为每个区块创建多种视觉变体。这篇文章会带你彻底搞懂“区块样式变体”这个概念——它不是全局样式变体，也不是区块变体，三者虽然名字相近，但用途完全不同。
你将学会两种注册方式：PHP 方式和 JavaScript 方式。还会了解到如何通过 theme.json 定制核心区块的预设样式，以及何时该用哪种方法。文章会解释每个术语，并提供可直接运行的代码示例，适合初学者跟着操作。
一、区块样式变体是什么？
“区块样式变体”的官方简称是“区块样式”，它本质上就是一个 CSS 类名，格式为 .is-style-{名称}。当你给一个区块应用某种样式时，这个类就会被添加到区块的外层容器上。
举个例子：你给「图片」区块选了一个“圆角”样式，实际上就是在该区块的包裹元素上加了一个 .is-style-rounded 类。剩下的工作交给 CSS——主题或插件提前写好的样式规则会生效。
关键限制：用户每次只能给一个区块选择一种样式，不能组合多个样式。如果你需要让用户能自由组合多种视觉效果，就得考虑开发自定义设计工具，而不是用区块样式。
注意：区块样式≠区块样式表（样式表是 CSS 文件本身）。两者常配合使用，但概念不同。
二、PHP 方式注册与移除
大多数主题开发者会用 PHP 来注册区块样式，因为直接在 functions.php 里写代码更直观。
register_block_style() 函数
这个函数接受两个参数：
php
register_block_style(
string $block_name, // 区块名称，如 'core/image'
array $style_properties // 样式配置数组
): bool
配置数组里必须包含 name 和 label，还可以选择是否提供 inline_style（内联 CSS）或 style_handle（外部样式表句柄）。
php
add_action( 'init', 'mytheme_register_block_styles' );
function mytheme_register_block_styles() {
register_block_style( 'core/image', array(
'name' => 'hand-drawn',
'label' => __( '手绘风格', 'mytheme' ),
'inline_style' => '.wp-block-image.is-style-hand-drawn img {
border: 3px solid currentColor;
border-radius: 255px 15px 225px 15px/15px 225px 15px 255px;
box-shadow: 0 6px 16px rgba(0,0,0,0.25);
}'
) );
}
如果 CSS 代码量较大，建议放到独立的样式表文件中，然后用 style_handle 参数引入。
注意：
style_handle参数目前存在一个已知问题——它只会在编辑器里加载样式，前台页面不会生效。在官方修复之前，建议暂时用inline_style或手动在wp_enqueue_scripts里加载样式表。
unregister_block_style() 函数
移除已注册的区块样式：
php
add_action( 'init', 'mytheme_unregister_block_styles', 99 );
function mytheme_unregister_block_styles() {
unregister_block_style( 'core/image', 'hand-drawn' );
}
注意优先级设为 99，确保在注册函数（默认优先级 10）之后执行。PHP 方式注册的样式只能用 PHP 方式移除，不能用 JavaScript 移除。
三、JavaScript 方式注册与移除
如果你的主题需要在前端动态处理区块样式，或者你想用更现代的 JS 方式，可以使用 registerBlockStyle() 和 unregisterBlockStyle()。
加载 JavaScript 文件
先在主题目录下创建 assets/js/block-editor.js 文件，然后在 functions.php 中引入：
php
add_action( 'enqueue_block_editor_assets', 'mytheme_block_editor_assets' );
function mytheme_block_editor_assets() {
wp_enqueue_script(
'mytheme-block-editor',
get_theme_file_uri( 'assets/js/block-editor.js' ),
array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' )
);
}
registerBlockStyle() 用法
js
wp.blocks.registerBlockStyle( 'core/image', {
name: 'hand-drawn',
label: '手绘风格'
} );
和 PHP 版本一样，也支持 isDefault 参数，设为 true 时该样式会成为区块的默认样式。
CSS 样式需要通过其他方式引入，比如在 functions.php 中用 wp_add_inline_style()，或者单独加载一个 CSS 文件。
unregisterBlockStyle() 用法
为了保证移除操作在样式注册完成之后执行，建议放在 wp.domReady 回调里：
js
wp.domReady( function () {
wp.blocks.unregisterBlockStyle( 'core/image', 'hand-drawn' );
} );
JavaScript 方式注册的样式只能用 JavaScript 方式移除。
四、通过 theme.json 定制核心区块样式
WordPress 允许你在 theme.json 里直接修改核心区块的预设样式，而不需要写任何 CSS。这种方式的优势在于：用户可以在“外观 > 编辑器 > 样式”界面中看到并调整这些样式。
实际案例：修改按钮的“轮廓”样式
假设你想让「按钮」区块的“轮廓”样式带上一个双层边框效果（用阴影模拟），可以这样配置 theme.json：
json
{
"version": 2,
"styles": {
"blocks": {
"core/button": {
"variations": {
"outline": {
"border": {
"color": "var:preset|color|black",
"radius": "4px",
"style": "solid",
"width": "3px"
},
"shadow": "var:preset|shadow|outlined",
"spacing": {
"padding": {
"top": "0.5rem",
"bottom": "0.5rem",
"left": "1.5rem",
"right": "1.5rem"
}
}
}
}
}
}
}
}
可定制的核心区块样式列表
目前 WordPress 支持在 theme.json 中定制以下区块的预设样式：
core/button：outline、fillcore/image：roundedcore/quote：plaincore/site-logo：roundedcore/separator：wide、dotscore/social-links：logos-only、pill-shapecore/table：stripescore/tag-cloud：outline
注意：通过
register_block_style()自定义注册的区块样式，目前还不能在theme.json中定制。只能定制 WordPress 核心自带的那些样式。
总结
| 方法 | 适用场景 | 移除方式 |
|---|---|---|
PHP（register_block_style） | 主题开发的主流选择，直接写在 functions.php | 必须用 PHP |
JavaScript（registerBlockStyle） | 需要动态处理或偏好前端开发方式 | 必须用 JS |
theme.json 定制 | 仅限核心预设样式，无需写 CSS，用户可调节 | 直接修改配置 |
建议优先考虑用 theme.json 定制核心样式——这是干净的方式。如果核心预设样式不满足需求，再用 PHP 或 JS 注册自定义样式。选择哪种注册方式，主要看你的开发习惯和主题架构，功能上没有本质区别。