@wordpress/样式引擎

样式引擎旨在为跨客户端和服务器端应用程序的块渲染样式提供一致的API。

最初,它将提供一个单一的集中式代理,负责生成块样式,在稍后的阶段,它还将负责处理和呈现优化的前端CSS。

请注意

此软件包是WordPress 6.1的新版本,因此尚处于起步阶段。

路线图上即将完成的任务包括但不限于以下内容:

  • 整合全局和块样式渲染和排队(正在进行)
  • 探索渲染前CSS规则处理,以消除其他常见和/或重复块样式的重复数据。(正在进行)
  • 扩展语义类名和/或设计标记表达式的范围,并将规则封装到稳定的实用程序类中。
  • 探索渲染前CSS规则处理,以消除其他常见和/或重复块样式的重复数据。
  • 提出一种控制层次结构和特定性的方法,并使样式层次结构级联可访问和可预测。这可能包括准备CSS级联层,直到它们得到更广泛的支持,并允许通过theme.json在Gutenberg中提供opt-in支持。
  • 重构所有块以一致地对所有自定义使用“样式”属性,即不推荐使用预设特定属性,例如属性.fontSize.

有关路线图的更多信息,请参阅块编辑器样式:倡议和目标GitHub项目委员会.

如果您正在对样式引擎进行更改或添加,请花点时间阅读关于贡献的注释.

后端API

wp_style_engine_get_styles()

全局公共函数,用于从单个样式对象生成样式,例如块的属性.style对象theme.json中的顶级样式.

另请参见使用样式引擎生成块支撑样式.

参数

  • $块样式 阵列一个街区的属性.样式对象或theme.json中的顶级样式
  • $个选项 数组<string|boolean>用于确定输出的选项数组。
    • 上下文 一串描述样式对象来源的标识符,例如“块支持”或“全局样式”。默认值为“块支持”。当两者上下文选择器则样式引擎将使用上下文作为一把钥匙。
    • 将变量转换为类名 布尔值是否跳过转换CSS变量:?值转换为var(-wp–preset–*)值。默认值为.
    • 选择器 一串传递选择器时,生成()将返回完整的CSS规则$选择器{…规则},否则为属性和值的串联字符串。

退换商品
数组<string|array>|null

阵列(“css”=>(string)css规则集或声明块,格式化后放置在HTML`style`属性或标记中。“declarations”=>(array)表示已解析CSS声明的属性/值对的数组。“classnames”=>(string)由空格分隔的类名。);

它将返回内联样式的已编译CSS声明,或者,如果提供了选择器,则返回完整的CSS规则。

要在站点前端排队渲染样式$个选项数组需要以下内容:

  1. 选择器(字符串)–这是块样式CSS声明的CSS选择器。
  2. 上下文(字符串)–这告诉样式引擎存储样式的位置。同一上下文中的样式将存储在一起。

wp样式引擎获取样式将返回已编译的CSS和CSS声明数组。

用法

如前所述,wp_style_engine_get_styles()当您希望从块的样式对象一个很好的例子是使用样式引擎生成块支撑样式.

在下面的代码片段中,我们从块的属性中获取样式对象,并将其传递给样式引擎以获取样式。通过传递上下文在选项中,样式引擎将存储样式以供以后检索,例如,如果您希望批量排队一组CSS规则。

$block_attributes=数组(“style”=>数组(“间距”=>数组(“填充”=>“100px”),),);$样式=wp_style_engine_get_styles($block_attributes['style'],阵列('选择器'=>'.a-selector',“context”=>“block-supports”,));print_r($样式);/*阵列(“css”=>“.a-selector{padding:100px}”“声明”=>数组(“padding”=>“100px”))*/

wp_style_engine_get_stylesheet_from_css_rules()

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

此函数用作CSS编译器,但也将在存储中注册样式,其中上下文字符串在选项中传递。

参数

  • $css_rules 数组<数组>
  • $个选项 数组<string|bool>用于确定输出的选项数组。
    • 上下文 一串描述样式对象来源的标识符,例如“块支持”或“全局样式”。默认值为“块支持”。设置后,样式引擎将尝试存储CSS规则。
    • 美化 布尔是否向输出添加新行和缩进。默认值是继承全局常量的值脚本_取消,如果已定义。
    • 优化 布尔是否优化CSS输出,例如合并规则。默认值为.

退换商品
一串编译的CSS字符串基于$css_rules.

用法

当您希望从一系列选择器+声明项编译一组定制的CSS规则时,此功能非常有用。

样式引擎将返回经过清理的样式表。通过传递上下文选项中的标识符,样式引擎将存储样式以供以后检索,例如,如果您希望批量排队一组CSS规则。

你可以打电话wp_style_engine_get_stylesheet_from_css_rules()多次,并且,只要您的样式使用相同的上下文标识符,它们将一起存储。

