Elementor Atomic Builder Interactions 交互系统深度解析从 Schema 校验到 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 开源仓库中 docs/atomic-builder/interactions 文档体系完整剖析 v4 Atomic原子元素上的交互Interactions能力——包括数据模型、Schema 校验管线、编辑器elementor/editor-interactions包与 Motion.js 前端运行时。读完你既能掌握设计者视角的动效配置模型也能以开发者身份理解如何通过 filter 扩展交互 Schema、注册编辑器控件以及定位动画不生效类问题的完整排查链路。一、Interactions 是什么分层架构与实验门控Interactions 为 Atomicv4元素提供动效能力每个元素持有一个interactionsprop——一个带版本号的交互项列表每个交互项 触发器trigger 动画预设animation preset 可选的断点排除breakpoint exclusions。数据在保存时校验、写入 postmeta 缓存供前端读取最终由客户端Motion.js执行动画。从 docs/atomic-builder/interactions/overview.md 的架构表可以看到完整的四层分布层位置PHP 模块modules/interactions/编辑器包packages/packages/core/editor-interactions/前端脚本modules/interactions/assets/js/动画库Motion.jsassets/lib/motion/版本 v11.13.5该功能受实验特性门控约束Module::is_experiment_active()要求启用e_atomic_elements即AtomicWidgetsModule::EXPERIMENT_NAME定义于 modules/atomic-widgets/module.php。若实验未激活modules/interactions/module.php 的构造函数会直接返回、不注册任何 hook。这也解释了为何在普通模式下看不到 Interactions 标签页。不同角色的使用场景设计师在编辑器 Interactions 标签页配置入场动画与滚动动画插件/Addon 作者通过elementor/atomic-widgets/interactions/schemafilter 扩展 Schema通过registerInteractionsControl注册编辑器控件内部贡献者在modules/interactions/保存管线、校验、前端或editor-interactions标签页 UI、预览中工作。二、数据模型Interaction Item 与文档结构2.1 Interaction Item每个交互项是$$type: interaction-item的 PropValue包含四个字段见 docs/atomic-builder/interactions/schema.md字段Prop 类型描述interaction_idstring稳定的每项 ID保存时由 Parser 分配为{post_id}-{element_id}-*triggerstringenum动画何时触发animationanimation-preset-props效果、类型、方向、时序、配置breakpointsinteraction-breakpoints断点排除可选2.2 文档形状Document Shape完整的元素交互数据按如下 JSON 结构存储{ 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: { ...: ... } } } } ] }这套带类型的 PropValue 包装{ $$type, value }是 Atomic Widgets 数据模型的基础约定详细规范可参考 docs/atomic-builder/fundamentals/prop-value.md。编辑器端构建这些结构的工具函数集中在 prop-value-utils.tscreateInteractionItem、createAnimationPreset、createTimingConfig、createConfig等它们把 TS 侧平铺字段转换为上述嵌套 PropValue 形态。2.3 动画预设animation-preset-props字段Prop 类型描述effectstringenumfade、slide、scale、customtypestringenumin或outdirectionstringenum滑动方向见下方快照timing_configtiming-configduration、delayTime_Size_Prop_Type毫秒configconfig-v2replay、easing、relativeTo、repeat、times、start、endcustom_effectcustom-effectkeyframes—— 仅 Prometa: pro2.4 断点interaction-breakpoints字段Prop 类型描述excludedexcluded-breakpoints跳过该交互的断点标签列表三、Schema服务端 Prop 类型树与内置预设3.1 Interactions_SchemaInteractions_Schema是交互数据的权威 PHP prop-type 树modules/interactions/schema/interactions-schema.php被校验、导入导出、prop-type 迁移以及编辑器 MCP schema 资源共同消费Interactions_Schema::get(); // → apply_filters( elementor/atomic-widgets/interactions/schema, … )内置 schema 结构为version当前为 1items数组元素类型由Interaction_Item_Prop_Type定义。对应的各 Prop 类型类位于 modules/interactions/props/全部继承 Atomic Widgets 的Object_Prop_Type符号key职责源码Interaction_Item_Prop_Typeinteraction-item根条目形状props/interaction-item-prop-type.phpAnimation_Preset_Prop_Typeanimation-preset-props效果 时序形状props/animation-preset-prop-type.phpAnimation_Config_Prop_Typeconfig-v2replay、easing、滚动区间props/animation-config-prop-type.phpTiming_Config_Prop_Typetiming-configduration delayprops/timing-config-prop-type.phpCustom_Effect_Prop_Typecustom-effect关键帧自定义效果props/custom-effect-prop-type.phpInteraction_Breakpoints_Prop_Typeinteraction-breakpoints断点包装props/interaction-breakpoints-prop-type.phpPresets—枚举常量与默认值presets.php3.2 内置值快照Built-in Values以下枚举与默认值直接来自 modules/interactions/presets.php其中标注pro的选项仅在 Pro 中开放触发器TriggersKey层级load、scrollInBasescrollOut、scrollOn、hover、clickPro效果Effectsfade、slide、scaleBasecustomPro。类型Typesin、out。方向Directionsleft、right、top、bottom、top-left、top-right、bottom-left、bottom-right、。缓动EasingeaseInBaseeaseOut、easeInOut、backIn、backInOut、backOut、linearPro。默认值duration600ms、delay0、slide distance100、scale start0、easingeaseIn、滚动区间85%–15%、relativeTo为viewport、repeat 为可选loop/times。上限每个元素最多 5 个交互项由Validation强制。这些默认值通过Presets::defaults()暴露并在 module.php 的get_config()中以constants键注入ElementorInteractionsConfig全局对象供编辑器与前端读取。例如Animation_Config_Prop_Type中start/end是单位为%的Size_Prop_Type默认 85/15easing的默认值easeIn与Presets::DEFAULT_EASING一致见 props/animation-config-prop-type.php。3.3 Pro 门控机制Prop 类型通过meta( pro, … )标记 Pro-only 值例如Animation_Preset_Prop_Type中的custom_effect、Animation_Config_Prop_Type中的replay/relativeTo/repeat/times/start/endInteraction_Item_Prop_Type的trigger通过Presets::ADDITIONAL_TRIGGERS标记 Pro 触发器。编辑器侧则用PromotionSelect限制基础档位可选值参考 editor-interactions/src/ui/ 下的promotion-select.tsx与interactions-promotion-chip.tsx。四、保存管线校验、ID 分配与 postmeta 缓存4.1 两步保存流程Module::register_hooks()modules/interactions/module.php挂载了两个关键钩子elementor/document/save/data→handle_interactions()先Validation-sanitize()递归消毒并校验再Validation-validate()检查数量上限最后Parser-assign_interaction_ids()分配稳定 IDelementor/document/after_save→handle_interactions_cache()调用Interactions_Postmeta-process_content()写入按元素分组的缓存。4.2 Validation逐字段校验modules/interactions/validation.php 定义白名单VALID_EFFECTS [fade,slide,scale,custom]、VALID_TYPES [in,out]、VALID_DIRECTIONS含空串与VALID_REPEAT_MODES [,loop,times]。sanitize()递归遍历元素树含嵌套elements对每个interactions字段做以下处理兼容数组与 JSON 字符串两种输入统一解码出items校验每项的$$type interaction-itemtrigger必须通过TriggerValueValidatorvalidators/trigger-value.php 中的六种合法值校验animationeffect/type/direction枚举、timing_configduration/delay同时接受number与size两种格式且 0、configreplay必须为 boolean、repeat必须是loop|times|、times 1、start/end在 0–100 之间、custom_effect通过Custom_Effect_Value校验breakpoints若存在则必须通过BreakpointsValueValidator。validate()阶段对每个元素累计交互项数量超过$max_number_of_interactions 5时抛出异常Element %1$s has more than %2$d interactions从而在保存层面阻断非法数据。对应的单元测试覆盖见 tests/phpunit/elementor/modules/interactions/test-validation.php。4.3 Parser稳定 ID 分配modules/interactions/parser.php 负责给交互项分配跨会话稳定的interaction_id未携带 ID 或携带temp-前缀临时 ID编辑器新建项时由generateTempInteractionId生成的项会通过Utils::generate_id( {$post_id}-{$element_id}-, $ids_lookup )重新生成已有稳定 ID 的项保留并登记进ids_lookup防止重复。因此保存后形如123-abc123-1的 ID 会成为该交互项的永久标识前端 DOM 绑定依赖的是元素 ID见第六节而interaction_id更多服务于去重、复制粘贴与 MCP 工具定位。Parser的行为由 tests/phpunit/elementor/modules/interactions/test-parser.php 验证。4.4 Postmeta 缓存缓存由 modules/interactions/cache/interactions-postmeta.php 管理Meta key 为elementor-interactions-cache写elementor/document/after_save→process_content()自动跳过 autosave 与草稿状态读load_content()直接读 postmeta缓存过期时回退process_content()重建删当提取出的交互映射为空时delete_post_meta()。真正做树遍历提取的是 cache/elements-interactions.php递归遍历元素树提取每个元素的interactions.items生成element_id items映射。这层缓存让前端渲染时无需每次重新解析整个元素树是文档中强调的性能关键点。五、编辑器端elementor/editor-interactions包5.1 包结构与初始化elementor/editor-interactions实现了 v4 编辑器侧的完整交互表面Interactions 标签页、逐字段控件、预览播放、剪贴板粘贴与 MCP 工具。它作为 atomic-widgets v2 包注册入口为 src/init.tsinit()依次完成注册默认数据提供者documentElementsInteractionsProvider注册粘贴命令与重复元素时清理临时交互 ID的 hook注册基础控件见下表注册interactionsMCP 域initMcpInteractions参考 docs/atomic-builder/mcp/registering-editor-tools.md。5.2 Interactions 标签页InteractionsTabsrc/components/interactions-tab.tsx的工作流程通过useElementInteractions( elementId )读取元素交互数据有数据时在InteractionsProvider内渲染InteractionsList无数据时展示EmptyState点击创建首个交互逐项编辑通过InteractionDetails/InteractionSettings完成。useElementInteractionssrc/hooks/use-element-interactions.ts订阅elementor/element/update_interactions窗口事件保证外部改动实时同步到标签页。编辑器内预览播放复用的是editor-interactions.jsMotion.js 运行时而非 React 包本身。5.3 控件注册表Controls Registry核心 API 定义于 src/interactions-controls-registry.tsregisterInteractionsControl( { type, component, options? } ); getInteractionsControl( type ); getInteractionsControlOptions( type );InteractionsControlType覆盖 14 种控件trigger、effect、effectType、direction、duration、delay、replay、repeat、times、easing、relativeTo、start、end、customEffects。其中基础档在init.ts中注册的选项如下控件类型基础选项triggerload、scrollIneffectfade、slide、scaleeffectTypein、outdirectiontop、bottom、left、righteasingeaseInreplaynorepeat无固定选项duration与delay通过TimeFrameIndicator内联渲染relativeTo、start、end、times、customEffects等注册槽位已存在但由配套包如 Pro在各自init()时注册——这正是注册表 槽位设计支持 Pro 扩展的方式。5.4 数据提供者与配置桥interactionsRepositorysrc/interactions-repository.ts是提供者注册表默认提供者documentElementsInteractionsProvider读取文档元素上的交互数据任何编辑器包都可以在自己的init()中通过interactionsRepository.register( createInteractionsProvider( … ) )注册新提供者createInteractionsProvider支持key、priority、subscribe与actions见 src/utils/create-interactions-provider.ts。配置桥get-interactions-config.ts读取window.ElementorInteractionsConfig由 PHPModule::enqueue_editor_scripts通过wp_add_inline_script注入见 module.php使前端获得与 PHP 侧一致的默认常量与活动断点。六、前端运行时Motion.js 渲染管线6.1 完整管线modules/interactions/interactions-frontend-handler.php 与 assets/js/interactions.js 构成前端管线elementor/frontend/builder_content_data → collect_document_interactions → Interactions_Postmeta::load_content或 process_content 回退 → Interactions_Collector::register 按元素注册 wp_footer优先级 1 → print_interactions_data → script idelementor-interactions-data…/script interactions.jsDOMContentLoaded → 解析 JSON → 查询 [data-interaction-id] → Motion.animate / inView编辑模式下整个流程被跳过collect_document_interactions与print_interactions_data均在开头检查Plugin::$instance-editor-is_edit_mode()。6.2 Footer JSON 形状print_interactions_data()将Interactions_Collector聚合的数据编码为 JSON 输出到页脚脚本标签{ elementId: abc123, dataId: abc123, interactions: [ /* items */ ] }脚本标签 id 为elementor-interactions-data对应Module::SCRIPT_ID_INTERACTIONS_DATA。interactions.js找到该标签后JSON.parse再对每条记录执行document.querySelectorAll( [data-interaction-id elementId ] )进行 DOM 绑定。6.3 运行时触发器行为assets/js/interactions.js 中的三种运行时触发器行为触发器行为load立即animate()defaultAnimationscrollIninView且amount: 0进入视口时播放scrollOutinView且amount: 0.85退出视口时播放先以 0 时长复位到初始关键帧其余 Schema 中的触发器hover、click、scrollOn与custom效果会被isSupportedInteraction()直接跳过见 assets/js/interactions-utils.js——这正是文档强调的运行时子集 vs 完整 Schema差异。若replay为 falsescrollIn/scrollOut播放一次后即停止监听。6.4 断点排除逻辑assets/js/interactions-breakpoints.js 从ElementorInteractionsConfig.breakpoints读取活动断点配置min/max 方向与阈值由 PHP 侧Module::get_active_breakpoints()注入监听resize100ms 防抖维护当前断点。skipInteraction()interactions-shared-utils.js检查交互项的breakpoints.excluded是否包含当前活动断点标签命中则跳过该动画——实现了响应式场景下移动端不做入场动画这类需求。6.5 关键帧构建与 transform 保留getKeyframes( effect, type, direction )负责把 Schema 语义转换为 Motion.js 关键帧fade→opacity: [0,1]in或[1,0]outscale→scale: [scaleStart, 1]in或[1, scaleStart]outslide 方向 → 按slideDistance默认 100生成x/y位移复合方向如top-left会叠加两个轴。为避免动画覆盖元素已有的 CSS transform旋转、平移、缩放运行时先通过getTransformBaselineFromComputedStyle解析getComputedStyle的 matrix再用preserveTransformKeyframes把基线合并进关键帧。同时applyAnimation会先将element.style.transition置为none动画结束后再恢复防止 CSS transition 干扰 Motion 动画。这些工具函数同时通过window.elementorModules.interactions暴露供 Pro 等第三方消费。七、扩展指南Addon 作者如何接入7.1 通过 filter 扩展 SchemaInteractions_Schema::get()最终经过elementor/atomic-widgets/interactions/schemafilter因此 Addon 可以在不修改核心代码的前提下追加字段add_filter( elementor/atomic-widgets/interactions/schema, function ( array $schema ) { $item $schema[items][0]; $shape $item-get_shape(); $shape[my_extension] My_Extension_Prop_Type::make(); $item-set_shape( $shape ); return $schema; } );新的 Prop 类型类应放在modules/interactions/props/同构位置遵循现有Object_Prop_Type子类写法。7.2 三端平行修改要求文档明确强调新增 trigger / effect 需要平行修改三处缺一不可PHP 侧Validation枚举白名单与Presets选项枚举编辑器侧registerInteractionsControl注册对应控件组件前端侧isSupportedInteraction()interactions-utils.js中的支持列表。编辑器侧扩展新控件的内部路径为实现组件 → 在init.ts中registerInteractionsControl注册新数据提供者 →interactionsRepository.register( createInteractionsProvider( … ) )注册 MCP 工具 →initMcpInteractions( getMCPByDomain( interactions, … ) )。前端没有公开的注册 hook运行时能力的扩展只能修改核心 JS 文件本身。导入导出模块则通过Interactions_Schema::get()解析/重组交互项确保 Schema 扩展后导入导出仍能正确往返。八、测试与验证仓库为 Interactions 提供了 PHPUnit 与前端 Jest 双层测试保障tests/phpunit/elementor/modules/interactions/test-validation.php构造标准interaction-itemPropValuecreate_prop_type_interaction与create_config_prop辅助函数覆盖 effect/type/direction/timing/config 各字段的合法与非法输入tests/phpunit/elementor/modules/interactions/test-parser.php通过Parser_Ex子类接管 ID 生成验证{post_id}-{element_id}-{n}分配逻辑tests/phpunit/elementor/modules/interactions/test-interactions-collector.php 与 cache/test-elements-interactions.php验证收集器与树遍历提取编辑器包测试src/tests/ 与 src/components/controls/tests/含interaction-details、resolve-direction、paste-interactions、各控件组件测试。九、常见排查路径与总结调试动画未生效时按文档给出的链路自底向上排查实验特性e_atomic_elements是否开启未开启则整个模块不加载保存是否成功检查Validation是否抛超过 5 个交互异常、interaction_id是否已从temp-转为稳定 ID前端数据是否到位页脚是否存在#elementor-interactions-data脚本标签、JSON 中elementId是否与 DOM 上data-interaction-id匹配运行时是否跳过触发器是否落在load/scrollIn/scrollOut子集内、效果是否为custom、当前断点是否在breakpoints.excluded中Motion.js 是否加载成功window.Motion.animate/window.Motion.inView是否存在waitForAnimateFunction最多轮询 10 次。Interactions 将触发器 动画预设 断点规则的声明式模型与 Motion.js 的高性能运行时结合配合 Schema filter、控件注册表与 postmeta 缓存兼顾了编辑体验、扩展性与前端性能。更完整的模型背景可继续阅读 docs/atomic-builder/atomic-widgets/overview.md、docs/atomic-builder/fundamentals/prop-types.md 与 docs/atomic-builder/migration/prop-type-migrations.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），仅供参考
