触发器

触发器指的是行为的触发时机，定义了某个行为在何时执行。

根据交互的前端（客户端）和后端（服务端）区分，触发器也分为前端触发器和后端触发器。

前端触发器

Zion 支持多种前端触发器，不同组件支持的触发器不同，以产品内“组件属性-行为”界面为准。

前端触发器可分为三类：

• 用户交互触发器：响应用户在页面上进行的交互操作，包括点击时、悬停时、进入可视区时、在可视区内滚动时。
• 状态变化触发器：响应组件状态的变化，包括值变化时、失去焦点时、开始播放时、上传成功时、进度改变时、完成时。
• 生命周期触发器：触发器自动触发，包括应用启动时、页面加载时、页面卸载时。

组件触发器通用上下文数据

触发器上下文数据是指在触发时，直接提供给行为的数据。上下文适用于除“悬停时”、“进入可视区时”和“在可视区内滚动时”之外的所有组件触发器。

触发器原生上下文

指在触发瞬间直接提供给行为的数据。

流程执行上下文

指行为开始执行后，由前序节点或运行过程产生的数据。

用户交互触发器

点击时

当组件被点击时触发。

1. 支持该触发器的组件： 按钮、文本、图片、视图、列表子视图、标签栏子视图、条件式容器子视图、自定义选择器子视图。

2. 常用场景

   • 点击按钮，向数据库添加数据
   • 点击图片，放大预览或跳转到详情页
   • 点击列表项，进入对应的详情页

3. 触发时机

无论是鼠标点击（mousedown + mouseup）还是触屏点击（touchstart + touchend），一次完整的点击交互均包含“按下”与“抬起”两个连续动作。只有当这两个动作在同一个组件的有效判定区域内连贯完成时，点击触发器才会被激活。

出现以下情况时，不会激活触发器：

• 在组件区域内按下，但未抬起（长按且无后续释放动作）；
• 在组件区域内按下，滑动/移动至组件区域外部后再抬起（常见于滑动误触取消）；
• 在组件区域外按下，滑动/移动至组件区域内部后再抬起。

4. 触发器上下文数据

本触发器上下文数据与组件触发器通用上下文一致。

5. 事件处理规则

   • 遮挡：当组件互相遮挡时，只有最上层组件的点击触发器会被触发。

   • 嵌套：在构建复杂的应用界面时，组件往往是多层嵌套的（例如：将一个“购买按钮”放置在一个“商品卡片”容器中）。如果多层组件的点击时触发器上都绑定了行为，那么就需要一个规则保证业务逻辑清晰且互不干扰：

     a. 最内层优先响应：触发器的判定从最内层开始。

     b. 事件拦截（阻止冒泡）：若当前层级绑定了行为，事件将在该层级被响应并消费，同时底层会自动调用 stopPropagation 阻止事件向父节点冒泡。

     c. 继续传播：如果当前层级没有绑定任何行为，则触发器会继续向外层传播。

     因此在嵌套的情况下，最多只有一个组件会触发点击时触发器。

6. 最佳实践：如何防止重复点击

为防止用户重复点击导致同一操作多次执行，可以使用条件式容器实现：

a. 条件式容器内设置“未点击”和“已点击”两个子容器。
b. “未点击”容器放一个按钮，按钮依次绑定两个行为：先切换到“已点击”容器，再执行目标操作（如新增数据）。
c. “已点击”容器放一个不可用（样式区分）的按钮，无需绑定行为。

这样按钮一旦被点击，就会立即变为“已点击”状态，阻止再次点击。

悬停时

组件被悬停时触发，该触发器下目前只允许添加动效相关的行为：滑动，缩放，淡入淡出，翻转，心跳，闪烁，跳动。

1. 支持该触发器的组件： 按钮、文本、图片、视图、列表子视图、标签栏子视图、条件式容器子视图。

2. 常用场景

   • 悬停在按钮上时，按钮弹跳，引导用户点击。
   • 悬停在图片上时，图片放大，更好展示图片细节。

3. 触发时机

基于浏览器原生的指针事件机制，当鼠标指针进入组件的可视边界时触发。

• 鼠标进入组件：悬停触发器会被触发一次；
• 在组件内停留：不会触发；
• 鼠标离开组件：不会触发；

4. 触发器上下文数据

无上下文数据，触发器内的行为无法绑定任何数据。