$styles=数组(阵列(“选择器”=>“.wp-pumpkin”,“声明”=>数组(“颜色”=>“橙色”)),阵列(“选择器”=>“.wp-tomot”,“declarations”=>数组(“color”=>“red”)),阵列(“选择器”=>“.wp-tomot”,“声明”=>数组(“padding”=>“100px”)),);$样式表=wp_style_engine_get_stylesheet_from_css_rules($个样式,阵列(“context”=>“block-supports”,//表示这些样式应与块支持CSS一起存储。));print_r($stylesheet);//。wp-pumpkin{color:orange}.wp-tomota{color:red;padding:100px}

还可以使用规则_group键。

$styles=数组(阵列(“rules_group”=>“@media(min-width:80rem)”,“选择器”=>“.wp-carrot”,“声明”=>数组(“颜色”=>“橙色”)),阵列(“rules_group”=>“@media(min-width:80rem)”,“选择器”=>“.wp-tomot”,“declarations”=>数组(“color”=>“red”)),);$样式表=wp_style_engine_get_stylesheet_from_css_rules($个样式,阵列(“context”=>“block-supports”,//表示这些样式应与块支持CSS一起存储。));print_r($stylesheet);//@媒体(最小宽度:80rem){.wp-carrot{color:orange}@media

wp_style_engine_get_stylesheet_from_context()

如果找到,则从存储的上下文返回已编译的CSS。

参数

  • $商店名称 一串描述样式对象来源的标识符,例如“块支持”或“全局样式”。默认值为“块支持”。
  • $个选项 数组<bool>用于确定输出的选项数组。
    • 美化 布尔是否向输出添加新行和缩进。默认值是继承全局常量的值脚本_取消,如果已定义。
    • 优化 布尔是否优化CSS输出,例如合并规则。默认值为.

退换商品
一串从存储的CSS规则中编译的CSS字符串。

用法

使用此函数可以使用存储在特定上下文标识符下的所有样式生成样式表。

一个用例是当您希望将所有存储的样式排队以便渲染到前端时。样式引擎将在检索时合并样式并消除重复。

//首先,让我们收集并注册我们的风格。$styles=数组(阵列(“选择器”=>“.wp-apple”,“声明”=>数组(“颜色”=>“绿色”)),);wp_style_enginee_get_stylesheet_from_css_rules($个样式,阵列(“context”=>“水果风格”,));//稍后,我们从上下文存储中获取编译的规则。$stylesheet=wp_style_engine_eget_stylesheet_from_context('水果风格');print_r($stylesheet);//。wp苹果{颜色:绿色;}if(!空($stylesheet)){wp_register_style('my-stylesheet',false,array(),true,true);wp_add_inline_style(“我的样式表”,$stylesheet);wp_enqueue_style(“我的样式表”);}

安装(仅JS)

安装模块

npm install@wordpress/style-engine--保存

此包假定您的代码将在2015年+环境。如果您使用的环境对此类语言功能和API的支持有限或不支持,您应该包括polyfill发货@wordpress/babel预设在代码中。

用法

编译CSS

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

参数

  • 风格 样式:Style对象,例如块属性的值。Style对象或theme.json中的顶级样式
  • 选项 样式选项:带有设置的Options对象,用于调整样式的生成方式。

退换商品

  • 一串:生成的样式表或内联样式声明。

变更日志

6.1.0引入WordPress核心。

获取CSSRules

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

参数

  • 风格 样式:Style对象,例如块属性的值。Style对象或theme.json中的顶级样式
  • 选项 样式选项:带有设置的Options对象,用于调整样式的生成方式。

退换商品

  • 生成的CSSRule[]:包含选择器(如果有)、CSS属性键(camelcase)和解析的CSS值的对象集合。

变更日志

6.1.0引入WordPress核心。

从原始样式获取CSS值

从传入的样式预设值返回WordPress CSS自定义变量值(如果检测到)。

预设值为字符串并遵循模式var:description|context|slug变量.

例子:

getCSSValueFromRawStyle('var:preset|color|heavenlyBlue')//返回“var(–wp–预设–颜色–天堂蓝)”

参数

  • styleValue(样式值) 样式值:表示原始CSS值的字符串。不会处理非字符串。

退换商品

  • 样式值:如果传入的样式值是预设值,则为CSS自定义变量值。

词汇表

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

块样式(古腾堡内部)
包含块样式属性的对象,该属性包含块的样式值。例如。,{间距:{边距:“10px”},颜色:{…},…}
上下文
共享共同来源或目的的一组样式的标识符,例如“块支持”或“全局样式”。上下文还用作从存储中获取CSS规则的键。
CSS声明或(CSS属性声明)
与CSS值配对的CSS属性。例如。,颜色:粉红色
CSS声明块
一组CSS声明通常与CSS选择器配对以创建CSS规则。
CSS属性
描述HTML元素的可修改风格特征的标识符。例如。,边境,字体大小,宽度
CSS规则
CSS选择器后跟一个CSS声明块,位于一组花括号内。通常在CSS样式表中找到。
CSS选择器(或CSS类选择器)
CSS选择器是CSS规则的第一个组件,是一种元素、类名或其他术语的模式,用于定义规则的CSS定义所应用的元素。例如。,p.my-col-classname>span。CSS选择器根据“class”属性的内容匹配HTML元素。请参见MDN CSS选择器文章.
CSS样式表
包含在文件或HTML样式标记.
CSS值
CSS属性的值。该值确定如何修改属性。例如10伏在里面高度:10vw.
CSS变量(vars)或CSS自定义属性
属性,其值可以在其他CSS声明中重用。使用自定义属性表示法(例如。,--wp—预设值—橄榄色:#808000;)并使用变量()功能(例如。,颜色:var(--wp--预设--橄榄色);). 请参见关于CSS自定义属性的MDN文章.
全球风格(古腾堡内部)
包含主题的theme.json和用户样式设置中的值的合并块样式对象。
内联样式
内联样式是影响单个HTML元素的CSS声明,包含在样式属性中
处理器
对存储的CSS规则执行编译和优化。查看课程`WP_样式_引擎_处理器`.
商场
包含相关样式的数据对象。查看课程`WP_样式_引擎_CSS_规则_存储`.