---
name: screen-interaction
description: 给大屏加交互：点击切换整页内容、点击图表钻取明细、选择器筛选数据、标题跟着选择变化。例如"做成两页，顶部导航切换销售和库存""点柱状图里的某个模型，下面显示这个模型的明细""加一个模型选择器"
---

# 大屏交互

交互都靠大屏变量：点击写变量，组件读变量。变量、显示条件、筛选、事件的写法见 update_canvas 和 set_interaction 的参数说明

点击交互只在预览和线上页运行；编辑器画布不执行事件，显示变量默认值下的样子，可以用「预览变量值」切换查看。告诉用户到预览里点击验证。整批通过检查就说明变量、筛选、事件的引用都对得上，回复里直接说明点哪里会切换什么，不要说"可能不生效""还未确认"

## 步骤

1. 用 update_canvas 在 variables 里声明变量（整组替换，保留已有的变量）；默认值取数据里存在的值，类型和数据一致（"1" 与 1 不等）
2. 加组件、写数据，再用 set_interaction 给组件设显示条件、筛选和事件；同一批里先后顺序不限，整批执行完才检查引用
3. 提交后按 apply_actions 的结果核对：引用对不上会整批报错，按提示修正后重新提交

## 整页切换

- 用选项导航（nav）：props.var 写变量 ID，items 每项是一页（label 页名，value 写进变量的值）；点击选项写变量不用配事件
- 每页的组件用 set_interaction 写 visibleWhen：{"var": "page", "equals": "该页的 value"}
- 不同页的组件可以放在同一块区域，它们不会同时显示；导航和大屏标题这类各页共用的组件不写 visibleWhen

## 钻取

- 主图表用 itemClick 事件写变量：{"type": "itemClick", "action": {"setVar": "model", "fromField": "model"}}，fromField 是数据行里的列；被点的数据项会显示为选中
- 明细组件用 filters 按变量筛选：{"field": "model", "var": "model"}；field 是它自己数据行里的列
- 被筛选的组件的 $query 不要对筛选字段加 WHERE，结果要带上这一列，前端按变量筛选
- 也可以加一个 nav 做选择器：items 写 $query，例如 SELECT DISTINCT model AS label, model AS value FROM t ORDER BY 1

## 明细指标卡

- 指标卡写 rows 和 bind：rows 是按筛选字段汇总好的数据行（每个筛选值一行），bind 把列绑定到字段，例如 {"value": "calls", "compare.value": "calls_mom", "trend.data": "trend"}
- rows 用 $query，趋势列用数组，例如 SELECT model, SUM(calls) AS calls, list(calls ORDER BY day) AS trend FROM (按模型、日期汇总) GROUP BY model
- 再用 set_interaction 给它写 filters，和钻取的明细组件一样

## 标题跟着变

- 文本内容写 {{变量ID}}，例如"{{model}} 调用明细"；变量为 null 时那一段为空