事件交互

2026年7月8日大约 10 分钟

事件交互

事件交互让大屏「活」起来：某个事件发生时，执行一个或多个动作。它与数据联动（cross-filter / select-sync）是两套正交机制——数据联动关注「数据的传播」，事件交互关注「行为的编排」。

触发器 → 动作

一个元素（页面 / 组件 / 子元素都行）上可配多组「触发器 → 动作」，存在它的 options.interactions 里。持久化形态：

"interactions": {
  "version": 2,
  "groups": [
    {
      "trigger": { "name": "click", "options": {} },
      "interactions": [
        {
          "alias": "点击→打开链接",
          "trigger": { "name": "click", "options": {} },
          "action": { "name": "openUrl", "options": {
            "url": "https://…", "openWay": "_blank",
            "start": "meanwhile", "delay": 0, "duration": 1 } }
        }
      ]
    }
  ]
}

一个分组 = 一种触发器（trigger.name + 触发器自身 options）。同名但 options 不同（如不同 eventName）= 不同分组。
一个分组下可挂多条「交互项」（编辑器里的一行）。
动作通用 options：start / delay / duration。调度：meanwhile 与上一动作并入同一批（批内并行、全部完成才算完），follow 等上一批完成后再开始；delay、duration 单位都是 ms。开窗 / 跳转 / 请求等一次性动作只在首帧执行一次（引擎逐帧重调时跳过），duration 只对缓动（changeOption 的 isTween）和 appear / disappear 有意义——示例里的 duration: 1 是惯例占位。

在线演示

下面的预览就是播放态，交互真实生效。

① 点击按钮 → changeOption 修改文本：

② switchState 多状态切换（告警变色）：点「触发告警 / 恢复正常」，中间文本在两个状态间切换（默认态存 options，告警态存 stateOverrides）。

触发器清单

name	别名	适用	payload（传给动作的 `{:字段}`）
`click`	点击	组件	无
`mouseEnter` / `mouseLeave`	移入 / 移出	组件	无
`appear` / `disappear`	入场 / 离场	组件	无（配合进 / 退场动画）
`receiveBehaviorEvent`	接收二开事件	组件 / 页面	发送方带的 data
`itemClicked`	点击某项	柱 / 饼 / 表 / 列表 / 图片等	选中项维度，如 `{城市:"北京"}`（仅类目）
`click-row` / `select-row` / `unselect-row` / `click-operate`	表格行 / 操作列	表格	`{ rowNumber, rowIndex, columnUID, value, row:{别名:值}, ...选中维度 }`；`click-operate` 另含 `operate` / `operateIndex`
`selectTrigger` / `unselectTrigger`	选中 / 取消选中	按钮（开「启用选中态」）	`row`（`{关系字段:关系值}`）
`search`	搜索时	搜索框	`{keyword, value, fuzzy}`
`viewChanged`	视图切换	视图容器 / 导航 / 轮播	`{index, label}`
`mediaEnded`	播放完毕	视频	`{src}`
`timeChanged`	时间变化	时间轴	`{time}`
`marker-click` / `region-click` 等 14 个	地图要素 / 视角 / 就绪…	2D 地图	命中要素属性，可 `{:name}` / `{:value}`，全表见 2D 地图 · 事件
`scene3d-piece-click` / `-dblclick` / `-contextmenu` / `-hover` / `scene3d-blank-click`	三维元素点击 / 双击 / 右键 / 悬停 / 空白	三维场景	`{pieceUid, name, pieceType}`，几何拾取另含 `hitX/hitY/hitZ`，见三维 · 播放态交互
`scada-node-click` / `scada-node-dblclick` / `scada-link-click` / `scada-blank-click`	组态图元 / 连线 / 空白	组态画板	`{nodeUid, name, shape, dataKey, value}`
`conditionMeet`	数据规则满足	页面	无
`screenAppear`	页面入场	页面	无（`appearSwitch`：`first` / `always`）
`timer`	定时器	页面	`{ time, count }`（触发时刻 ms + 第几次；配置见下）

提示

触发器多在预览 / 播放态才生效（编辑态点击 = 选中组件）。itemClicked 的 payload 只含类目字段（如 城市）不含数值；要取整行数值用表格的 click-row（payload 含整行 row）。conditionMeet / screenAppear / timer 写在页面节点上，其余写在组件上。

触发器的归属：前四行是基线触发器——组件基线 6 个（click / mouseEnter / mouseLeave / appear / disappear / receiveBehaviorEvent）所有组件都有，页面基线 4 个（conditionMeet / screenAppear / timer / receiveBehaviorEvent）写在页面节点；其余（itemClicked、表格行、地图 / 三维 / 组态专有等）由各组件类的 defineCustomTriggers() 按需注册，只在对应组件的交互面板出现。每个组件页「事件」小节列出的就是该组件实际可用的触发器全集（由审计脚本对照源码保持零差异）。

