企业官网建设流程全解析

Elementor Atomic Builder Style Schema 完全指南：原子部件样式键的权威映射与扩展实践

【免费下载链接】elementorThe most advanced frontend drag & drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor

本文以docs/atomic-builder/fundamentals/style-schema.md为骨架，结合 Elementor 开源仓库中modules/atomic-widgets/的实现源码撰写而成。

导读

Style Schema（样式模式）是 Elementor Atomic Builder 中CSS 属性键（longhand key）与 Prop Type（属性类型）之间的权威映射表，它决定了"一个样式变体（style variant）的props里可以出现哪些键、每个键又是什么类型"。无论是为原子部件新增可样式化属性、理解 CSS Converter 的输出结构、还是为样式面板配置属性依赖（prop dependencies），都需要先读懂 Style Schema。读完本文，你将掌握 Style Schema 的完整键分组、依赖机制、断点变体数据格式、变量联合注入原理，以及通过 WordPress filter 扩展自定义样式属性的完整实践路径。

一、Style Schema 是什么

Style_Schema（源码位于 modules/atomic-widgets/styles/style-schema.php）是 Atomic Widgets 模块的规范化样式键映射。它回答两个核心问题：

1. 一个样式变体的props中允许出现哪些长写（longhand）CSS 属性键？
2. 每一个键对应的 Prop Type 是什么（尺寸、颜色、枚举、联合类型……）？

它的获取入口是Style_Schema::get()，内部会应用elementor/atomic-widgets/styles/schemafilter；而真正未经过滤的权威映射由Style_Schema::get_style_schema()返回。在前端编辑器中，这张表通过elementor/editor/localize_settings被本地化为settings.atomic.styles_schema，供 JS 侧（@elementor/editor-styles包）直接读取。

从源码实现看，get_style_schema()将 10 个私有分组方法的结果做array_merge合并，分别是：

• get_size_props()— 尺寸
• get_position_props()— 定位
• get_typography_props()— 排版
• get_spacing_props()— 间距
• get_border_props()— 边框
• get_background_props()— 背景
• get_effects_props()— 效果
• get_layout_props()— 布局
• get_alignment_props()— 对齐
• get_special_props()— 特殊属性

二、何时使用 Style Schema

Style Schema 面向以下四类场景：

• 新增或约束一个可样式化的 CSS 属性：在样式变体中注册新键、或收紧某个键的取值范围；
• 理解 CSS Converter 的输出形状：Converter 将原始 CSS 解析为带类型的 PropValue 时，其合法目标键集合即来自 Style Schema；
• 为样式面板配置属性依赖：例如object-position依赖object-fit存在且不等于fill，这类"条件显示"逻辑由 schema 中的dependencies数组驱动；
• 定位变量/动态标签联合的注入点：Variables 模块和 Dynamic Tags 模块都会通过elementor/atomic-widgets/styles/schema过滤钩子，把global-color-variable、global-font-variable等类型以联合（union）方式注入到具体键上。

需要特别区分的是：widget 设置（非样式变体）的 schema 走的是elementor/atomic-widgets/props-schema过滤器（见 prop-types.md），而样式键走的是本文讨论的styles/schema。

三、权威键清单：按分组逐项解读

以下清单为关键示例快照，权威完整列表请直接检索 style-schema.php。

1. Size 尺寸组（get_size_props）

2. Position 定位组（get_position_props）

3. Typography 排版组（get_typography_props）

4. Spacing 间距组（get_spacing_props）

padding与margin均为联合类型：dimensions（四边一体）或size（单值）。两者的单位预设不同——padding使用Size_Constants::spacing()，margin使用Size_Constants::spacing_margin()（后者额外包含auto与custom单位）。

'padding' => Union_Prop_Type::make() ->add_prop_type( Dimensions_Prop_Type::make_with_units( Size_Constants::spacing() ) ) ->add_prop_type( Size_Prop_Type::make() ->units( Size_Constants::spacing() ) ->description( 'Padding css in Size PropType format' ) ),

5. Border 边框组（get_border_props）

6. Background 背景组（get_background_props）

background使用嵌套的Background_Prop_Type（对象类型）。源码中有一处特殊处理：通过$background_prop_type->get_shape_field( Background_Overlay_Prop_Type::get_key() )逐层取得Background_Image_Overlay_Prop_Type的 shape，并调用Dynamic_Prop_Types_Mapping::make()->get_extended_schema()为其注入动态标签联合——这是"schema 递归增强"在背景对象上的直接体现。

7. Effects 效果组（get_effects_props）

8. Layout 布局组（get_layout_props）

9. Alignment 对齐组（get_alignment_props）

justify-content、justify-items、align-content、align-items、align-self均为String_Prop_Type枚举，取值覆盖 flex/grid 主流对齐关键字（center、start、end、flex-start、flex-end、space-between、stretch、anchor-center、baseline等）；order为Number_Prop_Type，数值越小越靠前。

10. Special 特殊组（get_special_props）

四、依赖机制：条件可见的属性控制

Style Schema 中的每个 Prop Type 都可以携带dependencies数组，由编辑器（editor-props包中的isDependencyMet、extractValue）负责求值。这是样式面板实现"条件控件"的底层机制。

最典型的例子是object-position，它在 style-schema.php 中被定义为：

'object-position' => Union_Prop_Type::make() ->add_prop_type( String_Prop_Type::make()->enum( Position_Prop_Type::get_position_enum_values() ) ) ->add_prop_type( Position_Prop_Type::make() ) ->set_dependencies( Dependency_Manager::make( Dependency_Manager::RELATION_AND ) ->where( [ 'operator' => 'ne', 'path' => [ 'object-fit' ], 'value' => 'fill', ] ) ->where( [ 'operator' => 'exists', 'path' => [ 'object-fit' ], ] ) ->get() ),