5. 事件处理规则

   • 遮挡：当组件互相遮挡时，只有最上层组件的悬停触发器会被触发。

   • 嵌套：如果父组件和子组件都在悬停触发器下绑定了行为：

     • 只在父组件上悬停时，只会触发父组件的悬停触发器；
     • 在子组件上悬停时，会同时触发父组件和子组件的悬停触发器。

进入可视区时

当目标组件出现在可视区域时触发，该触发器下仅支持添加动效相关的行为：滑动、变大/缩小、淡入/淡出、翻转、心跳、闪烁、跳动。

1. 支持该触发器的组件： 文本、按钮、图片、视频、视图、列表子视图、标签栏子视图、条件式容器子视图。

2. 常用场景

• 内容“生长”效果，当页面滚动到某个组件时，让组件从无到有地出现
• 数据生动展示，当枯燥的数据进入视野时，通过动态变化吸引注意力

3. 触发时机

该触发器实现依赖于对浏览器原生滚动事件 的实时监听与空间几何计算。

当你为组件配置了该触发器后，系统会在后台高频捕捉用户的滑动行为。在每次滚动发生时，引擎会实时获取该组件当前的物理坐标，并将其与可视区的高度进行数学比对。

一旦计算出组件的边缘跨过了系统设定的“触发起点”阈值，引擎就会判断该组件已进入可视区，立刻触发该触发器：

• 无论组件是从左侧、右侧、上侧还是下侧进入可视区域，都会触发。
• 如果进入页面时，组件已经在可视区域，也会触发。

4. 触发器上下文数据

无上下文数据，触发器内的行为无法绑定任何数据。

在可视区内滚动时

当组件在可视区内滚动时触发。这个触发器下当前仅支持添加“滚动交互”行为，用于实现特定的动画效果。

1. 支持该触发器的组件： 文本、按钮、图片、视频、视图、列表子视图、条件式容器子视图。

2. 常用场景

   • 吸引用户注意力，让组件跟随页面滚动而淡入或位移
   • 提升格调，页面滚动时，让组件进行缩放、旋转等动画效果，提升页面质感

3. 触发时机

其底层同样基于浏览器原生滚动事件 监听。但它在计算方式上更加连续和精细。当组件处于可视区内时，引擎会根据组件当前的实时物理坐标，计算出一个 0 到 1 之间的动态滚动进度比例。

由于这个进度比例是随着用户手指的滑动而实时、连续变化的，系统会直接利用该比例来驱动元素的透明度、大小、旋转或位移。这种将滚动距离按比例映射为动画进度的计算方式，使得你可以实现极其丝滑、无缝衔接的视差滚动效果。

4. 触发器上下文数据

无上下文数据，触发器内的行为无法绑定任何数据。

状态变化触发器

值变化时

在输入型组件的值发生变化时触发。

1. 支持该触发器的组件： 输入框、数据选择器、自定义选择器、日期时间选择器、开关。

2. 常用场景

   • 输入校验，当用户输入内容后，再进行校验，并给出反馈
   • 表单联动，当用户输入内容后，刷新其他组件的数据源，保持数据一致性

3. 触发时机

• 输入框：无论键盘输入、粘贴、拖拽文本进来，只要值变化了就触发。

• 数据选择器：只要选择了值（即使重复选择同一个值），就触发。

• 自定义选择器：只要选择了选项（即使重复选择同一个选项），就触发。在取消选择时，也会触发。

• 日期时间选择器：只要选择了日期或时间（即使重复选择同一个日期或时间），就触发。

• 开关：切换状态时触发。

4. 触发器上下文数据

本触发器上下文数据与组件触发器通用上下文一致。

5. 事件处理规则

• 输入法问题：在用输入框获取内容时，如果使用输入法输入，输入的过程不会触发“值变化时”触发器，只有输入完成后才会触发一次。

• 防抖问题

输入框支持设置防抖延时（毫秒），防止输入频繁时多次触发值变化触发器。

其原理是在输入框的值发生变化后，系统会先等待一段时间。如果在这段时间内用户再次输入，则重新开始计时。只有当用户停止输入持续超过设定的时间，才会触发值变化触发器。

如图中的输入框配置了 1000 毫秒的延时，那么当用户在输入并停止 1000 毫秒后，才会触发值变化触发器。

失去焦点时

在输入框失去焦点时触发。

1. 支持该触发器的组件： 输入框。

2. 常用场景