timer 的触发器 options：mode（interval 每隔一段 / at 每天时刻）、interval（秒，最小 1）、at（HH:mm[:ss]）、startDelay（秒）、maxCount（最大次数，0 不限）、onlyActiveScreen（多页面时仅当前激活页运行）。仅播放态运行；标签页转入后台即暂停，回前台按当前配置从「现在」重建，不补跑漏掉的次数。

动作清单

name	别名	关键 options
`changeOption`	修改设置	`element`（目标）、`optionKey`（属性名）、静态值或动态公式（见下）
`switchState`	切换状态	`element`、`state`（状态 uid，`""` 回默认）
`switchPopup`	控制弹窗	`popupUid`（弹窗容器 `group-popup`）、`operate`（仅 `show` / `hide`）
`custom`	组件自定义	由目标组件自身定义的专有动作面板（如地图 / 组态派生动作）
`switchScreen`	切换页面	`screenUID`
`switchWindow`	打开 / 关闭窗口	`windowUid`、`operate`（`open`/`close`/`toggle`），见窗口系统
`openUrl`	打开链接	`url`（支持 `{:param}` / `{:payload字段}` 插值）、`openWay`
`reloadData`	刷新数据	`connection`（数据源 uid；空 = 刷新全部可重取数据源，仅 api/webhook 会真正重新取数）
`editProjectParams`	修改项目参数	`params-key` + `<key>-params-value`（驱动规则 / 条件样式）
`changeFullscreen`	全屏播放控制	进入 / 退出全屏
`logoutVisitor`	访客退出登录	清除访客会话（配合发布访问控制）
`writePayloadToEmbedded`	写入内嵌数据集	把 payload 写入内嵌（JSON）连接的表，驱动其它组件刷新
`sendBehaviorEvent`	发送行为事件	`element`、`eventName`（payload 透传给目标的 `receiveBehaviorEvent`）
`transfer`	传递触发	`element`、`trigger`（代触发目标的某触发器）
`executeScript`	执行脚本	`commond`（由宿主二开 `onScript` 接管，见 SDK）
`requestApi`	调用接口	出站 HTTP / 平台数据请求，结果可写参数 / 数据源 / 派发事件（见下）
`appear` / `disappear`	进 / 退场动画	对目标 `opacity` 做 0↔100 插值
`empty`	空动作	占位（保留分组结构，动作待配）

专有动作：地图 17 个（mapFlyTo / mapLayerVisible 等，见 2D 地图 · 事件）、三维场景 12 个（scene3dFlyTo / scene3dFocus / scene3dWritePoint / scene3dSetOption 等，见三维 · 播放态交互）、组态 scadaWritePoint（写测点，value 填 toggle 则 0↔1 翻转）与 scadaSetOption（改图元选项，如指定图像集第几张，见组态）、按钮 5 个（selected / unSelected 设置选中态，enterFullscreen / exitFullscreen / toggleFullscreen 整页全屏）。

transfer 动作的坑

transfer 的 options 只留 element + trigger，不要带 start / delay / duration，否则会并入触发匹配的 options 而匹配不到目标分组。另外它不透传 payload（目标交互链拿不到源事件数据），并内置 cycleGuard 防环（A↔B 互相 transfer 只跑一圈）。

changeOption 详解

目标怎么选（targetElement）——三种模式：

targetElement	语义	搭配键
`searchElement`（默认）	`element` 直接指定目标；空 = 触发元素自身	`element`
`filterElementChildren`	以 `element[0]` 为父，按名称过滤其子元素批量修改	`element` + `filterKey`（名称包含）、`isRecursionFilter`（递归）
`filterCurrentChildren`	同上，但以动作所在元素自身为父	`filterKey` / `isRecursionFilter`

静态值的键名规则：值写在 optionKey 末段同名键上——optionKey: "text" → options 里再写 "text": 新值（上面演示①即此写法）；optionKey 为路径数组时取最后一段，如 ["text-font","size"] → 键为 "size"。

动态取值：valueDynamic: true + valueMode 三选一——value（取目标当前值）、fromCurrentValue（取触发组件的当前值）、formula（公式插值）。公式在 valueFormula 里用 {:expr} 插值，取值优先级：先取 payload 字段（{:字段} / {:row.字段}；{:value} 优先取 payload 的数值），payload 无则 {:value} 回退目标当前值，其余名按项目参数取。

