样式

最后更新：2026-10-17 10:55:29

块样式允许对现有块应用替代样式。它们通过向块的包装器添加一个 className 来实现。如果选择了该块样式，可以使用这个 className 为块提供替代样式。有关如何将样式应用于块的完整示例，请参阅使用样式和样式表。

示例：

wp.blocks.registerBlockStyle( 'core/quote', {
    name: 'fancy-quote',
    label: 'Fancy Quote',
} );

上面的示例注册了一个名为 fancy-quote 的块样式到 core/quote 块。当用户从样式选择器中选择此块样式时，is-style-fancy-quote className 将添加到块的包装器中。

通过添加 isDefault: true，您可以将注册的块样式标记为在没有提供自定义类名时被视为激活的样式。这也意味着对于被标记为默认的样式，不会在 HTML 输出中添加自定义类名。

要移除块样式，请使用 wp.blocks.unregisterBlockStyle()。

示例：

wp.blocks.unregisterBlockStyle( 'core/quote', 'large' );

上面的代码从 core/quote 块中移除了名为 large 的块样式。

重要：在注销块样式时，可能会存在一个竞态条件，即代码运行的顺序：注册样式还是注销样式。您希望您的注销代码最后运行。要做到这一点，请将注册样式的组件指定为依赖项，在本例中为 wp-edit-post。此外，使用 wp.domReady() 可确保注销代码在 DOM 加载后运行。

使用以下 PHP 代码挂接您的 JavaScript：

function myguten_enqueue() {
    wp_enqueue_script(
        'myguten-script',
        plugins_url( 'myguten.js', __FILE__ ),
        array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
        filemtime( plugin_dir_path( __FILE__ ) . '/myguten.js' )
    );
}
add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );

myguten.js 中的 JavaScript 代码：

wp.domReady( function () {
    wp.blocks.unregisterBlockStyle( 'core/quote', 'large' );
} );

服务器端注册辅助函数

虽然提供的示例允许完全控制块样式，但它们需要大量的代码。

为了简化注册和注销块样式的过程，还提供了两个服务器端函数：register_block_style 和 unregister_block_style。

register_block_style

register_block_style 函数接收块的名称作为第一个参数，并接收一个描述样式属性的数组作为第二个参数。

样式数组的属性必须包括 name 和 label：

name：用于计算 CSS 类名的样式标识符。
label：样式的可读标签。

除了两个必需属性外，样式属性数组还应包括一个 inline_style 或 style_handle 或 style_data 属性：

inline_style：包含注册样式所需 CSS 类名的内联 CSS 代码。
style_handle：包含已注册样式的句柄，该样式应在需要块样式的位置挂接。
style_data：包含一个类似 theme.json 的表示法，由样式属性数组组成。

还可以将 is_default 属性设置为 true，以在缺少默认样式时标记其中一个块样式为默认样式。

以下代码示例注册了一个名为“Blue Quote”的样式到引用块，并提供内联样式，使具有“Blue Quote”样式的引用块呈现蓝色：

register_block_style(
    'core/quote',
    array(
        'name'         => 'blue-quote',
        'label'        => __( 'Blue Quote', 'textdomain' ),
        'inline_style' => '.wp-block-quote.is-style-blue-quote { color: blue; }',
    )
);

或者，如果已注册包含块样式 CSS 的样式表，则可以仅传递样式表的句柄，以便 register_block_style 函数确保其被挂接。

以下代码示例提供了此用例的示例：

wp_register_style( 'myguten-style', get_template_directory_uri() . '/custom-style.css' );

// ...

register_block_style(
    'core/quote',
    array(
        'name'         => 'fancy-quote',
        'label'        => __( 'Fancy Quote', 'textdomain' ),
        'style_handle' => 'myguten-style',
    )
);

另一种方法是使用 style_data 属性，如下面的代码示例所示。它向图像块添加了一个具有橙色边框和略微圆角的块样式。

register_block_style(
       array( 'core/image' ),
       array(
           'name'         => 'orange-border',
           'label'        => __( 'Orange Border', 'pauli' ),
           'style_data'=> array(
                           'border' => array(
                           'color' => '#f5bc42',
                           'style' => 'solid',
                           'width' => '4px',
                           'radius' => '15px'
            )
        )
    )
);

使用 style_data 属性使用户可以通过 编辑器 > 样式 中的全局样式 UI 对其进行更改。style_data 属性是在 WordPress 6.6 中添加的。

有关更多信息，请参阅 WordPress 6.6 开发说明：区域样式。
也在 WordPress 开发者博客上：在 WordPress 6.6 中使用块样式变体对区域、嵌套元素等进行样式设置

unregister_block_style

unregister_block_style 允许注销先前使用 register_block_style 在服务器上注册的块样式。

函数的第一个参数是已注册的块名称，第二个参数是样式的名称。

以下代码示例从引用块中注销名为‘fancy-quote’的样式：

unregister_block_style( 'core/quote', 'fancy-quote' );

重要：函数 unregister_block_style 仅注销使用 register_block_style 在服务器上注册的样式。该函数不会注销使用客户端代码注册的样式。