• 延时搜索，在用户输入完内容后再进行搜索
• 输入状态提示，在用户输入时和输入完成后，展示不同的样式

3. 触发时机

触发条件为：

• 输入框失去焦点；
• 当前应用的 JS 脚本依然在运行。

典型会触发的场景：

• 鼠标点击输入框之外的区域（除非关闭浏览器窗口或刷新页面，此时 JS 脚本会被销毁）；
• 按下回车键导致输入框失去焦点；
• 通过键盘 Tab 切换到其他输入项，或切换至其他浏览器窗口。

不会触发的情况：

• 正在使用输入法选择候选词；
• 直接关闭浏览器窗口（但如果是小程序退出，仍会触发，因为小程序页面未被完全销毁）；
• 刷新页面。

4. 触发器上下文数据

本触发器上下文数据与组件触发器通用上下文一致。

开始播放时

视频组件开始播放时触发。

1. 支持该触发器的组件： 视频组件。

2. 常用场景

• 视频播放统计，记录用户播放视频的次数
• 播放提示：当视频开始播放时，调整页面样式，吸引用户注意力

3. 触发时机

• 初次播放时触发；
• 从暂停/停止状态重新播放时触发。

4. 触发器上下文数据

本触发器上下文数据与组件触发器通用上下文一致。

上传成功时

图片组件或视频组件上传图片或视频成功后触发。

1. 支持该触发器的组件： 图片组件、视频组件。

2. 常用场景

• 图片上传统计，记录用户上传图片次数
• 图片上传完成提示，当图片上传完成时，提示用户上传成功

3. 触发时机

每上传一张图片或视频成功时触发一次。

如果图片数量上限大于 0，即可以上传多张图片，那么每上传一张图片成功后都会触发一次。

4. 触发器上下文数据

本触发器上下文数据与组件触发器通用上下文一致。

进度改变时

只要进度条组件的进度发生变化时就会触发该触发器。

1. 支持该触发器的组件： 进度条组件。

2. 常用场景

• 进度条进度提示，当进度条进度发生变化时，提示用户进度变化

3. 触发时机 进度条数值发生变化时触发。

4. 触发器上下文数据

本触发器上下文数据与组件触发器通用上下文一致。

完成时

Lottie 动画组件播放完成时触发。

1. 支持该触发器的组件： Lottie 动画。

2. 常用场景

• 动画播放完成提示，当动画播放完成时，提示用户动画播放完成

3. 触发时机 动画播放完成时触发。

4. 触发器上下文数据

本触发器上下文数据与组件触发器通用上下文一致。

生命周期触发器

生命周期触发器涵盖了应用和页面从创建、更新到销毁的全过程。

系统完整的生命周期触发器的时序图如下：

应用启动时

应用根组件首次完成挂载（DOM/原生视图渲染上屏）时触发的触发器，整个应用生命周期内仅触发一次。

1. 常用场景

• 在应用启动时，初始化客户端变量
• 在应用启动时，发起静默登录（小程序强制调用）或获取设备信息

2. 触发时机

应用启动时在各端 App 根组件首次完成挂载时触发。

运行时实际执行顺序为：

1. 用户配置的行为；
2. 系统自动追加的隐式查询：拉取“当前用户”数据；
3. 上述查询成功后，自动刷新当前用户数据。

由于用户配置的行为运行在第 1 步、而当前用户数据要等到第 2 步成功之后才可用，因此用户配置行为时，无法使用任何已登录用户数据（包括 id 字段）。

同样，由于本触发器运行在任何页面进入之前，页面变量、弹窗变量、页面参数与页面数据源也都不在作用域内，无法使用。

会触发的情况：

• 通过任意方式进入应用的第一个页面，包括：通过链接直接访问、从其他页面跳转访问、通过浏览器的前进后退访问
• 刷新页面时

不会触发的情况：

• 在应用内部页面间跳转时不会触发（只有在新标签页中打开页面时才会触发，此时相当于重新进入应用）
• 小程序进程未被销毁时再次进入应用

3. 触发器上下文数据

触发器原生上下文

指在触发瞬间直接提供给行为的数据。

流程执行上下文

指行为开始执行后，由前序节点或运行过程产生的数据。

页面加载时

“页面加载时”指页面 UI 完成首次挂载（DOM/原生视图渲染上屏）的瞬间触发的触发器。此时页面上的组件尚未开始渲染，远程数据尚未获取，因此无法引用任何组件的的输出和数据源。

