Elementor Atomic Builder Interactions 交互系统全解析从编辑器配置到 Motion.js 前端执行【免费下载链接】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导读本文以 Elementor 开源仓库el/elementor中 docs/atomic-builder/interactions/overview.md 为骨架结合modules/interactions/的 PHP 保存管线与elementor/editor-interactions编辑器包源码系统讲解 Atomicv4元素上的交互Interactions功能数据模型interaction item 与 PropValue 结构、保存时的校验与稳定 ID 分配、postmeta 缓存、前端经 Motion.js 执行以及面向设计师、插件作者和内部贡献者的扩展方式。读完后你将掌握该交互子系统的完整链路并能基于公共 API 二次开发。一、Interactions 是什么Interactions 为 Atomicv4元素添加动效能力。每个元素持有interactionsprop——它是一个带版本的交互条目列表每条交互条目interaction item由触发器trigger 动画预设animation preset 可选的断点排除breakpoint exclusions组成。数据的生命周期贯穿三层层级位置PHP 模块modules/interactions/编辑器包packages/packages/core/editor-interactions/前端脚本modules/interactions/assets/js/动画库Motion.jslib/motion/motion.js版本 v11.13.5从源码实现看数据在保存时被校验Validation、由Parser分配稳定 ID随后写入 postmeta 作为前端读取的缓存最终由浏览器端 Motion.js 执行动画。二、什么时候使用它设计师在编辑器 Interactions 标签页为元素配置入场entrance与滚动scroll动画无需写代码。插件/附加组件作者通过elementor/atomic-widgets/interactions/schema过滤器扩展 schema通过registerInteractionsControl注册编辑器控件可以引入自定义触发器与动画效果。内部贡献者在 modules/interactions/保存管线、校验、前端或editor-interactions标签页 UI、预览中工作。功能门控GateModule::is_experiment_active()要求启用e_atomic_elements实验即 AtomicWidgetsModule::EXPERIMENT_NAME。在 module.php 中可以看到若实验未激活__construct()会直接返回、不注册任何钩子。三、核心概念3.1 Interaction item 数据结构交互条目是一个PropValue其$$type为interaction-item包含四个字段interaction_id稳定且唯一的交互 ID保存时由 Parser 生成trigger触发器枚举load、scrollIn、scrollOut、scrollOn、hover、clickanimationanimation-preset-props类型的动画预设breakpointsinteraction-breakpoints类型的断点配置可选。其类型定义见 props/interaction-item-prop-type.phpInteraction_Item_Prop_Type extends Object_Prop_Typetrigger字段通过meta( enum, Presets::triggers_options() )标注可选枚举并通过meta( pro, Presets::ADDITIONAL_TRIGGERS )标注哪些属于 Pro 能力。3.2 文档中的数据结构示例{ version: 1, items: [ { $$type: interaction-item, value: { interaction_id: { $$type: string, value: hero-fade-in }, trigger: { $$type: string, value: scrollIn }, animation: { $$type: animation-preset-props, value: { ...: ... } } } } ] }schema 的根定义位于 schema/interactions-schema.phpInteractions_Schema::get()返回经过apply_filters( elementor/atomic-widgets/interactions/schema, ... )过滤后的 canonical prop-type 树目前固定为version: 1与items数组。3.3 保存管线Save pipeline保存流程在 module.php 中由两个钩子驱动elementor/document/save/data→handle_interactions()先Validation::sanitize()清洗并校验数据非法条目会被剔除随后validate()检查每个元素最多 5 条交互超出抛异常Element %s has more than %d interactions见 validation.php最后Parser::assign_interaction_ids()为缺少 ID 或temp-临时 ID 的条目分配稳定 ID。elementor/document/after_save→handle_interactions_cache()Interactions_Postmeta将每个元素与交互的映射写入 postmeta 缓存供前端读取。Parserparser.php会递归遍历elements树对每个interactions字段解码后若interaction_id存在且以temp-开头临时 ID或缺失则调用Utils::generate_id()生成{post_id}-{element_id}-前缀的稳定 ID并把已用 ID 记入ids_lookup防止冲突。校验器validation.php对每个条目逐层验证顶层必须为{ $$type: interaction-item, value: {...} }trigger必须通过 Trigger_Value 校验animation必须为animation-preset-props其effect仅允许fade / slide / scale / customtype仅允许in / outdirection允许空字符串或 8 个方向timing_config的duration/delay支持number与size两种格式且非负config中的start/end0–100、repeat、loop、times、times≥1、replay布尔、easing、relativeTo均做类型与范围校验breakpoints通过 Breakpoints_Value 校验自定义效果通过 Custom_Effect_Value 校验。3.4 运行时配置ConfigModule::get_config()module.php暴露给 JS 的配置对象ElementorInteractionsConfig常量JS_CONFIG_OBJECT包含两部分constants来自Presets::defaults()的预设默认值breakpoints当前激活的响应式断点配置由Plugin::$instance-breakpoints读取。编辑器侧通过wp_add_inline_script注入window.ElementorInteractionsConfig预览 iframe 通过wp_localize_script注入。3.5 预设值与枚举presets.php 定义了所有允许的枚举与默认值是校验与编辑器控件的单一事实来源类别值触发器基础load、scrollIn附加ProscrollOut、scrollOn、hover、click效果基础fade、slide、scale附加custom类型in、out方向left、right、top、bottom、top-left、top-right、bottom-left、bottom-right、缓动基础easeIn附加easeOut、easeInOut、backIn、backInOut、backOut、linear重复模式、loop、times默认值defaultDuration: 600ms、defaultDelay: 0、slideDistance: 100、scaleStart: 0、relativeTo: viewport、start: 85、end: 15、defaultEasing: easeIn、repeat: 四、前端执行从 postmeta 到 Motion.js4.1 数据收集Collector Frontend Handlerinteractions-frontend-handler.php 通过两个钩子完成前端管线elementor/frontend/builder_content_data→collect_document_interactions()在编辑模式下直接跳过否则优先从Interactions_Postmeta读取该文档的缓存缓存为空时现场process_content()生成再逐条注册进单例 Interactions_Collector请求级聚合register()/get_all()。wp_footer优先级 1→print_interactions_data()若无交互数据则直接返回否则按需加载 Motion.js 与前端交互脚本并以script typeapplication/json idelementor-interactions-data的形式集中输出 JSON每条记录为{ elementId, dataId, interactions }。4.2 前端脚本执行assets/js/interactions.js 是前端入口流程清晰等待 Motion.js 的animate与inView函数就绪waitForAnimateFunction读取#elementor-interactions-data脚本标签中的集中式 JSON按elementId通过[data-interaction-id...]选择器找到目标 DOM 元素对每条交互调用applyAnimation()先读取元素计算样式中的 transform 基线getTransformBaselineFromComputedStyle、用preserveTransformKeyframes保留已有 transform 关键帧再按效果/类型/方向生成关键帧动画期间临时将element.style.transition置为none以免 CSS transition 破坏动画按触发器分支执行scrollOut使用amount: 0.85的视口阈值并在播放后replay false时停止监听scrollIn使用amount: 0阈值其余load、hover、click等走默认动画分支。前端脚本的注册与依赖关系见 module.phpmotion-jsv11.13.5→elementor-interactions-shared-utils→elementor-interactions/elementor-editor-interactions均在elementor/frontend/after_register_scripts中注册。五、扩展Extension扩展入口有两个详见 docs/atomic-builder/interactions/schema.md 与 docs/atomic-builder/interactions/editor.mdSchema 层使用过滤器elementor/atomic-widgets/interactions/schema扩展Interactions_Schema::get()返回的 prop-type 树新增自定义 prop type 或修改现有枚举。编辑器控件层使用registerInteractionsControl注册自定义控件编辑器 UI 会自动渲染。需要注意新增触发器trigger或效果effect需要在PHP 与 JS 两侧同步实现——PHP 侧修改Validation枚举白名单与Presets新增枚举与默认值JS 侧修改interactions.js动画执行逻辑与interactions-utils.js配置解析。目前没有公开的前端注册钩子即前端执行逻辑暂不支持无侵入扩展。六、公共 API 一览符号签名用途源码Interactions_Schema::get(): array返回经过滤的canonical prop-type 树schema/interactions-schema.phpParserassign_interaction_ids( $data ): array保存时分配稳定 IDparser.phpPresetstriggers_options()、effects_options()、easing_options()、defaults()允许的枚举值与默认值presets.phpValidationsanitize( $document )、validate()保存时清洗与校验validation.phpInteractions_Frontend_Handlercollect_document_interactions()、print_interactions_data()前端收集与页脚输出interactions-frontend-handler.phpInteractions_Collector::instance()、register()、get_all()请求级数据聚合单例interactions-collector.phpregisterInteractionsControl( { type, component, options? } )注册编辑器控件interactions-controls-registry.tsinteractionsRepository.register( provider )、.all()编辑器交互数据注册表interactions-repository.tsuseElementInteractions( elementId )编辑器内读写元素的交互use-element-interactions.ts关键过滤器elementor/atomic-widgets/interactions/schema——用于扩展Interactions_Schema::get()返回的 schema。七、内部钩子与集成点钩子 / 集成点角色elementor/frontend/after_register_scripts注册 Motion.js 与交互相关脚本module.phpelementor/document/save/data校验 ID 分配elementor/document/after_save写入 postmeta 缓存elementor/frontend/builder_content_data调用collect_document_interactions收集数据wp_footer调用print_interactions_data输出集中式 JSONeditor-editing-panel挂载InteractionsTabinteractions-tab.tsx从源码结构看导入/导出import/export流程通过Interactions_Schema::get()解析交互条目保证与 schema 的 canonical 形态一致。八、延伸阅读schema.md — prop-type 树与预设editor.md — 编辑器控件注册frontend.md — Motion.js 运行时../atomic-widgets/overview.md — Atomic 元素模型../fundamentals/prop-value.md — PropValue 约定../getting-started/experiments.md — 实验特性开关【免费下载链接】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），仅供参考 Elementor Atomic Builder Interactions 交互系统全解析：从编辑器配置到 Motion.js 前端执行
Elementor Atomic Builder Interactions 交互系统全解析从编辑器配置到 Motion.js 前端执行【免费下载链接】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导读本文以 Elementor 开源仓库el/elementor中 docs/atomic-builder/interactions/overview.md 为骨架结合modules/interactions/的 PHP 保存管线与elementor/editor-interactions编辑器包源码系统讲解 Atomicv4元素上的交互Interactions功能数据模型interaction item 与 PropValue 结构、保存时的校验与稳定 ID 分配、postmeta 缓存、前端经 Motion.js 执行以及面向设计师、插件作者和内部贡献者的扩展方式。读完后你将掌握该交互子系统的完整链路并能基于公共 API 二次开发。一、Interactions 是什么Interactions 为 Atomicv4元素添加动效能力。每个元素持有interactionsprop——它是一个带版本的交互条目列表每条交互条目interaction item由触发器trigger 动画预设animation preset 可选的断点排除breakpoint exclusions组成。数据的生命周期贯穿三层层级位置PHP 模块modules/interactions/编辑器包packages/packages/core/editor-interactions/前端脚本modules/interactions/assets/js/动画库Motion.jslib/motion/motion.js版本 v11.13.5从源码实现看数据在保存时被校验Validation、由Parser分配稳定 ID随后写入 postmeta 作为前端读取的缓存最终由浏览器端 Motion.js 执行动画。二、什么时候使用它设计师在编辑器 Interactions 标签页为元素配置入场entrance与滚动scroll动画无需写代码。插件/附加组件作者通过elementor/atomic-widgets/interactions/schema过滤器扩展 schema通过registerInteractionsControl注册编辑器控件可以引入自定义触发器与动画效果。内部贡献者在 modules/interactions/保存管线、校验、前端或editor-interactions标签页 UI、预览中工作。功能门控GateModule::is_experiment_active()要求启用e_atomic_elements实验即 AtomicWidgetsModule::EXPERIMENT_NAME。在 module.php 中可以看到若实验未激活__construct()会直接返回、不注册任何钩子。三、核心概念3.1 Interaction item 数据结构交互条目是一个PropValue其$$type为interaction-item包含四个字段interaction_id稳定且唯一的交互 ID保存时由 Parser 生成trigger触发器枚举load、scrollIn、scrollOut、scrollOn、hover、clickanimationanimation-preset-props类型的动画预设breakpointsinteraction-breakpoints类型的断点配置可选。其类型定义见 props/interaction-item-prop-type.phpInteraction_Item_Prop_Type extends Object_Prop_Typetrigger字段通过meta( enum, Presets::triggers_options() )标注可选枚举并通过meta( pro, Presets::ADDITIONAL_TRIGGERS )标注哪些属于 Pro 能力。3.2 文档中的数据结构示例{ version: 1, items: [ { $$type: interaction-item, value: { interaction_id: { $$type: string, value: hero-fade-in }, trigger: { $$type: string, value: scrollIn }, animation: { $$type: animation-preset-props, value: { ...: ... } } } } ] }schema 的根定义位于 schema/interactions-schema.phpInteractions_Schema::get()返回经过apply_filters( elementor/atomic-widgets/interactions/schema, ... )过滤后的 canonical prop-type 树目前固定为version: 1与items数组。3.3 保存管线Save pipeline保存流程在 module.php 中由两个钩子驱动elementor/document/save/data→handle_interactions()先Validation::sanitize()清洗并校验数据非法条目会被剔除随后validate()检查每个元素最多 5 条交互超出抛异常Element %s has more than %d interactions见 validation.php最后Parser::assign_interaction_ids()为缺少 ID 或temp-临时 ID 的条目分配稳定 ID。elementor/document/after_save→handle_interactions_cache()Interactions_Postmeta将每个元素与交互的映射写入 postmeta 缓存供前端读取。Parserparser.php会递归遍历elements树对每个interactions字段解码后若interaction_id存在且以temp-开头临时 ID或缺失则调用Utils::generate_id()生成{post_id}-{element_id}-前缀的稳定 ID并把已用 ID 记入ids_lookup防止冲突。校验器validation.php对每个条目逐层验证顶层必须为{ $$type: interaction-item, value: {...} }trigger必须通过 Trigger_Value 校验animation必须为animation-preset-props其effect仅允许fade / slide / scale / customtype仅允许in / outdirection允许空字符串或 8 个方向timing_config的duration/delay支持number与size两种格式且非负config中的start/end0–100、repeat、loop、times、times≥1、replay布尔、easing、relativeTo均做类型与范围校验breakpoints通过 Breakpoints_Value 校验自定义效果通过 Custom_Effect_Value 校验。3.4 运行时配置ConfigModule::get_config()module.php暴露给 JS 的配置对象ElementorInteractionsConfig常量JS_CONFIG_OBJECT包含两部分constants来自Presets::defaults()的预设默认值breakpoints当前激活的响应式断点配置由Plugin::$instance-breakpoints读取。编辑器侧通过wp_add_inline_script注入window.ElementorInteractionsConfig预览 iframe 通过wp_localize_script注入。3.5 预设值与枚举presets.php 定义了所有允许的枚举与默认值是校验与编辑器控件的单一事实来源类别值触发器基础load、scrollIn附加ProscrollOut、scrollOn、hover、click效果基础fade、slide、scale附加custom类型in、out方向left、right、top、bottom、top-left、top-right、bottom-left、bottom-right、缓动基础easeIn附加easeOut、easeInOut、backIn、backInOut、backOut、linear重复模式、loop、times默认值defaultDuration: 600ms、defaultDelay: 0、slideDistance: 100、scaleStart: 0、relativeTo: viewport、start: 85、end: 15、defaultEasing: easeIn、repeat: 四、前端执行从 postmeta 到 Motion.js4.1 数据收集Collector Frontend Handlerinteractions-frontend-handler.php 通过两个钩子完成前端管线elementor/frontend/builder_content_data→collect_document_interactions()在编辑模式下直接跳过否则优先从Interactions_Postmeta读取该文档的缓存缓存为空时现场process_content()生成再逐条注册进单例 Interactions_Collector请求级聚合register()/get_all()。wp_footer优先级 1→print_interactions_data()若无交互数据则直接返回否则按需加载 Motion.js 与前端交互脚本并以script typeapplication/json idelementor-interactions-data的形式集中输出 JSON每条记录为{ elementId, dataId, interactions }。4.2 前端脚本执行assets/js/interactions.js 是前端入口流程清晰等待 Motion.js 的animate与inView函数就绪waitForAnimateFunction读取#elementor-interactions-data脚本标签中的集中式 JSON按elementId通过[data-interaction-id...]选择器找到目标 DOM 元素对每条交互调用applyAnimation()先读取元素计算样式中的 transform 基线getTransformBaselineFromComputedStyle、用preserveTransformKeyframes保留已有 transform 关键帧再按效果/类型/方向生成关键帧动画期间临时将element.style.transition置为none以免 CSS transition 破坏动画按触发器分支执行scrollOut使用amount: 0.85的视口阈值并在播放后replay false时停止监听scrollIn使用amount: 0阈值其余load、hover、click等走默认动画分支。前端脚本的注册与依赖关系见 module.phpmotion-jsv11.13.5→elementor-interactions-shared-utils→elementor-interactions/elementor-editor-interactions均在elementor/frontend/after_register_scripts中注册。五、扩展Extension扩展入口有两个详见 docs/atomic-builder/interactions/schema.md 与 docs/atomic-builder/interactions/editor.mdSchema 层使用过滤器elementor/atomic-widgets/interactions/schema扩展Interactions_Schema::get()返回的 prop-type 树新增自定义 prop type 或修改现有枚举。编辑器控件层使用registerInteractionsControl注册自定义控件编辑器 UI 会自动渲染。需要注意新增触发器trigger或效果effect需要在PHP 与 JS 两侧同步实现——PHP 侧修改Validation枚举白名单与Presets新增枚举与默认值JS 侧修改interactions.js动画执行逻辑与interactions-utils.js配置解析。目前没有公开的前端注册钩子即前端执行逻辑暂不支持无侵入扩展。六、公共 API 一览符号签名用途源码Interactions_Schema::get(): array返回经过滤的canonical prop-type 树schema/interactions-schema.phpParserassign_interaction_ids( $data ): array保存时分配稳定 IDparser.phpPresetstriggers_options()、effects_options()、easing_options()、defaults()允许的枚举值与默认值presets.phpValidationsanitize( $document )、validate()保存时清洗与校验validation.phpInteractions_Frontend_Handlercollect_document_interactions()、print_interactions_data()前端收集与页脚输出interactions-frontend-handler.phpInteractions_Collector::instance()、register()、get_all()请求级数据聚合单例interactions-collector.phpregisterInteractionsControl( { type, component, options? } )注册编辑器控件interactions-controls-registry.tsinteractionsRepository.register( provider )、.all()编辑器交互数据注册表interactions-repository.tsuseElementInteractions( elementId )编辑器内读写元素的交互use-element-interactions.ts关键过滤器elementor/atomic-widgets/interactions/schema——用于扩展Interactions_Schema::get()返回的 schema。七、内部钩子与集成点钩子 / 集成点角色elementor/frontend/after_register_scripts注册 Motion.js 与交互相关脚本module.phpelementor/document/save/data校验 ID 分配elementor/document/after_save写入 postmeta 缓存elementor/frontend/builder_content_data调用collect_document_interactions收集数据wp_footer调用print_interactions_data输出集中式 JSONeditor-editing-panel挂载InteractionsTabinteractions-tab.tsx从源码结构看导入/导出import/export流程通过Interactions_Schema::get()解析交互条目保证与 schema 的 canonical 形态一致。八、延伸阅读schema.md — prop-type 树与预设editor.md — 编辑器控件注册frontend.md — Motion.js 运行时../atomic-widgets/overview.md — Atomic 元素模型../fundamentals/prop-value.md — PropValue 约定../getting-started/experiments.md — 实验特性开关【免费下载链接】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），仅供参考