客户端和页面行为

设置变量

修改页面变量或客户端变量的值，支持向数组变量中追加或移除元素。

常用场景

记录用户在表单中的临时输入状态。
动态控制组件的显示与隐藏。

参数配置

参数	类型	是否必填	说明
作用域	枚举	是	允许选择“客户端”或“页面和组件”，切换下方对应的变量配置面板。
变量	文本	是	选择定义在当前页面中的页面变量，或全局的客户端变量。
操作	枚举	否	仅当所选变量为数组类型时展示。可选：设为、添加、移除。
值	和变量类型一致	是	指定要赋予、追加或移除的数据值。支持绑定组件输出、静态值等。

运行结果与输出

无

运行机制

依托系统内置的状态管理，自动定位并更新目标变量。
状态更新完成后，系统会自动通知所有使用了该变量的组件重新加载。
数组追加操作会将新数据添加到列表的最后。
数组移除操作会根据传入的值进行匹配并从数组中过滤移除：
1. 对象比对：如果传入的值是包含 id 属性的普通 JavaScript 对象，无论该对象属于数据模型表，还是在页面本地创建的自定义对象，系统均会精准比对该 id 进行过滤移除。
2. 值全等比对：如果传入的值是基础类型或不带 id 的对象，系统会自动执行全等判定，直接移除完全相同的数据。

常见错误

类型错误：如果值的类型与变量类型不匹配，编辑器中会给出错误提示。

用法举例

1、记录用户输入状态 (Web 端)

需求：用户在填写多步表单时，需要将第一步填写的姓名暂存到页面变量中，以便在最后一步提交时统一读取。
配置流程：
1. 前置准备：
  - 创建 “表单页面”；
  - 在 “表单页面” 中配置好一个输入框。
  - 在右侧菜单栏的 “数据” 标签的 “变量” 分类下，新建一个文本类型的页面变量。
2. 选择组件：在 “表单页面” 画布上，选中 “按钮”。
3. 添加行为：在右侧配置面板中切换到 “行为” 标签页，直接在 “点击时” 事件下点击添加操作。
4. 配置行为基础参数：
  - 在行为选择下拉框中，搜索并选中 “设置变量”。
  - 作用域选择 “页面和组件”，变量选择刚刚创建的页面变量。
5. 绑定参数传递：
  - 点击值输入框右侧的 “+” 加号按钮，在弹出的数据源中依次展开并选择精确路径：组件 -> 输入框 -> 组件输出。
运行结果：用户在网页端点击按钮时，系统会将输入框中的文本成功保存到页面变量中。

刷新数据源

强制目标组件重新发起数据请求，获取并渲染最新数据。

常用场景

提交表单后，刷新列表组件以展示最新添加的数据。
切换筛选条件后，刷新图表或列表组件。
定时任务触发时，刷新页面核心数据。

参数配置

参数	类型	是否必填	说明
刷新目标	数组	是	通过级联选择器选择当前页面或页面中包含查询逻辑的目标组件。可添加多个。

运行结果与输出

无

运行机制

系统会遍历需刷新的组件列表，触发目标组件的查询事件，强制重新向服务器请求并获取最新数据。
如果目标组件的数据源来自变量或自定义数组等本地数据，则直接跳过刷新操作。
如果目标组件 (如列表或表格) 开启了分页功能，刷新后，重置列表并自动返回第一页，用户当前在列表或表格中的翻页进度全部丢失。

特殊说明

如果目标组件当前处于隐藏状态或未加载，系统会跳过刷新操作。这可能导致用户再次看到该组件时显示的是旧数据。建议在组件重新显示时再次触发刷新，或者使用全局变量来自动同步数据。
如果刷新目标选择页面，只会刷新页面的数据源，不会刷新页面中的组件。

常见错误

无

用法举例

1、提交表单后刷新列表 (小程序端)

需求：用户在弹窗中提交新的反馈意见后，底层的反馈列表需要立即刷新以展示刚刚提交的内容。
配置流程：
1. 前置准备：
  - 创建 “反馈页面”；
  - 在 “反馈页面” 中配置好一个展示反馈数据的列表，以及一个包含按钮的表单弹窗。
2. 选择组件：在 “反馈页面” 画布上，选中表单弹窗内的 “按钮”。
3. 添加行为：在右侧配置面板中切换到 “行为” 标签页，在添加数据行为的成功时中，点击添加操作。
4. 配置行为基础参数：
  - 在行为选择下拉框中，搜索并选中 “刷新数据源”。
  - 点击添加刷新列表项，在级联菜单中选择底层的列表。
5. 绑定参数传递：
  - 无需额外绑定参数。
运行结果：用户在小程序端点击按钮后，表单数据入库，底层的列表自动重新发起请求并展示最新数据。