1. 常用场景

• 在页面加载时，初始化页面变量
• 在页面加载时，记录用户访问该页面的时间

2. 触发时机

页面加载过程实际上由两条并发的执行路径组成：

• UI 渲染路径：页面组件挂载完成 → 触发本触发器，并将该触发器下配置的行为推入运行时引擎的执行队列执行。
• 数据源请求路径：页面及其内部组件的数据源（远程查询、当前用户完整数据）从挂载之后开始独立发起请求。

两条路径互不等待，因此本触发器执行时无法保证页面数据源已返回，无法引用任何远程数据，详见下方“受限数据”。

以下情况会触发：

• 通过任意方式进入页面，包括：通过链接直接访问、从其他页面跳转访问、通过浏览器的前进后退访问
• 刷新页面时

以下情况不会触发：

• 在小程序页面栈中未被销毁时，进入到该页面（具体请参考下文“小程序特殊说明”）

3. 触发器上下文数据

触发器原生上下文

指在触发瞬间直接提供给行为的数据。

流程执行上下文

指行为开始执行后，由前序节点或运行过程产生的数据。

页面卸载时

“页面卸载时”指当前页面对应的页面组件进入卸载阶段时触发的触发器。通常在该时机，页面内数据已完成初始化，因此可以读取页面内已有数据。

1. 常用场景

• 记录用户在页面中的停留时间
• 在退出页面时清理仅在该页面有效的客户端变量

2. 触发时机

该触发器仅在应用内路由切换导致的页面卸载场景下可靠；关闭浏览器、刷新页面或跳转到站外页面会直接销毁 JavaScript 执行上下文，行为执行不可靠，按不触发处理。

会触发的情况：

• 在应用内通过跳转行为切换到其他页面（不是打开新标签页的方式）；
• 浏览器的前进、后退到本应用的其他页面；
• 在小程序中页面被实际从页面栈中销毁（具体请参考下文“小程序特殊说明”）。

不会触发的情况：

• 关闭浏览器；
• 刷新页面；
• 跳转到应用外的页面；
• 打开新标签页（原页面仍存活，未被销毁）；
• 在小程序中页面只是入栈、未被销毁（具体请参考下文“小程序特殊说明”）。

3. 触发器上下文数据

触发器原生上下文

指在触发瞬间直接提供给行为的数据。

流程执行上下文

指行为开始执行后，由前序节点或运行过程产生的数据。

4. 事件处理规则

小程序由于存在“页面栈”的概念，并用一套机制控制页面的加载和销毁，导致其生命周期触发器和 Web 端非常不同。下文将简略介绍小程序的生命周期触发器，详细完整的说明请参考：小程序页面栈 

小程序的页面会被组织为一个页面栈加若干不在栈中的悬垂页面的组合形式。

• 页面栈：按顺序存放了通过跳转依次打开的页面。
• 悬垂页面：当前已经创建但非活跃的 tabBar 的页面。

不同的跳转方式会对应不同的页面栈行为，导致前一个页面的状态（是否被销毁）不同，进而影响生命周期触发器的触发：

后端触发器

目前支持的后端触发器有：数据库内容变化、Webhook、定时。

其中“数据库内容变化”和“定时”触发的行为流均属于自动执行的行为流，有次数限制：

1. 每月免费额度（次月 1 号自动重置）：

• 免费版：1000 次/月
• 高级版：10000 次/月
• 专业版：50000 次/月

2. 超出部分可按需付费（次数永久有效）：

• 费用：10 元 / 10000 次

数据库内容变化

用于数据库的数据发生变更（新增、更新或删除）时，执行行为流，能够大幅度提升项目自动化水平。

1. 常用场景

   • 业务流程自动化：如用户付费达到一定金额时自动升级会员、订单状态变更时自动执行相关操作等。
   • 数据监控：如数据异常时自动报警、数据变更时记录审计日志等。
   • 数据统计：如订单完成后自动统计销售额、用户行为数据等。

2. 触发时机

触发时机：在数据修改完成并写入数据库之后触发。数据库触发器是在原数据变更提交后，即数据已真实落盘。如果触发器关联的行为流执行失败，不会导致原先的数据修改被回滚。

触发级别：行级别触发，即每条数据修改都会触发一次。因此，即使修改多条数据只用了一个请求，只要更新了几次，就会触发几次。

3. 配置项说明