"action": { "name": "changeOption", "options": {
  "element": [{ "targetPath": ["screen_main","w_text"], "refType": "element" }],
  "optionKey": "text", "valueDynamic": true, "valueMode": "formula",
  "valueFormula": "已选中：{:城市}" } }

缓动：静态修改数值 / 向量类属性时可加 isTween: true + easing（缓动曲线），在 duration（ms）内从当前值插值到新值。

requestApi 调用接口

出站请求动作，requestKind 二选一（默认 http），响应按 resultMode 落地：

键组	键	说明
通用 HTTP（`requestKind: "http"`）	`method` / `url` / `headers`（JSON 文本）/ `authToken`（Bearer）/ `body` / `timeout`（ms）	`url` / `headers` / `body` 支持 `{{参数名}}` / `{{payload.字段}}` 占位——注意是双花括号，与 changeOption 公式的 `{:}` 不同
平台数据（`requestKind: "platform"`）	`platformOp`：`list` / `view` / `create` / `update` / `delete` / `createCollection` / `deleteCollection`	操作本系统数据表（PocketBase）；按操作搭配 `collection`（物理名）、`recordId`、`filter` / `sort` / `expand` / `page` / `perPage`（list）、`body`（create / update / 建表负载），同样支持 `{{...}}` 占位
结果处理（共用）	`resultMode`：`ignore` / `setParams` / `setData` / `emit`	`setParams` 配 `paramKey` + `valuePath`（响应取值路径，空 = 整个响应）；`setData` 配 `connection` + `table`（空 = 首表）+ `dataPath`（行数组路径）；`emit` 配 `resultEventName`（响应作 payload 派发，可被 `receiveBehaviorEvent` 接住）

一次性动作（仅首帧发一次）；带在途去重（同配置请求未返回前跳过本次）与超时中断。典型闭环：页面 timer → requestApi（resultMode: "setData"）→ 图表自动刷新。

目标元素引用

动作作用到「哪个元素」，统一写 element: [{ targetPath: [...uid路径], refType: "element" }]：

页面：["screenUid"]
组件：["screenUid", "widgetUid"]
子元素（地图图层 / 三维元素 / 组态图元）：["screenUid", "widgetUid", "pieceUid"]
空 / 省略 → 目标 = 触发元素自身。

多目标分流（actions[] + triggerTarget）

部分触发器（地图要素点击 / 三维元素点击 / 组态图元点击 / 地图右键菜单项等）支持「逐项设置」：一条交互项用 actions[] 替代单 action，每个动作带 triggerTarget（图层 / 图元 / 菜单项的 uid 或 key）；运行态按命中的目标只执行对应动作。

{ "trigger": { "name": "scada-node-click", "options": {} },
  "actions": [
    { "triggerTarget": "node_pump",  "name": "switchWindow", "options": { /* … */ } },
    { "triggerTarget": "node_valve", "name": "switchScreen", "options": { /* … */ } }
  ] }

多状态（states / stateOverrides）

一个组件（或页面）可声明多个状态（如「正常 / 告警」）。默认状态的样式存 options，其它状态只存差异覆盖 stateOverrides[状态uid]：

{
  "options": { "text": "待机", "background-color": "#1b2233" },
  "states": [
    { "uid": "", "name": "待机" },        // ★ 默认态 uid 必须是空串
    { "uid": "cs_alarm", "name": "告警" }
  ],
  "stateOverrides": {
    "cs_alarm": { "text": "⚠ 告警", "background-color": "#3a1418" }
  }
}

三种切换方式：

方式	怎么触发
① 主动切（事件 → 动作）	`switchState` 动作：`{ element, state:"<uid>" }`（`""` 回默认）
② 数据驱动	状态开 `useCurrentRuleField: true` + 比较规则（`dataRuleField` / `dataRuleFunc` / `dataRuleArgs`）+ 组件 `state-rule-fields` 绑定字段，取字段首行值比较，数据变即自动重算
③ 跟随页面态	状态加 `followScreenStates`；页面切态时组件联动切。或 `followDataRules` 跟随工程数据规则

提示

多个状态按 states 顺序求值，首个命中生效；每个状态内按 ① followScreenStates → ② useCurrentRuleField + dataRule* → ③ followDataRules 的顺序判定（开了 useCurrentRuleField 的状态不再看 followDataRules）。都不命中时保持当前态、不回退（数据驱动场景把「常态」放默认态即可）。覆盖按顶层键整体替换（改字体颜色要写完整 text-font 对象）。

延伸阅读：数据系统 · 数据规则（conditionMeet / 数据驱动状态的规则来源）· 窗口系统（switchWindow 动作）· SDK（executeScript / sendBehaviorEvent 与宿主互通）。