TopStack 文档

主题

数据绑定 ​

数据绑定是指图元样式、属性、动画等属性值与业务数据之间关联绑定。绑定关系建立之后，可实现数据驱动图形变化。可以在预览或者发布的页面中进行查看。

DANGER

所有数据绑定都是单向的，是由数据来驱动图形。

图元的大部分属性都可以跟进行数据绑定，点击相应属性的绑定按钮（“回形针”图标），弹出数据绑定对话框，进行绑定设置。 image.png颜色属性绑定

当给颜色属性绑定数值时，可以通过定义颜色区间来自动实现变量值与颜色值之间的转换关系。

给颜色属性绑定变量值，在使用数据转换脚本时，注意以下几点：

  1. 只能返回数值类型，不能返回颜色值。
  2. 脚本里返回的值是输入给颜色区间进行判断的。
  3. 脚本只需要对原始值进行二次处理就可以。

数据转换

如果绑定的变量值，与图元的属性类型不一致时，需要我们编写数据转换脚本，将变量值转换为图元属性需要的数据类型。

DANGER

不同的数据来源，数据转换脚本的入参有所区别，详见各自的数据转换脚本说明。

image.png

单测点值 ​

用于绑定单个测点实时值。 image.png 数据转换参数说明：

参数名说明
value测点值
quality数量质量：0 表示正常，1 表示离线
timestamp时间戳
data图元对象

例如，我们给一个图元的文本属性绑定测点值，希望不同的测点值显示不同的状态文本，比如运行、停止、故障。数据转换脚本如下： image.pngimage.png

多测点值 ​

用于绑定多个测点实时值。由于绑定了多个测点，最终的返回值需要用户编写“数据转换脚本”进行计算。 image.png

数据转换 ​

数据转换脚本入口参数说明：

参数名说明
value测点对象数组，依次对应每个测点，具体详见下面的“测点对象字段说明”。
data图元对象

测点对象字段说明：

字段名说明
deviceID设备标识
pointID测点标识
value测点值
quality数量质量：0 表示正常，1 表示离线
timestamp时间戳

示例： 返回两个测点值的平均值