2、切换分类后刷新商品 (Web 端)

需求：用户在左侧菜单点击不同的商品分类时，右侧的列表需要刷新并展示对应分类的商品。
配置流程：
1. 前置准备：
  - 创建 “商城页面”，在页面的数据中，添加一个整数类型的变量 category，用于存储当前选中的分类 id。
  - 在 “商城页面” 中配置好两个列表：分类列表和商品列表，商品列表的查询条件绑定了 category 变量。
2. 选择组件：在 “商城页面” 画布上，选中左侧列表内的 “列表项”。
3. 添加行为：在右侧配置面板中切换到 “行为” 标签页，添加：
  - 添加设置变量行为，将 category 设为：列表项 -> 分类 -> 当前项 -> id。
  - 添加刷新数据源行为，点击添加刷新列表项，在级联菜单中选择右侧的商品列表。
运行结果：用户在网页端点击不同分类时，右侧列表会根据新的分类条件重新加载第一页的商品数据，左侧列表会根据新的分类条件重新加载第一页的商品数据。

滚动页面

控制当前活动页面滚动至顶部或指定的组件位置。

常用场景

长列表翻页或加载更多后，提供回到顶部的快捷操作。
点击锚点导航菜单，页面平滑滚动至对应的内容区块。

参数配置

参数	类型	是否必填	说明
滚动至	枚举	是	下拉选择滚动方向：“页面顶部”或是“指定组件”。
组件	文本	否	仅指定组件时必填。级联或下拉选择当前页面中所有可见组件，指定要滚动到的目的地。

运行结果与输出

无

运行机制

视口容器控制本质：滚动操作的本质是对当前活动页面容器视口偏移量的控制，而非对组件本身进行位置样式，例如位移和定位属性的修改。
系统会查询当前活动页面的容器节点（滚动容器），并直接将该容器的 scrollTop 属性值设为 0，从而将内部页面内容的顶端滚动对齐至视口最上方。当滚动到指定组件时，系统会先获取目标组件相对于其最近定位祖先节点的垂直偏移高度（offsetTop），随后将该高度数值赋给滚动容器的 scrollTop 属性。这能使目标组件的顶端刚好停留在视口最上方。

特殊说明

滚动的动画效果和最终停留的精确位置由系统自动控制，目前不支持手动微调偏移距离。
如果目标组件当前处于隐藏状态，页面将无法滚动到该位置。
高危警告：由于无法手动调整滚动的偏移距离，如果你的页面顶部有固定不动的导航栏，滚动到目标组件时，组件的顶部可能会被导航栏遮挡。

常见错误

目标不存在：如果指定的滚动目标组件不存在或已被删除，系统会忽略该操作。这不会导致页面白屏或应用崩溃，用户体验不受影响。

用法举例

1、回到页面顶部 (小程序端)

需求：用户在浏览长篇幅的新闻详情页时，点击右下角的按钮，页面直接滚动回最上方。
配置流程：
1. 前置准备：
  - 创建 “新闻详情页”；
  - 在 “新闻详情页” 中配置好长文本内容，并在右下角固定定位一个按钮。
2. 选择组件：在 “新闻详情页” 画布上，选中 “按钮”。
3. 添加行为：在右侧配置面板中切换到 “行为” 标签页，直接在 “点击时” 事件下点击添加操作。
4. 配置行为基础参数：
  - 在行为选择下拉框中，搜索并选中 “滚动页面”。
  - 滚动至选择 “页面顶部”。
5. 绑定参数传递：
  - 无需额外绑定参数。
运行结果：用户在小程序端点击按钮后，页面视口会立刻滚动回新闻标题所在的顶部位置。

2、滚动至评论区 (Web 端)

需求：用户在阅读博客文章时，点击文章开头的 “查看评论” 链接，页面自动向下滚动到容器的位置。
配置流程：
1. 前置准备：
  - 创建 “博客文章页”；
  - 在 “博客文章页” 中配置好文本，并在页面底部配置好一个容器。
2. 选择组件：在 “博客文章页” 画布上，选中文章开头的 “文本”。
3. 添加行为：在右侧配置面板中切换到 “行为” 标签页，直接在 “点击时” 事件下点击添加操作。
4. 配置行为基础参数：
  - 在行为选择下拉框中，搜索并选中 “滚动页面”。
  - 滚动至选择 “指定组件”，在组件级联菜单中选择底部的容器。
5. 绑定参数传递：
  - 无需额外绑定参数。
运行结果：用户在网页端点击链接后，页面视口会自动向下滚动，直到容器完整出现在视野中。

控制定时任务

控制页面内定时任务的开始与暂停状态。在配置行为前，需要在页面的行为标签的定时任务分类下，新建定时任务，并设置好触发间隔。详情请参考定时任务。

