项目交付——数据对接入门

1 前言

本文旨在于帮助快速掌握项目交付中数据对接相关技巧，属于经验分享，非 EasyV 产品的全面使用教程，更多内容见帮助中心其他教程/文档。

文内图片生成于 EasyV 4.8.1 版本，因版本迭代原因可能与所用产品界面不同，但基本功能变化不大，本文仍可作为参考使用。

2 面向人员与对应场景

• 数据开发工程师

• 所需能力：掌握数据库查询语句相关知识
• 适应场景：简单大屏项目

• 前端开发工程师

• 所需能力：掌握 JavaScript 基础知识
• 适应场景：所有大屏项目

3 交付流程与人员配置

根据大屏场景的不同，所需的人员配置和流程也有所不同。

• 简单项目

• 大屏场景：只有数据库作为接入数据源，并且无复杂交互。
• 人员配置：数据开发工程师
• 推荐实施人员：数据开发工程师
• 实施流程：数据开发工程师根据大屏的业务逻辑，直接在大屏的对应组件中写 SQL 语句进行数据接入。

• 一般项目

• 大屏场景：主要以 API 接口作为接入数据源
• 人员配置：前端开发工程师
• 推荐实施人员：前端开发工程师
• 实施流程：前端开发工程师拿到 API 接口文档后，在大屏中配置 API 接口进行数据接入。

• 复杂项目

• 大屏场景：需要接入多种数据源，页面中包含较为复杂的交互。
• 人员配置：数据开发工程师、前端开发工程师
• 推荐实施人员：前端开发工程师
• 实施流程：由数据开发工程师提供 SQL 语句，前端开发工程师拿到 API 接口文档和 SQL 语句后进行数据接入与交互配置。

4 功能说明

4.1 数据源

1. 数据源主要为 4 大类，分别为静态数据、CSV 文件、API 接口和数据库。
2. 每种数据源的配置界面都不同，其中 API 接口和数据库参数配置区域内可以使用回调参数。

API 接口

API 接口有两种请求路径，一种是前端发起请求，一种是后端发起请求，可以根据接口和网络环境的不同，灵活调整请求方式。

• 前端发起请求。

• 配置方式：不勾选【后端发起请求】。
• 请求源头：当前显示页面所在的浏览器环境。
• 跨域问题：若接口的协议、host 或端口和大屏地址不同，可能会存在跨域问题。如果接口在开发时配置了跨域限制，则无法成功请求到数据，需要接口提供方设置允许跨域。

• 后端发起请求。

• 配置方式：勾选【后端发起请求】。
• 请求源头：大屏部署的服务器环境。
• 跨域问题：从服务器端直接发起请求，不会存在跨域问题。

4.2 字段映射

字段列表示组件所需的字段名称，映射列表示数据中将要匹配的字段。

在项目中，接入的数据大部分情况下和组件并不匹配，在数据结构匹配，仅字段不匹配时，通过字段映射可以快速实现字段的匹配。

例：获取到的结果中字段为 user，组件中所需的字段为 text，将映射列中的 text 改为 user 即可完成映射。

如果数据结构不相同，则需要使用数据过滤器进行处理。

4.3 数据过滤器

通过数据源获取数据后，如果数据不符合组件所需的数据格式，可以通过数据过滤器处理成符合需求的数据格式。

数据过滤器本质上是一个函数，包含固定参数 data 和 callbackArgs，data 为通过数据源获取的数据/前一个数据过滤器的返回值，callbackArgs 包含数据过滤器接收的回调参数（下面的回调参数中详细说明），return 所返回的值将向下传递。

数据源为静态数据时，最好不要在数据过滤器中修改 data 的内容，修改操作等于手动修改了静态数据，可能会导致已有的静态数据丢失或其他异常。

每个组件都可以添加多个数据过滤器，处理顺序为从上向下，上一个数据过滤器的返回值将作为下一个数据过滤器的 data 参数，最后一个数据过滤器的返回值即为组件展示所用的数据。

点击测试按钮，弹出的窗口可以观察到数据处理的过程，原始数据中包含 s 值为 "系列二" 的数据，通过数据过滤器的处理后，结果中不再有 s 值为 "系列二"的数据。

再次过滤后，数据中将只剩下 y 值大于 200 的数据。

PS1：数据过滤器中不仅可以返回 JSON 格式数据，同样也可以返回字符串、数值、对象等多种类型的结果，一般在数据容器中这么使用，用于回调参数的中间处理。

4.4 自动更新

接入的 CSV/API 接口/数据库 数据可能会是动态更新的，需要定期更新，可以使用自动更新功能实现动态更新的效果。

开启自动更新后，平台会根据配置的时间间隔，定期发起请求获取最新的数据，组件也会根据最新的数据进行对应展示。

4.5 回调参数

4.5.1 说明

回调参数可以理解为一个全局变量，回调名称即为变量名，回调值即为变量值，用于组件之间数据的交互，使用回调参数的地方在该回调参数的数值发生变化时，会根据新的值重新进行计算或发起请求。

4.5.2 特性

1. 编辑页面不生效，仅在预览页面生效
2. 回调值发生变化后触发后续链路联动

1. 数据过滤器绑定的回调参数值变化后，数据过滤器中的代码会重新执行一遍。
2. API 接口和 SQL 语句依赖的回调参数值变化后，对应的 API 接口会带着新的参数重新请求一次，SQL 语句也会重新执行一次。

4.5.3 来源

1. url 携带

https://easyv.dtstack.com/workspace/bigscreen/191865#adcode=110000&id=1234

