variables.md

全局变量 (Global Variables) 使用指南

在 ThingsVis 平台中，全局变量 (Variables) 是一种强大的核心状态管理机制。它允许您在仪表盘的多个组件（大屏、卡片、图表）之间共享数据，实现复杂的联动效果，甚至可以通过持久化（Persistent）特性将应用状态同步到浏览器的 URL 中，刷新也不会丢失。

1. 变量的作用与设计理念

与仅属于单个组件的“内部状态”不同，全局变量是属于整个可视化应用 (Dashboard) 的。 您可以将它想象成一个公共的数据池：“一处定义，处处可用；一处修改，全局响应”。

常见的使用场景：

• 公共过滤器：一个下拉框修改了 currentCity 变量，页面上所有的图表自动更新为该城市的数据。
• 主题/模式切换：一个开关按钮修改了 isDarkMode 变量，全站的主题配色随之改变。
• 状态共享：在多页面或多层级的弹窗中，传递当前的“选中设备 ID”。

---

2. 如何创建与定义全局变量

最近的版本中，全局变量的入口被统一整合。

1. 在编辑器的界面的左侧面板（组件库/大纲列表的上方菜单），找到并点击 “全局变量” (Variables) 面板。
2. 弹出面板中，可以概览当前所有的变量。点击面板右上角的 + (添加) 来新建变量。
3. 填写以下属性来定义变量的行为：
   • 变量标识符 (Name)：唯一的英文名称，比如 currentCity。这是您在公式和代码里引用它的标识。
   • 名称 (Label)：友好的显示名称，比如“当前城市”，方便自己记忆。
   • 类型 (Type)：非常重要，这决定了变量存储的数据格式，底层内核支持解析以下几种：
     • string (字符串): 文字
     • number (数字): 用于计算或坐标
     • boolean (布尔): true/false，常用于开关控制
     • object / array (对象和数组): 用于存储复杂的结构化数据
   • 默认值 (Default Value)：仪表盘首次加载时该变量的初始值。
   • 持久化保存 (Persistent)：(开关) 如果开启，该变量将被自动同步到浏览器网址栏。

⚠️ 保存注意： 全局变量定义（即新增或删除变量结构）会随大屏一起保存到后端。您平时在面板中只是修改“草稿 (Draft)”定义，点击面板上的保存或使用快捷键 Ctrl+S 时，定义才会被真正写入系统存储池并持久化。

---

3. 在组件中使用变量 (双向绑定)

定义好变量后，您就可以在组件的属性配置、数据源甚至文本中引用它。

方式 A：文本与配置项插值 (数据读取)

在支持动态数据绑定的文本框或任何其他组件属性配置中，使用双大括号语法 {{ var.变量标识符 }} 即可读取全局变量。

这套语法在底层会自动根据您的使用场景进行“智能识别”：

1. 独立引用 (保持原始类型)

如果您的输入框里仅有大括号，没有包含任何其他额外字符：

{{ var.currentCity }}

💡 优势： 这种写法在底层会直接传递变量的原始数据类型。如果您在全局变量里存了一个 Array 数组或 Object 对象，这种写法能原封不动地把对象数据传给图表组件，完全不会被强制转成字符串，非常适合用作图表的高级数据源。

2. 文本混合拼接

当您需要在一句话中插入变量时，直接在纯文本中拼接大括号：

当前设备温度：{{ var.temperature }} ℃

系统底层的渲染引擎会自动提取变量的值，并拼接到字符串中。当变量被修改时，这段文字会极速无刷新重新渲染。

方式 B：通过交互动作修改变量 (数据写入)

如果您希望用户通过点击“按钮”或切换“多选卡”来改变变量的值，请在对应组件的 事件交互 (Events) 配置中，选择类似“设置变量 (Set Variable)” 的行为。 底层的 Kernel 会分发 setVariableValue 动作。一旦执行，整个页面上所有绑定了此变量的组件都会立即拿到最新值，触发联动。

---

4. 高级特性：持久化 URL 参数 (Persistent)

这是 ThingsVis 变量系统最强大的特性之一。

当您为一个变量勾选了 “持久化 (Persistent)” 属性后：

1. 自动上链：当变量的值发生改变时（比如用户在页面上选了不同的城市），浏览器的地址栏会无刷新地增加一个参数：?var_currentCity=北京。
2. 刷新不丢：当您按 F5 刷新页面，或者将该 URL 复制后发送给您的同事时，ThingsVis 的引擎在初始化阶段，会优先读取 URL 中的 var_ 前缀参数（并自动根据您定义的类型做数据转换）。
3. 状态共享：如果有同名的持久化参数，它的优先级高于变量原本设定的“默认值”。

利用这一特性，您可以极大地提升可视化大屏的分享体验，让分享出去的带参链接天然具备所见即所得的状态。