常用场景

轮播图组件的自动播放与悬停暂停控制。
验证码倒计时的启动与重置。
实时数据大屏的定时刷新启停开关。

参数配置

参数	类型	是否必填	说明
定时任务	文本	是	下拉选择要控制的定时任务实例。
操作	枚举	是	下拉选择要执行的任务动作：“开始”或“暂停”。

运行结果与输出

无

运行机制

开始逻辑与首拍重置：
- 防止重复开始：Zion 引擎内置防止重复开始的幂等机制，只有首次触发会真正创建定时器。例如在 1 秒内连续发送 100 次开始指令，系统只会创建 1 个定时器，后续 99 次指令都会被直接忽略。
- 交替触发重置死锁：若极高频地交替触发暂停和开始，例如快速开关切换，则会触发原生定时器的首拍重置陷阱。由于定时器在启动后需要等待一个完整的时间间隔，例如 5 秒，才会执行第一次行为，而高频地先暂停后开始会不断销毁并重新初始化定时器。每次重新启动都会将等待时间彻底归零，导致定时任务因始终到不了第一个触发点而发生运行死锁。
暂停逻辑与即时销毁：当触发定时任务暂停时，系统底层会立即同步执行 clearInterval 彻底销毁该定时器，并从内存中擦除任务标识，瞬间释放被闭包占用的内存资源并停止计时。
触发后续行为流：当后台定时器运行并到达设定的时间间隔后，系统会自动触发你在该定时任务上绑定的下游行为流，例如设置变量与刷新数据源等，从而完成自动更新的闭环。

特殊说明 由于底层基于浏览器原生的 setInterval API 实现，需警惕以下机制，以防产生逻辑陷阱：

异步任务重叠与服务器过载风险：setInterval 仅负责定期将任务推入队列，并不等待其执行完毕。如果你的定时任务内部频繁触发刷新数据源等耗时长的异步网络请求，且网络拥堵导致响应时间超过了设定的执行间隔，多个请求会在后台并行悬起，导致页面渲染数据前后错乱，甚至因请求暴增而导致服务器过载崩溃。请务必开启防连击保护，或合理调大时间间隔。
后台节流与时间冻结陷阱：现代浏览器和微信小程序客户端为了节电，会对进入后台运行的定时器进行极严苛的限制甚至挂起暂停。
主线程卡顿导致的时间漂移：JS 是单线程执行的。如果页面上发生复杂渲染或重型计算，定时器回调将在宏任务队列中滞后排队，导致定时任务的实际触发时间相比物理世界发生偏移。因此，定时任务不能用于制作高精密的时间测量仪。
页面跳转时的销毁规则：定时任务在页面跳转时是否销毁完全取决于页面在内存中是被卸载还是在后台暂存：
- Web 端：当页面跳转时，原页面组件会被彻底卸载，因此 100% 自动彻底销毁定时器。
- 小程序端：若使用推入页面跳转，原页面只是被页面栈底层暂存，并未销毁，定时器仍会存活。但微信底层的渲染容器会强制冻结该页面上所有的原生 setInterval 定时器，切回原页面时会自动恢复运转；若使用重定向或返回跳转，原页面会从栈中彻底弹出并销毁，系统会同步销毁该定时器。

常见错误

无

用法举例

1、启动验证码倒计时 (小程序端)

需求：用户在登录页面点击获取验证码按钮并发送短信成功后，系统需要自动启动一个每秒执行一次的定时任务，用来动态递减并更新按钮上的倒计时剩余秒数，例如从 60 秒到 0 秒。
配置流程：
1. 前置准备，即创建变量与定时任务：
  - 在左侧的页面面板中，新建一个名为 登录页面 的页面。
  - 在 登录页面 画布上，拖入一个按钮组件。
  - 在右侧菜单栏的数据 -> 变量中，新建一个长整数类型的变量 countdown_sec，默认值设为 60。在页面上绑定按钮的文本为 countdown_sec。
  - 在右侧菜单栏的行为 -> 定时任务中新建一个定时任务：时间间隔设为 1000，不勾选立即执行。在该任务的行为编辑器中，绑定一个设置变量行为，将 countdown_sec 用公式设置为 countdown_sec - 1。
2. 选择组件：在 登录页面 画布上，选中按钮。
3. 添加行为：在右侧配置面板中切换到行为标签页，在发送短信的成功分支下点击添加操作。
4. 配置参数：
  - 在行为选择下拉框中，搜索并选中控制定时任务。
  - 定时任务配置项选择刚才创建的倒计时任务，操作选择开始。
5. 绑定参数传递：
  - 无需额外绑定参数。
运行结果：用户在小程序端点击按钮并成功发送短信后，倒计时定时任务正式启动，页面上的倒计时数字开始逐秒递减。