含义是：仅当object-fit键存在且不等于fill时，object-position控件才生效。类似地，定位组共享同一个$non_static_dependency（position存在且 ≠static），四个inset-*键都挂载它；column-gap依赖column-count ≥ 1（gte操作符）。

编辑器侧的联动细节：依赖求值在读取影响属性（affecting props）时会解包overridable信封（rewrapOverridableValue，作用于 cascade 流程），也就是说依赖判断读到的是被 override 层包裹后解开的真实值，而不是原始信封对象。

五、断点变体：{ meta, props }数据契约

一个样式变体由Style_Variant::build()生成，结构固定为{ meta, props }。构造器 style-variant.php 提供了set_breakpoint()、set_state()、add_prop()/add_props()链式方法：

{ "variants": [ { "meta": { "breakpoint": "desktop", "state": null }, "props": { "color": { "$$type": "color", "value": "#333" } } }, { "meta": { "breakpoint": "mobile", "state": "hover" }, "props": { "color": { "$$type": "color", "value": "#wc26-gold" } } } ] }

三个字段的语义：

• meta.breakpoint— 来自 Elementor 的断点配置（desktop、mobile、tablet 等），由Breakpoints\Manager体系提供；
• meta.state— 伪状态（hover、focus）或null（无状态）；style-states.php维护状态集合；
• props— Style Schema 键 → PropValue 的映射，每个值都必须符合该键对应 Prop Type 的约束（含$$type判别字段）。

渲染端拿到变体后，会结合断点与状态筛选出适用的 props，再交给样式解析器与 transformer 生成最终 CSS。

六、变量联合注入：schema 的递归增强

Style Schema 并不仅是静态表——Variables 模块会通过elementor/atomic-widgets/styles/schema过滤钩子递归增强它。在 modules/variables/hooks.php 中注册了两个 filter：

private function filter_for_style_schema() { add_filter( 'elementor/atomic-widgets/styles/schema', function ( array $schema ) { return ( new Style_Schema() )->augment( $schema ); } ); add_filter( 'elementor/atomic-widgets/styles/schema', function ( array $schema ) { return ( new Size_Style_Schema() )->augment( $schema ); } ); return $this; }

增强的具体规则：

• color→ 与global-color-variable组成联合类型；
• font-family→ 与global-font-variable组成联合类型；
• 尺寸类键 → 通过Size_Style_Schema与global-size-variable联合。

增强是递归的：会穿透对象形状（如background及其嵌套字段）与数组条目类型，直到叶子节点。此外，Dynamic Tags 模块也通过同一过滤器以优先级8注入动态标签联合（见 modules/atomic-widgets/dynamic-tags/dynamic-tags-module.php）。

变量在样式中的完整消费链路可参考 usage-in-styles.md：CSS Converter 遇到var(--label)引用时，Variable_Prop_Value_Transformer会尝试将其提升为global-*-variablePropValue；只有当键没有变量联合时，引用才回退到custom_css。

七、Public API 一览

本地化链路：在 modules/atomic-widgets/module.php 中，add_styles_schema()将Style_Schema::get()写入$settings['atomic']['styles_schema']，再通过elementor/editor/localize_settings交付给前端——JS 侧正是从这里读取 schema 以渲染样式面板、做键存在性判断与变体查找。

八、扩展：注册自定义样式键

当内置键集不满足需求时，通过add_filter在 schema 上追加键即可。以下示例为新增一个使用 spacing 单位的自定义尺寸长写属性：

add_filter( 'elementor/atomic-widgets/styles/schema', function ( array $schema ) { $schema['my-custom-longhand'] = Size_Prop_Type::make() ->units( Size_Constants::spacing() ); return $schema; } );

其中Size_Constants（size-constants.php）提供了丰富的单位预设：px、%、em、rem、vw、vh、ch、vmin、vmax、fr、s/ms、deg/rad/grad/turn、auto、custom，以及typography()、spacing()、border()、opacity()、grid_track()等按场景组织好的单位组。

注册新键之后，通常还需要两步配套工作：

1. 注册 Styles transformer（若需要自定义 CSS 输出）— 通过elementor/atomic-widgets/styles/transformers/registeraction 注册，参考 transformers.md；
2. 注册 CSS converter（若希望 Agent 通过原始 CSS 也能命中该属性）— 需要新增Property_Converter_Base子类并更新covered_properties()，详见 extension.md。

注意区分：widget 设置（非样式变体）的 schema 扩展应使用elementor/atomic-widgets/props-schema，不要与styles/schema混淆。

九、内部实现拾遗

• PropDependencies\Manager（位于modules/atomic-widgets/prop-dependencies/）负责把where()链构建成依赖术语树（dependency term tree），支持exists、ne、gte等操作符与RELATION_AND关系；
• Style_Variant::build()统一产出{ meta, props }两段式结构；
• Variables 模块通过hooks.php注册两个styles/schema过滤器（常规类型增强 + 尺寸类型增强）；
• 背景组在构建时就会触发Dynamic_Prop_Types_Mapping的递归扩展，说明 schema 的"动态化"内嵌于核心构建流程，而非完全依赖外部过滤器。

十、进一步阅读

• prop-types.md — Prop Type 体系与 PHP↔TS 映射
• transformers.md — 样式值的渲染期转换
• validation.md — schema 校验规则
• usage-in-styles.md — 变量在样式中的消费与custom_css回退
• extension.md — CSS Converter 的扩展与covered_properties()覆盖校验

【免费下载链接】elementorThe most advanced frontend drag & drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor