---
title: 数据接入与绑定
source: https://vjmap.com/guide/visual/data.html
---

---
group: 数据与交互
description: 给大屏接数据：连接数据面板、API 与 WebSocket 等接口、模拟数据、平台数据表，组件「数据」页签的字段绑定、筛选、联动和数据规则。
---

# 数据接入与绑定

大屏要「跟着数据变」，靠的是两步：先在**连接数据**面板里把数据源接进来，再在组件的**数据**页签里把字段绑定到组件上。[新手入门](./quickstart.html)用一段粘贴的 JSON 走过一遍最短的流程，本篇把每种数据源和绑定方式讲细。

先记住三层关系：

- **连接**：一个数据源，例如一个 API、一份 JSON、一张平台数据表。
- **表**：一个连接里可以有多张表（例如 Excel 的多个工作表）。
- **字段**：表里的列，有名称和类型（文本、数值、数组）。组件绑定的就是「某个连接 / 某张表 / 某个字段」。

字段改名、改类型都不影响已有的绑定；但删除并重建连接，绑定会失效，换数据源请用「替换数据源」。

## 连接数据面板

在编辑器顶栏点「数据 → 编辑数据...」，或按 `Ctrl+D`，打开「连接数据」面板。点左上角「添加新数据」，右侧列出所有数据源类型：

![连接数据面板与数据源类型](./images/data-types.webp)

1. **添加新数据**：新建一个数据源，右侧显示类型网格。
2. **替换数据源**：把一个连接整体换成另一个，同时保留组件绑定（见下文）。
3. **平台数据**：平台自带的数据表，在首页「数据管理」里建表录数，大屏实时订阅。
4. **接口**：API（HTTP 接口取数）、WebSocket（长连接推送）、Webhook（外部系统回调）、PostMessage（大屏被嵌入网页时由父页面传数）。
5. **模拟数据**：按规则造数，可定时刷新，适合没有后端时先把大屏做出来。
6. **文件**：Excel、CSV、JSON，上传文件或直接粘贴，数据不会变。

再往下是 MySQL、SqlServer、Pgsql、MongoDB 等数据库类型，目前标着「暂不支持」。数据在数据库里时，可以在自己的服务里包一层 HTTP 接口，再用 API 接入。

::: tip 拿不准用哪种
先用「模拟数据」或粘贴一段 JSON，把布局和绑定做对；真实接口准备好后，再用「替换数据源」整批换掉，组件不用重新绑定。
:::

### 查看与编辑数据源

建好的数据源出现在面板左侧，点其中的表可以在右侧检查数据：

![数据源树和数据明细](./images/data-tree.webp)

1. **连接**：一个数据源，点左侧三角展开或收起。
2. **编辑 / 删除**：鼠标移到连接上出现。编辑会重新打开该类型的配置对话框；删除后，绑定它的组件会取不到数据。
3. **表**：点一下，右侧显示这张表。
4. **数据明细 / 数据结构**：「数据明细」是只读的行预览（右上角显示总条数）；「数据结构」里可以改字段的名称和类型，例如把被当成文本的数字改成「数值」，图表才能按数值画。
5. **明细表格**：表头里每个字段名旁边标着它的类型。

## API：从 HTTP 接口取数

选「API」打开「连接 API」对话框，按顶部三步走：发送请求、数据解析、确认数据源。下图用官网的公开搜索接口做演示：

![连接 API 第一步：发送请求](./images/data-api-send.webp)

1. **三个步骤**：当前步骤高亮，完成的步骤变绿。
2. **请求方法**：GET、POST、PUT、DELETE。
3. **请求地址**：以 `http://` 或 `https://` 开头，地址里可以写 `{{变量名}}` 引用「变量」页签里的值。
4. **发送**：先发一次，确认接口能通。
5. **请求参数 / 认证 / 请求头 / 请求体 / 脚本 / 变量**：查询参数一行一个；认证支持 Basic、Bearer Token 等；脚本可以在请求前后做简单处理。
6. **响应**：右上角显示状态码（图中为 200），下面是返回的原始内容。

点「下一步」进入数据解析。接口返回的往往是一层层嵌套的对象，组件需要的是里面那个数组：

![连接 API 第二步：数据解析](./images/data-api-parse.webp)

1. **响应结果**：上一步拿到的数据，用来对照填路径。
2. **使用 JSONPath 解析**：结构特殊时勾选，可以逐个字段指定取值路径，或一次解析出多张表。
3. **数据路径**：填到数组所在的位置，用点分隔，例如 `data.list`、`data.records[0]`；图中填的是 `groups`。留空会自动识别 `data`、`rows`、`list` 等常见写法。填好点「解析」。
4. **解析结果**：显示几个字段、几行，并预览表格。

第三步填「连接名称」，核对字段结构和数据明细，点「确定」即可。

::: warning 跨域
API 是在浏览器里直接请求的，接口服务要允许跨域（CORS），否则发送会失败。不能改接口时，可以把数据导成文件，或改用平台数据。
:::

### WebSocket、Webhook、PostMessage

这三种都是「对方把数据推过来」，配置对话框长得差不多：

- **WebSocket**：选协议（Socket.io 或原生 WebSocket）和模式，填 `ws://` / `wss://` 地址。
- **Webhook**：平台自动生成一个回调地址，复制给外部系统，对方往这个地址 POST 数据。
- **PostMessage**：平台生成一个「链接 Id」，大屏被嵌入到你的网页后，父页面发消息时带上同一个 Id，大屏才会接收。

三者都要在下方给每张表填字段映射：「字段名」是大屏里显示的名字，「字段类型」选数字、字符串或数组，「数据字段名」填推送报文里的键名。例如服务端推来 `{"ts": "10:00", "kw": 820}`，就建「时间 → ts」「功率 → kw」两个字段。填好后可以点「获取数据预览」（PostMessage 是「监听预览」）核对实际报文。

## 模拟数据：让大屏先动起来

没有后端时，用模拟数据按规则造数，设置刷新间隔后，预览和发布后的大屏会定时换一批数，柱子、数字跟着跳，适合做演示和实时监控的样子：

![模拟数据：字段规则与数据预览](./images/data-mock.webp)

1. **数据源名称**：图中叫「设备监测」。
2. **行数与刷新间隔**：生成几行；每隔几秒重新生成一次，`0` 表示不自动刷新（仍可被「刷新数据」或交互动作触发）。
3. **字段规则**：点「添加字段」逐个添加，每个字段选一种生成规则。图中设备号用「递增序列」从 1001 开始，温度用「正弦波动」（基线 60、振幅 15、周期 20 秒），负载用「整数(区间)」20～95，状态用「枚举(随机)」从「正常,正常,正常,告警」里随机取，告警出现的概率就是四分之一。
4. **数据预览**：按当前时间生成一帧，改规则时实时变化。

生成规则一共九种：整数(区间)、小数(区间)、正弦波动、随机游走、递增序列、枚举(随机)、布尔、固定值、当前时间。

::: tip 编辑态不跳数
编辑器画布上显示的是一帧快照，刷新间隔在「预览」和发布后的大屏里才生效。
:::

## 平台数据：自带的数据表

数据要由人维护（值班表、设备台账、公告、手填指标），又希望改了马上在大屏上生效时，用平台数据。先在首页左侧点「数据管理」建表：

![新建数据表](./images/data-dm-new.webp)

1. **表名称**：必填，可以写中文；下面的「描述」选填。
2. **公开读取**：默认打开，发布后的大屏不用登录也能读取和实时订阅。关掉后表变成私有，匿名访问的大屏读不到数据。
3. **字段定义**：每行一个字段，填显示名、选类型、设是否必填。类型有文本、数值、布尔、日期、单选、关联（关联另一张表的记录）、JSON。
4. **添加字段**：再加一行。
5. **创建数据表**：保存。字段类型创建后不能改，显示名可以随时改。

建好后录入记录：

![数据管理：表列表与记录](./images/data-dm-table.webp)

1. **新建数据表**：再建一张表。
2. **表列表**：自己建的表，右侧数字是记录数。
3. **公开读取与实时状态**：表名旁边的标签和实时同步指示。
4. **记录**：点表头排序，每行右侧可以编辑、删除。右上角有「新增记录」「表结构」、刷新和更多（删除数据表）。

回到编辑器，`Ctrl+D` →「添加新数据」→「平台数据」，勾选要用的表：

![把数据表接入大屏](./images/data-platform.webp)

1. **连接名称**：图中改成了「值班表」。
2. **实时订阅、行数上限、排序**：实时订阅默认打开，后台一改数据，大屏立即刷新；行数上限默认 500。
3. **我的数据表**：勾选要接入的表，一个连接可以勾多张。
4. **预览**：点表名可以先看字段和数据。

确定后，表的字段（另外附带 ID 和创建时间）就能像其它数据源一样绑定到组件。

## 在组件上绑定字段

选中组件，右侧属性面板切到「数据」页签。下图是一个柱状图：

![组件的「数据」页签](./images/data-tab.webp)

1. **字段映射**：组件需要哪些字段，就列出几个槽。柱状图有「类目轴」和「数值」：上面的下拉选数据源，下面的下拉选字段。数值可以选多个字段，每个字段一条系列。
2. **数据来源**：「项目数据源」用连接数据面板里的数据；「组件自有数据」是组件内置的一份小表格，可以直接改；「演示数据」是组件自带的示例。
3. **数据源树**：列出所有连接和表，点表名切换。
4. **字段清单**：勾选字段，平台会按组件的需要自动放进字段映射里，比逐个下拉更快。
5. **数据预览**：当前表的前几行，方便核对。

表格类组件的字段映射是「数据字段」和「关键字段」：数据字段决定显示哪几列（可多选），关键字段用来标识每一行，一般不用设。

::: warning 字段清单会勾错槽时
字段清单按顺序自动映射。表格类组件勾选时，有时会把字段放进「关键字段」；这时直接在上面的「数据字段」下拉里多选需要的列，并清空关键字段。
:::

### 刷新数据

顶栏「数据」菜单里的「刷新数据」（`Ctrl+F5`）让所有联网数据源立即重新取数。也可以在[事件交互](./events.html)里用「刷新数据」动作，点按钮时刷新；「数据交互」分类里的「定时器与接口示例」演示了定时调接口刷新的做法。

### 替换数据源

在连接数据面板点「替换数据源」：上面选「源数据源（被替换）」和「目标数据源（替换为）」的连接与表，下面的「字段映射」逐个对应字段，点「确认替换」后，原来绑定旧字段的组件全部改绑到新字段。常用在「先用模拟数据搭好，再换成真实接口」。

## 筛选、联动与选中

同一份数据，可以只让某个组件看其中一部分，也可以让组件之间互相影响。这些都在「数据」页签的中段：

![组件筛选与数据过滤](./images/data-filter.webp)

1. **筛选设置（联动）**：「筛选其他组件」打开后，点这个组件的数据项（例如一根柱子）会过滤别的组件；「响应组件筛选」打开后，这个组件会被别人过滤，下面再选「选择字段」和「选择联动字段」，告诉平台用哪一列去匹配。「高级设置」可以用黑名单或白名单限定联动哪些组件。
2. **选中同步**：「选中其他组件」把当前选中项传出去，「接收选中」的组件据此高亮、定位对应的行（表格要指定「选中字段」）。它只传「选中了谁」，不会过滤数据。
3. **数据过滤**：打开开关，只对本组件生效，不影响数据源和其它组件。
4. **筛选条件**：「数据行」只取第 N 行；「数据行段」从某行起取 N 行；「直接判断」就地写一个「字段 + 条件 + 值」；「条件构建器」就地写一组条件；「数据规则」引用下文的工程级规则。

联动的效果要在「预览」里看。下图来自首页「数据交互」分类里的「数据联动示例」：饼图打开了「筛选其他组件」，柱状图和页面打开了「响应组件筛选」：

![点击饼图的杭州，柱状图只剩杭州](./images/data-linkage.webp)

1. **点击饼图的「杭州」**：作为联动的发起方。
2. **柱状图随之过滤**：只显示杭州的男女人均收入；再点一次取消，恢复全部。

::: tip 联动不生效时
发起方和接收方要绑定同名的字段（例如都有「城市」）；接收方所在的页面也要打开「响应组件筛选」（点画布空白处选中页面，在页面的「数据」页签里设置）。编辑态点击只会选中组件，联动要在预览里试。
:::

## 数据规则

数据规则是整个工程共用的「条件」，例如「温度大于 70 并且状态等于告警」。建一次，可以在数据过滤、[多状态](./events.html)、条件样式、事件触发等地方反复引用，改一处处处生效。在顶栏「数据 → 数据规则...」打开：

![数据规则：组内并且，组间或者](./images/data-rules.webp)

1. **添加条件**：新建一条规则，左侧列表可以复制、删除。
2. **条件名称**：给规则起个好认的名字，引用时按名字选。
3. **新建分组 / 新建条件**：「新建条件」在当前组里加一行，「新建分组」另起一组。
4. **组内「并且」**：同一组的几行都满足才算满足。每行依次选数据表（或项目参数）、字段、判断方式（第一条、最后一条、任一条、每一条或自定义第几条数据）、条件（等于、大于、包含、为空等）和值。
5. **组间「或者」**：任何一组满足就算满足。图中的规则读作：温度大于 70 且状态等于告警，或者负载大于 90。

::: warning 选表要选到表这一级
「数据表/项目参数」是一个树形下拉，要先点连接左边的三角展开，再选里面的表。只选到连接时，字段下拉里只有「行号」「倒序行号」「数据条数」这几个位置字段。
:::

## 发布后的数据

- 联网的数据源（API、推送类、平台数据）在发布后的大屏里照常取数，接口要能被观看者的浏览器访问到。
- 平台数据表要保持「公开读取」，匿名访问的大屏才能读到。
- 要交付离线环境时，「项目部署 → 导出部署文件」里勾选「将动态数据源转换为静态」，联网数据会被冻结成一份静态数据打进包里，见[保存、发布与嵌入](./publish.html)。

## 下一步

- 数据接好后，用[事件交互与多状态](./events.html)让点击、悬停驱动页面变化。
- 地图、三维、组态组件的数据绑定，见[二维地图](./map.html)、[三维场景](./scene3d.html)、[组态](./scada.html)。