javascript
var t1 = value[0].value
var t2 = value[1].value
if (t1 !== undefined && t2 !== undefined {
  return (t1 + t2) / 2
}
return 0

设备状态 ​

通过监听设备通讯状态来驱动图元属性变化。比如，驱动指示灯颜色变化、启用闪烁动画等。 image.png 数据转换脚本参数说明：

参数名说明
value设备状态值，1 表示在线，0 表示离线
timestamp时间戳
data图元对象

网关状态 ​

通过监听网关通讯状态来驱动图元属性变化。比如，驱动指示灯颜色变化、启用闪烁动画等。 image.png 数据转换脚本参数说明：

参数名说明
value设备状态值，1 表示在线，0 表示离线
timestamp时间戳
data图元对象

通道状态 ​

通过监听数据通道通讯状态来驱动图元属性变化。比如，驱动指示灯颜色变化、启用闪烁动画等。 image.png 数据转换脚本参数说明：

参数名说明
value设备状态值，1 表示在线，0 表示离线
timestamp时间戳
data图元对象

节点属性 ​

通过监听其它图元节点属性的变化，来驱动当前图元节点的属性变化。可用于图元节点属性值的相互绑定。完成节点属性绑定后，图形引擎将监听“绑定对象”的属性值，并传递给绑定目标，实现对目标对象属性赋值。 image.png

字段说明：

字段名称说明
绑定对象当前节点用于节点内的两个不同属性之间的绑定
标签绑定根据标签值查找绑定对象
父节点绑定父节点
吸附对象绑定吸附对象节点
标签名当选择标签绑定时，需要提供绑定对象节点的标签值
属性类型属性（property）监听绑定对象的 property 属性
属性（attr）监听绑定对象的 attr 属性
样式（style）监听绑定对象的 style 属性
属性名对应属性类型的属性名称

数据转换脚本参数说明：

参数名说明
value绑定的属性值
data图元对象

HTTP 绑定 ​

HTTP 常用于表格或图表的数据绑定，HTTP 返回的内容必须是 JSON 对象。

DANGER

使用 HTTP 绑定时，可能会遇到跨域问题，请确保 HTTP 接口允许跨域访问。

image.png

轮询间隔 ​

设置轮询间隔，可以实现每隔一段时间获取一次数据。

如果不设置轮询间隔，则只在页面初始化时获取一次数据。后续手动触发 HTTP 请求，可通过脚本方式实现。

脚本方式触发 HTTP 请求 ​

绑定 HTTP 时，可以设置一个【标识（ID）】，该 ID 在画面中要保证唯一性。

我们可以使用这个 ID 来手动触发 HTTP 请求，下面一是个示例：

javascript
// dm 为数据模型，此处假设已经获取到了数据模型
var db = dm.db() // 获取数据绑定对象
db.updateHTTP('此处为标识') // 触发 HTTP 请求

数据转换脚本 ​

数据转换脚本中的 value 参数代表 HTTP 请求返回的数据对象。value 对象包括两个固定的参数，如下所示：

参数名说明
valueHTTP 请求返回的数据对象
value.code表示 http 状态码；
value.data表示 http response body，是一个 json 对象；

请求参数 ​

http 请求基于 axios 库实现，所以请求参数本质上是 axios 的请求配置。 下面是一个示例： image.png示例

我们以获取天气信息为例，演示一下如果绑定天气接口数据。 在图纸中拖入一个文本，点击文本内容的绑定按钮，选择 HTTP 绑定。 image.png 在请求地址中输入：http://114.115.134.18:31020/api/third/weather/oneDay （测试用接口) 请求方法选择：GET 轮询间隔输入：5000 请求参数脚本：

javascript
return {
    params:{
        location:'dalian'
    },
    headers:{
        'Access-Control-Allow-Headers' : '*',
        'Content-Type' : 'application/json; charset=utf-8'
    }
}
// parms是这个请求携带的参数信息；headers是接口要求的请求头信息

数据转换脚本：

javascript
if (value.code != 200){
    return {
        name : '-',
        temperature : '-',
        text : '-'
    }
}
else {
    let res = value.data.results[0];
    return `城市：${res.location.name}，温度：${res.now.temperature}，空气质量：${res.now.text}`;
}

点击确定按钮，保存图纸，点击预览按钮显示预览效果。

数据集绑定 ​

与数据源管理中定义的数据集进行绑定，可以实现组态画面与第三方平台进行打通。 我们需要先在数据源管理界面创建数据集（请参考数据源管理相关教程），定义好的数据集可以用于组态画面中的数据绑定。 image.png

轮询间隔 ​

设置轮询间隔，可以实现数据集每隔一段时间自动更新。

如果不设置轮询间隔，则只在页面初始化时获取一次数据。后续如果要更新数据集，可通过脚本方式触发数据集更新。

脚本方式更新数据集 ​

绑定数据集时，可以设置一个【标识（ID）】，该 ID 在画面中要保证唯一性。

我们可以使用这个 ID 来手动触发数据集更新，下面一是个示例：

javascript
// dm 为数据模型，此处假设已经获取到了数据模型
var db = dm.db() // 获取数据绑定对象
db.updateDataset('此处为数据集标识') // 触发数据集更新

请求参数 ​

如果数据集需要提供查询参数，可以在请求参数中返回参数对象，如下图所示： image.png

数据转换脚本 ​

数据转换脚本中的 value 参数代表数据集返回的数据。根据数据集配置的不同，value 的格式有所不同，主要有两种格式。

格式1 ​

当使用【数据库数据集】 或 【带有分页的HTTP数据集】时，value 是一个数据对象，包括 total 和 rows 两个字段。

字段名说明
value.total总数量，分页查询时有效;
value.rows数据项数组，如果是分页查询，则对应当前页面的数据项数组；

示例： 返回当前数据集的所有行，可用于绑定到 table 组件。

数据转换脚本：

javascript
return value.rows
格式2 ​

当使用【不带分页的 HTTP 数据集】时，value 代表的是数据集中 JSON Path 指向的内容。

本地变量 ​

用于绑定本地变量，本地变量只有当前图纸内有效。

WARNING

在不同浏览器中打开同一图纸，本地变量不会共享

点击图纸空白处，在右侧属性栏中，可对本地变量进行编辑。

image-20250331093506540

全局变量 ​

用于绑定全局变量。我们可以通过定义 全局变量，实现在多个画面和浏览器终端中共享数据。