a. 选择操作类型：Zion 提供了四种触发类型：

• 数据新增时
• 数据更新时
• 数据删除时
• 数据新增或更新时

b. 选择数据表：要监听的数据表。所有在数据模型中可见的表均可以被选择。

c. 数据条件：设置触发条件，只有条件满足时，才会触发行为流。在触发条件中，可以拿到新增的、更新前的、更新后的、删除的数据，以及它们的关联表数据。

d. 行为流输入：设置行为流的输入。可用的数据如下：

另外，系统时间相关常量和 Secret 也可用于配置行为流入参。

为了数据一致性，等执行到行为流时无法保证关联表数据仍与触发瞬间一致，因此这里不支持把关联表数据直接作为行为流输入。

4. 特殊说明

• 循环触发问题：行为流之间可以通过数据库触发器或运行行为流节点互相嵌套触发。为了防止循环触发导致死循环，在一个触发链中，同一个行为流只允许被触发一次。

例如：行为流 A 触发了行为流 B，B 触发 C，C 触发 A。最后的 A 不会被触发执行。

• 导入数据时的触发问题

在数据管理-导入数据功能中，提供了“启用触发器”的配置，可选择批量导入数据时是否触发相关行为流。

• 假更新问题

即使更新后的数据与更新前的数据相同，也会触发“数据更新时”和“数据新增或更新时”触发器。

5. 最佳实践

• 如何避免行锁与死锁

由于数据库触发器是在原数据变更提交后异步发起的新事务，它虽然不会阻塞原操作，但在高并发场景下，多个异步触发器对同一批关联表进行交叉更新时，极易引发行级锁争用甚至死锁。避免死锁的关键在于：

• 规范顺序：在全局设计上，必须严格遵守统一的改表先后顺序（例如永远先修改订单表，再修改库存表，最后修改财务表），避免交叉抢锁。
• 快进快出：触发器只做最简单、最必要的数据修改，避免在触发器内实现复杂逻辑或嵌套触发。

• 如何实现只在某一列更新时触发行为流

如需仅在特定字段变化时触发，可以在数据条件中设置数据条件为： 更新前的数据/某一列 不等于 更新后的数据/某一列。

这样，只有对应列发生变化，行为流才会被触发。

Webhook

接收外部系统的 HTTP 回调触发，用于实现外部系统与行为流的集成。

1. 常用场景

   • 支付回调
   • 外部数据同步至 Zion 数据库

2. 触发时机

在系统接收到请求，并且满足以下条件时，会触发行为流：

• 请求方法为 POST 或 GET；
• 请求体的结构（字段名与类型）需与触发器内配置的 Request Body 一致。

3. 配置项说明

• 地址：Webhook 的 URL 地址。

• 类型：请求体的类型，提供三个选项：默认、支付宝、微信支付。在选择支付宝或微信支付时，系统会自动将请求体格式配置完成。而默认情况下，需要手动配置请求体格式。除非该 Webhook 用于支付回调，否则选择默认即可。

• 请求体（Request Body）映射：

在编辑器中定义 Webhook 请求体结构时，需要使用固定根字段 callback-request-body。该字段用于平台内部的结构映射与 schema 校验。

注意：callback-request-body 仅用于平台配置，不要求第三方在真实 HTTP 回调中携带。 外部系统实际发请求时，将编辑器里定义在 callback-request-body 下的字段直接放在 JSON 根层发送即可；平台会在接收后按配置结构进行归一化与校验。请求体目前仅支持对象类型。

例如在触发器配置面板中定义：

{
  "callback-request-body": {
    "order_id": "1234567890"
  }
}

则实际发起 HTTP 请求时，请求体为（无需包一层 callback-request-body）：

{
  "order_id": "1234567890"
}

• 行为流输入：设置行为流的输入，可用的数据如下：

• 响应体（Response Body）：

用于响应请求，支持三种类型：application/json、text/plain、text/html。支持绑定行为流的出参。

定时

用于按指定时间间隔自动触发行为流，适用于需要周期性执行的任务。

1. 常用场景

   • 定期检查订单状态，并关闭超时的订单
   • 用户会员到期前，发送通知。

2. 触发时机

在配置完成后，一旦更新后端就开始运行。

错过触发处理：如果服务器升级或宕机，重启后触发器将按原计划继续运行。在此期间错过的定时任务将被直接丢弃（Discard），不会进行补偿执行。

3. 配置项说明