使用方式为，在 url 地址尾部添加 #，其后使用[回调名称]=[回调值]的方式添加，多个键值对之间使用 & 符号连接
adcode 和 id 即为回调参数名
110000 和 1234 为对应的值

2. 组件配置

每个组件的配置和触发方式不完全相同，大部分位于【交互】-【回调参数】中，以具体组件为准。

4.5.4 使用

1. 在数据过滤器中

2. 在 SQL 语句中

SQL 语句中，[:]+[回调参数名]作为通配符，例 :type，预览时通配符将会被替换为对应的回调值处理。

3. 在 API 接口中（请求头、路径、参数、请求体）

API 接口中，同样使用 [:]+[回调参数名]作为通配符使用，例：:token，预览时通配符将会被替换为对应的回调值处理。

4.6 数据容器

一般组件的回调需要由特定的交互触发，如鼠标点击、轮播切换等，并且需要配置所要回调的字段值，最终的回调值会是数据中的某一项，不会将数据全部回调出来。

和一般组件相比，数据容器的回调参数有所不同：

1. 每次数据更新后触发，数据容器通过 CSV 文件/API 接口/数据库 接入的数据，每次数据更新都会触发回调，将新的数据向后传递。
2. 全额回调所有结果，可以将获取的所有数据全额回调出来，对象/数组/字符串/数值等 JavaScript 支持的格式都可以回调出来。

基于数据容器回调的特殊性，配合数据过滤器可以实现数据聚合、数据分发、数据中转等多种复杂场景的应用。

5 数据接入

5.1 规范命名

良好的命名能够更清晰地了解页面的结构/数据过滤器的用途/回调参数的意义/条件的规则等。

项目周期长、项目内容多、参与人员多等状况都会使大屏逻辑的理解变得更难，良好的命名规则可以使大屏结构与逻辑更清晰，减少反复查找、推测页面逻辑的时间消耗，数据接入和后续维护阶段都会更加方便，推荐尽量使用有意义的命名。

• 组件/组的名称 —— 描述组件/组的内容。

• 基本折线图 -> 销售金额趋势图
• 分组 -> 左侧内容/右侧内容

• 数据过滤器名称 —— 简要描述数据过滤器的作用。

• 返回当前时间

• 回调参数名称 —— 驼峰/下划线/其他命名皆可，尽量使用和回调参数作用相一致的描述性名称。

• 当前时间

• 告警类型

• 条件名称 —— 简要描述条件的规则。

• 包含有效数据

5.2 注意事项

以下事项并非必须遵守，仅是相对较优的处理方式，基于人员配备、设备状况、项目周期等情况会有不同的考量，具体问题具体分析。

1. 避免重复请求，同一个接口的数据需要在多个地方使用时，推荐使用数据容器作为存储，然后分发给对应组件。
2. 控制展示数量，一般图表类组件避免一次性接入大量级（万条以上）数据，过多数据的展示效果并不友好，也会导致大屏卡顿。
3. 合理设置更新时间，单项数据类并且变动很频繁可以适当高频率（每秒）更新，较大量数据（千条以上）尽量低频率（每分钟/每小时）更新。

6 小技巧

6.1 数据过滤器共用

因为数据过滤器本身是一个执行函数，只基于入参返回结果，而入参中的 data 值来源于数据源获取的数据/前一个数据过滤器的返回值，所以对于数据结构相同、处理逻辑相同的需求，可以使用同一个数据过滤器处理，不需要每个组件都写一个新的数据过滤器。

后续需要修改过滤器时，就不用每个数据过滤器都修改一遍，只改共同使用的这个过滤器即可。

应用场景：接口数据格式化、数据有效性过滤

6.2 静态数据做标记

基于数据过滤器 data 参数来源于数据源获取的数据/前一个数据过滤器的返回值的特性，静态数据中的数据可以被对应组件的首个数据过滤器获取到。

当多个组件所需的数据过滤器逻辑相同，仅有微小地方的处理有不同时，可以在对应多个组件的静态数据中以数据的形式进行标记，在数据过滤器中基于这些数据的不同，做针对性处理。

应用场景：数据分发

7 数据过滤器与回调管理

8 调试方法

当在数据过滤器/ API 接口/ SQL 语句中使用了回调参数时，因为回调参数在编辑页不生效的特性，无法直观地查看相应的数据结果，需要借助浏览器的开发者工具来辅助调试。

开发者工具通过按键 F12 或下图的方式打开。

8.1 查看 Console 结果。

在数据过滤器中写入 log 代码逻辑

在控制台中查看结果

8.2 查看 Network 请求详情。

8.2.1 API 接口未勾选后端发起请求

Network 中请求的 name 为接口的路径+参数，查找时需要根据接口的路径+参数过滤。

通过 Headers 模块查看实际传参，见上图。

通过 Preview 模块查看结果，见上图。

8.2.2 API 接口勾选后端发起请求/ SQL 语句中包含回调参数

Network 中请求的 name 为get?componentId+[组件id]，查找时需要根据组件的 id 过滤。

9 应用示例

文内仅为示例的大屏截图，示例的大屏文件包见文末附件。

9.1 数据分发

9.2 数据分发进阶

9.3 数据聚合

9.4 token 认证

9.5 复选框交互

9.6 时间回调

9.7 无数据情况展示

9.8 url 回调控制

9.9 搜索功能

9.10 默认回调参数

9.11 表格排序

9.12 回调跳转

10 附件

10.1 大屏示例包

百度网盘链接:https://pan.baidu.com/s/1Lsntna81p6bqWOwm1rglBQ 密码:m4t5