3. 仪表板基础概念：仪表板定义、仪表板状态、仪表板别名、仪表板权限模型

在深入 ThingsBoard 仪表板设计之前，必须理解四个核心基础概念：仪表板定义、仪表板状态、仪表板别名和仪表板权限模型。它们是构建任何复杂仪表板的基石，决定了数据如何被组织、导航、引用以及谁可以访问。

3.1 仪表板定义 (Dashboard Definition)

仪表板定义是 ThingsBoard 中一个仪表板的完整 JSON 描述。它包含了仪表板的所有配置信息，从布局、组件到数据源绑定，全部以结构化数据的形式存储。

仪表板定义的主要组成部分：

一个简化的仪表板定义 JSON 结构示例：

{
  "title": "温度监控仪表板",
  "configuration": {
    "widgets": [
      {
        "id": "w1",
        "type": "timeseries",
        "config": {
          "datasources": [
            {
              "type": "entity",
              "name": "温度传感器",
              "aliasName": "temp_sensor_alias"
            }
          ]
        }
      }
    ],
    "layouts": {
      "main": {
        "widgets": { "w1": { "sizeX": 6, "sizeY": 4, "col": 0, "row": 0 } }
      }
    },
    "states": { "default": { "name": "主视图" } },
    "aliases": { "temp_sensor_alias": { ... } }
  },
  "assignedCustomers": []
}

3.2 仪表板状态 (Dashboard State)

仪表板状态是 ThingsBoard 实现多页面导航和交互式钻取的核心机制。每个状态代表仪表板中的一个独立视图，可以拥有自己的一组小部件和布局。

状态的关键属性：

• 状态 ID：状态的唯一标识符（如 default、device_detail）。
• 名称：状态的显示名称，用于面包屑导航或状态切换器。
• 根状态：仪表板加载时默认显示的状态，通常命名为 default。
• 父状态：允许定义状态层级，实现“返回上一级”功能。
• 布局：每个状态可以拥有独立的布局（如 main、right、bottom），控制小部件的位置。

状态之间的典型关系：

3.3 仪表板别名 (Dashboard Alias)

仪表板别名是 ThingsBoard 中一个强大的抽象层。它允许小部件的数据源不直接绑定到具体的设备或资产实体，而是绑定到一个逻辑名称（别名）。别名在运行时解析为实际的实体 ID。

别名的类型与解析方式：

别名在仪表板定义中的位置：

{
  "configuration": {
    "aliases": {
      "current_device": {
        "alias": "当前选中设备",
        "filter": {
          "type": "entity_from_dashboard_state",
          "entityType": "DEVICE",
          "stateEntityParamName": "selectedDeviceId"
        },
        "resolveMultiple": false
      },
      "all_temp_sensors": {
        "alias": "所有温度传感器",
        "filter": {
          "type": "entity_name",
          "entityType": "DEVICE",
          "namePattern": "temp_*"
        },
        "resolveMultiple": true
      }
    }
  }
}

3.4 仪表板权限模型 (Dashboard Permission Model)

ThingsBoard 的权限模型基于角色和范围，控制谁可以查看、编辑或管理仪表板。理解权限模型对于多租户部署和团队协作至关重要。

权限模型的核心角色与能力：

仪表板权限的配置方式：

• 仪表板分配：租户管理员可以将仪表板分配给一个或多个客户。分配后，该客户的所有用户都能看到该仪表板。
• 编辑权限：在分配仪表板时，可以勾选“允许客户用户编辑仪表板”。启用后，客户用户可以在自己的范围内修改小部件配置（但无法更改别名或状态结构）。
• 公开访问：将仪表板标记为“公开”后，任何知道链接的人（无需登录）都可以查看。适用于大屏展示或对外报告。
• 移动端权限：可以单独控制仪表板是否在移动端应用上可见。

权限模型的工作流程：