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 模块的规范化样式键映射。它回答两个核心问题一个样式变体的props中允许出现哪些长写longhandCSS 属性键每一个键对应的 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 SchemaStyle 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键类型说明width/height/min-width/min-height/max-width/max-heightSize_Prop_Type元素尺寸overflowString_Prop_Type枚举visible/hidden/autoaspect-ratioString_Prop_Type对应 CSSaspect-ratioobject-fitString_Prop_Type枚举fill/cover/contain/none/scale-downobject-positionUnion_Prop_Type 依赖字符串枚举Position_Prop_Type::get_position_enum_values()或Position_Prop_Type依赖object-fit存在且 ≠fill2. Position 定位组get_position_props键类型说明positionString_Prop_Type枚举static/relative/absolute/fixed/stickyinset-block-start/inset-inline-end/inset-block-end/inset-inline-startSize_Prop_Type逻辑定位带$non_static_dependency依赖position存在且 ≠staticz-indexNumber_Prop_Type层叠顺序scroll-margin-topSize_Prop_Type单位限定为Size_Constants::anchor_offset()3. Typography 排版组get_typography_props键类型说明font-familyFont_Family_Prop_Type字体族font-weightString_Prop_Type枚举100–900、normal、bold、bolder、lighterfont-size/letter-spacing/word-spacing/line-heightSize_Prop_Type单位限定为Size_Constants::typography()colorColor_Prop_Typehex / rgb(a) / hsl(a) / CSS 颜色名column-countNumber_Prop_Type文本分栏数column-gapSize_Prop_Type依赖column-count ≥ 1gte操作符text-alignString_Prop_Type枚举start/center/end/justifyfont-styleString_Prop_Type枚举normal/italic/obliquetext-decorationString_Prop_Type自由字符串源码中留有TODO [EDS-524]待更严格校验text-transformString_Prop_Type枚举none/capitalize/uppercase/lowercasedirectionString_Prop_Type枚举ltr/rtlstrokeStroke_Prop_TypeSVG 描边allString_Prop_Type枚举initial/inherit/unset/revert/revert-layercursorString_Prop_Type枚举当前仅pointer4. Spacing 间距组get_spacing_propspadding与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键类型说明border-radius/border-widthUnion_Prop_Type专用类型Border_Radius_Prop_Type/Border_Width_Prop_Type或Size_Prop_Type单位Size_Constants::border()border-color/outline-colorColor_Prop_Type颜色border-style/outline-styleString_Prop_Type枚举none/hidden/dotted/dashed/solid/double/groove/ridge/inset/outsetoutline-width/outline-offsetSize_Prop_Type单位Size_Constants::border()6. Background 背景组get_background_propsbackground使用嵌套的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键类型说明mix-blend-modeString_Prop_Type枚举normal/multiply/screen/overlay/darken/lighten/color-dodge/saturation/color/difference/exclusion/hue/luminosity/soft-light/hard-light/color-burnbox-shadowBox_Shadow_Prop_Type阴影opacitySize_Prop_Type百分比 0–100默认单位%Size_Constants::opacity()filterFilter_Prop_Type滤镜backdrop-filterBackdrop_Filter_Prop_Type背景滤镜transformTransform_Prop_Type变换transitionTransition_Prop_Type过渡8. Layout 布局组get_layout_props键类型说明displayString_Prop_Type枚举block/inline/inline-block/flex/inline-flex/grid/inline-grid/flow-root/none/contentsflex-directionString_Prop_Type枚举row/row-reverse/column/column-reversegapUnion_Prop_TypeLayout_Direction_Prop_Type或Size_Prop_Type单位Size_Constants::layout()flex-wrapString_Prop_Type枚举wrap/nowrap/wrap-reverseflexFlex_Prop_TypeFlex 简写grid-template-columns/grid-template-rowsUnion_Prop_Type字符串或Grid_Track_Size_Prop_Type单位grid_track()fr/customgrid-auto-flowString_Prop_Type枚举row/column/row dense/column densegrid-auto-rows/grid-auto-columnsSize_Prop_Type单位grid_auto_track()默认单位frgrid-column/grid-rowSpan_Prop_Type带正则校验/^(?!.*https?:\/\/)(?!.*;).*$/禁止 URL 与分号9. Alignment 对齐组get_alignment_propsjustify-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键类型说明contentString_Prop_Type伪元素content的字符串内容appearanceString_Prop_Type枚举none/autoclip-pathString_Prop_Type裁剪形状四、依赖机制条件可见的属性控制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_dependencyposition存在且 ≠static四个inset-*键都挂载它column-gap依赖column-count ≥ 1gte操作符。编辑器侧的联动细节依赖求值在读取影响属性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 中注册了两个 filterprivate 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.mdCSS Converter 遇到var(--label)引用时Variable_Prop_Value_Transformer会尝试将其提升为global-*-variablePropValue只有当键没有变量联合时引用才回退到custom_css。七、Public API 一览Symbol签名用途Style_Schema::get()static get(): array返回经过 filter 的完整 schemastyle-schema.phpStyle_Schema::get_style_schema()static get_style_schema(): array返回未经 filter 的权威映射getStylesSchema()getStylesSchema(): Recordstring, PropType编辑器侧editor-styles包读取本地化 schemaisExistingStyleProperty()isExistingStyleProperty( property: string ): boolean判断某键是否存在于 schema 中getVariantByMeta()getVariantByMeta( variants, meta )按断点/状态查找变体editor-styles包本地化链路在 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_Constantssize-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()等按场景组织好的单位组。注册新键之后通常还需要两步配套工作注册 Styles transformer若需要自定义 CSS 输出— 通过elementor/atomic-widgets/styles/transformers/registeraction 注册参考 transformers.md注册 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考