@wordpress/style-engine

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

Style Engine 旨在提供一个一致的 API，用于在客户端和服务器端应用中渲染区块样式。

最初，它将提供一个单一的集中式代理，负责生成区块样式；在后续阶段，它还将承担处理和渲染优化的前端 CSS 的责任。

请注意

该包自 WordPress 6.1 起新引入，因此仍处于起步阶段。

路线图上即将开展的任务包括但不限于以下内容：

整合全局样式和区块样式的渲染与入队（进行中）
探索预渲染 CSS 规则处理，以期去除其他常见和/或重复区块样式中的重复项。（进行中）
扩展语义类名和/或设计令牌表达的范围，并将规则封装为稳定的工具类。
探索预渲染 CSS 规则处理，以期去除其他常见和/或重复区块样式中的重复项。
提出一种控制层级和优先级的方法，使样式层级级联变得可访问且可预测。这可能包括在 CSS 级联层获得更广泛支持之前为其做准备，并允许通过 theme.json 在 Gutenberg 中可选择启用支持。
重构所有区块，使其一致地使用 “style” 属性进行所有自定义，即弃用特定于预设的属性，例如 attributes.fontSize。

有关路线图的更多信息，请参阅区块编辑器样式：计划与目标和 GitHub 项目看板。

如果您正在对 Style Engine 进行修改或补充，请花一点时间阅读贡献说明。

后端 API

wp_style_engine_get_styles()

全局公共函数，用于从单个样式对象生成样式，例如区块的 attributes.style 对象的值或 theme.json 中的顶层样式。

另请参阅使用 Style Engine 生成 block supports 样式。

参数

$block_styles array 区块的 attributes.style 对象或 theme.json 中的顶层样式
$options array<string|boolean> 用于决定输出的选项数组。
- context string 描述样式对象来源的标识符，例如 ‘block-supports’ 或 ‘global-styles’。默认值为 ‘block-supports’。当同时设置了 context 和 selector 时，Style Engine 会使用 context 作为键存储 CSS 规则。
- convert_vars_to_classnames boolean 是否跳过将 CSS var:? 值转换为 var( –wp–preset–* ) 值。默认值为 false。
- selector string 当传入选择器时，generate() 将返回完整的 CSS 规则 $selector { ...rules }，否则返回属性和值的连接字符串。

返回值
array<string|array>|null

array(
    'css'           => (string) A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
    'declarations'  => (array) An array of property/value pairs representing parsed CSS declarations.
    'classnames'    => (string) Classnames separated by a space.
);

它将返回用于内联样式的已编译 CSS 声明，或者在提供选择器时返回完整的 CSS 规则。

要为站点前端渲染而入队样式，$options 数组需要满足以下条件：

selector (string) – 这是区块样式 CSS 声明的 CSS 选择器。
context (string) – 这告诉 Style Engine 存储样式的位置。相同 context 中的样式会存储在一起。

wp_style_engine_get_styles 将返回已编译的 CSS 和 CSS 声明数组。

用法

如前所述，当您希望从区块的样式对象生成 CSS 和/或类名时，wp_style_engine_get_styles() 非常有用。一个很好的示例是使用 Style Engine 生成 block supports 样式。

在下面的代码片段中，我们从区块的 attributes 中获取样式对象，并将其传递给 Style Engine 以获取样式。通过在选项中传递 context，Style Engine 将存储这些样式以便以后检索，例如，当您希望批量入队一组 CSS 规则时。

$block_attributes =  array(
     'style' => array(
        'spacing' => array( 'padding' => '100px' ),
     ),
);

$styles = wp_style_engine_get_styles(
    $block_attributes['style'],
    array(
        'selector' => '.a-selector',
        'context'  => 'block-supports',
    )
);
print_r( $styles );

/*
array(
    'css'          => '.a-selector{padding:100px}'
    'declarations' => array( 'padding' => '100px' )
)
*/

wp_style_engine_get_stylesheet_from_css_rules()

使用此函数可以编译并返回任何 CSS 规则的样式表。Style Engine 会自动合并声明并组合选择器。

该函数充当 CSS 编译器，但也会在选项中传递 context 字符串时将样式注册到存储中。

参数

$css_rules array<array>
$options array<string|bool> 用于决定输出的选项数组。
- context string 描述样式对象来源的标识符，例如 ‘block-supports’ 或 ‘global-styles’。默认值为 ‘block-supports’。设置后，Style Engine 将尝试存储 CSS 规则。
- prettify bool 是否在输出中添加换行和缩进。如果定义了全局常量 SCRIPT_DEBUG，默认继承其值。
- optimize bool 是否优化 CSS 输出，例如合并规则。默认值为 false。

返回值
string 基于 $css_rules 的已编译 CSS 字符串。

用法

当您希望从一系列选择器 + 声明项编译一组自定义 CSS 规则时非常有用。

Style Engine 将返回经过清理的样式表。通过在选项中传递 context 标识符，Style Engine 将存储这些样式以便以后检索，例如，当您希望批量入队一组 CSS 规则时。

您可以多次调用 wp_style_engine_get_stylesheet_from_css_rules()，只要您的样式使用相同的 context 标识符，它们就会存储在一起。

$styles = array(
    array(
        'selector'     => '.wp-pumpkin',
        'declarations' => array( 'color' => 'orange' )
    ),
    array(
        'selector'     => '.wp-tomato',
        'declarations' => array( 'color' => 'red' )
    ),
    array(
        'selector'     => '.wp-tomato',
        'declarations' => array( 'padding' => '100px' )
    ),
);

$stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
    $styles,
    array(
        'context' => 'block-supports', // 指示这些样式应与 block supports CSS 一起存储。
    )
);
print_r( $stylesheet ); // .wp-pumpkin{color:orange}.wp-tomato{color:red;padding:100px}

也可以使用 rules_group 键构建简单的嵌套 CSS 规则。

$styles = array(
    array(
        'rules_group'  => '@media (min-width: 80rem)',
        'selector'     => '.wp-carrot',
        'declarations' => array( 'color' => 'orange' )
    ),
    array(
        'rules_group'  => '@media (min-width: 80rem)',
        'selector'     => '.wp-tomato',
        'declarations' => array( 'color' => 'red' )
    ),
);

$stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
    $styles,
    array(
        'context' => 'block-supports', // 指示这些样式应与 block supports CSS 一起存储。
    )
);
print_r( $stylesheet ); // @media (min-width: 80rem){.wp-carrot{color:orange}}@media (min-width: 80rem){.wp-tomato{color:red;}}

wp_style_engine_get_stylesheet_from_context()

如果找到，将从存储的 context 返回已编译的 CSS。

参数

$store_name string 描述样式对象来源的标识符，例如 ‘block-supports’ 或 ‘ global-styles’。默认值为 ‘block-supports’。
$options array<bool> 用于决定输出的选项数组。
- prettify bool 是否在输出中添加换行和缩进。如果定义了全局常量 SCRIPT_DEBUG，默认继承其值。
- optimize bool 是否优化 CSS 输出，例如合并规则。默认值为 false。

返回值
string 从已存储的 CSS 规则编译得到的 CSS 字符串。

用法

使用该函数，基于存储在特定上下文标识符下的所有样式生成样式表。

一个使用场景是当你希望将所有已存储样式入队以渲染到前端时。Style Engine 会在获取时合并并去重样式。

// 首先，收集并注册我们的样式。
$styles = array(
    array(
        'selector'     => '.wp-apple',
        'declarations' => array( 'color' => 'green' )
    ),
);

wp_style_engine_get_stylesheet_from_css_rules(
    $styles,
    array(
        'context' => 'fruit-styles',
    )
);

// 之后，我们从上下文存储中获取编译后的规则。
$stylesheet = wp_style_engine_get_stylesheet_from_context( 'fruit-styles' );

print_r( $stylesheet ); // .wp-apple{color:green;}

if ( ! empty( $stylesheet ) ) {
    wp_register_style( 'my-stylesheet', false, array(), true, true );
    wp_add_inline_style( 'my-stylesheet', $stylesheet );
    wp_enqueue_style( 'my-stylesheet' );
}

安装（仅限 JS）

安装模块

npm install @wordpress/style-engine --save

此包假定你的代码将在 ES2015+ 环境中运行。如果你使用的环境对此类语言特性和 API 的支持有限或完全不支持，应在代码中引入 @wordpress/babel-preset-default 中附带的 polyfill。

用法

compileCSS

为给定的样式对象和选择器生成样式表。

用法

import { compileCSS } from '@wordpress/style-engine';

// 如果提供选择器，将返回完整的样式表字符串。
compileCSS(
    { spacing: { padding: '10px', margin: '12px' } },
    { selector: '.my-block' }
);
// '.my-block { margin: 12px; padding: 10px; }'

// 如果未提供选择器，将返回内联声明。
compileCSS( { spacing: { padding: '10px', margin: '12px' } } );
// 'margin: 12px; padding: 10px;'

参数

style Style：样式对象，例如区块的 attributes.style 对象的值，或 theme.json 中的顶层样式。
options StyleOptions：选项对象，用于调整样式生成方式。

返回值

string：生成的样式表或内联样式声明。

更新日志

6.1.0 引入 WordPress 核心。

GeneratedCSSRule

由 getCSSRules 生成的单个 CSS 规则。

getCSSRules

返回所生成 CSS 规则的 JSON 表示。

用法

import { getCSSRules } from '@wordpress/style-engine';

getCSSRules(
    { spacing: { padding: '10px', margin: '12px' } },
    { selector: '.my-block' }
);
// [
//   { selector: '.my-block', key: 'margin', value: '12px' },
//   { selector: '.my-block', key: 'padding', value: '10px' },
// ]

参数

style Style：样式对象，例如区块的 attributes.style 对象的值，或 theme.json 中的顶层样式。
options StyleOptions：选项对象，用于调整样式生成方式。

返回值

GeneratedCSSRule[]：一组对象，包含选择器（如果有）、CSS 属性键（驼峰式）和解析后的 CSS 值。

更新日志

6.1.0 引入 WordPress 核心。

getCSSValueFromRawStyle

如果检测到传入样式预设值，则返回对应的 WordPress CSS 自定义变量值。

预设值是字符串，并遵循 var:description|context|slug 模式。

示例：

getCSSValueFromRawStyle( 'var:preset|color|heavenlyBlue' ) // 返回 ‘var(–wp–preset–color–heavenly-blue)’

参数

styleValue StyleValue：表示原始 CSS 值的字符串。非字符串不会被处理。

返回值

StyleValue：如果传入样式值是预设值，则返回 CSS 自定义变量值。

Style

compileCSS 和 getCSSRules 接受的区块或主题样式对象。

StyleOptions

compileCSS 和 getCSSRules 的选项。

术语表

Style Engine 包所引用术语和变量名指南。

区块样式（Gutenberg 内部）：由区块的样式属性组成并包含区块样式值的对象。例如：{ spacing: { margin: '10px' }, color: { ... }, ... }上下文：用于标识一组具有共同来源或用途的样式的标识符，例如 'block-supports' 或 'global-styles'。上下文也用作从存储中获取 CSS 规则的键。CSS 声明（或 CSS 属性声明）：与 CSS 值配对的 CSS 属性。例如：color: pink CSS 声明块：一组 CSS 声明，通常与 CSS 选择器配对以创建 CSS 规则。CSS 属性：描述 HTML 元素可修改样式特性的标识符。例如：border、font-size、width…CSS 规则：由 CSS 选择器后跟一对花括号内的 CSS 声明块组成。通常出现在 CSS 样式表中。CSS 选择器（或 CSS 类选择器）：CSS 规则的第一个组成部分。CSS 选择器是由元素、类名或其他词条组成的模式，用于定义规则中的 CSS 定义所应用的元素。例如：p.my-cool-classname > span。CSS 选择器根据 “class” 属性的内容匹配 HTML 元素。参见 MDN CSS 选择器文章。CSS 样式表：包含在文件或 HTML style 标签中的一组 CSS 规则。CSS 值：CSS 属性的值。该值决定如何修改属性。例如：height: 10vw 中的 10vw。CSS 变量（vars）或 CSS 自定义属性：其值可在其他 CSS 声明中重用的属性。使用自定义属性表示法设置（例如：--wp--preset--olive: #808000;），并通过 var() 函数访问（例如：color: var( --wp--preset--olive );）。参见 MDN 关于 CSS 自定义属性的文章。全局样式（Gutenberg 内部）：合并后的区块样式对象，包含主题的 theme.json 和用户样式设置中的值。内联样式：影响单个 HTML 元素并包含在 style 属性中的 CSS 声明。处理器：对已存储的 CSS 规则执行编译和优化。参见类 `WP_Style_Engine_Processor`。存储：包含相关样式的数据对象。参见类 `WP_Style_Engine_CSS_Rules_Store。