1. 概述
适用场景：安装了「FineVis数据可视化」插件的用户，可参考本文了解 FineVis 模板的相关功能。
1.1 版本
| FineReport版本 | 插件版本 | 功能变更 |
|---|---|---|
| 11.5.1 | V4.1.0 | 「数据来源」新增 支持WebSocket 「数据来源>数据集」新增支持设置刷新频率 |
1.2 功能介绍
三维组件数据来源可分为「数据集」数据和「WebSocket」数据：
1）数据集：支持选择本地数据集或服务器数据集。
2）WebSocket：通过配置 URL，可实现实时数据接入。
2. 数据集
数据来源选择「数据集」时，支持选择本地数据集或系统中配置的服务器数据集。
V4.1.0 版本支持设置刷新频率，进行组件内部数据刷新。
3. WebSocket
使用 WebSocket 需购买「FVS三维组件-场景孪生」功能点，未购买时该选项灰化，提示：FVS三维组件-场景孪生未注册，无法添加，请联系管理员注册后再添加。通过 WebSocket 获取数据，可以满足数据图层展示模型数据时标签的高频刷新和实时更新需求，提升数据响应效率与使用体验，更好地支持实时监控、动态展示等关键业务场景。
三维自定义组件的「数据图层」、「模型实时运动」、「更新参数模型」和「模型数据应用事件」支持配置 WebSocket 。
注：三维城市场景和 Unity 组件图层的数据来源暂不支持选择 WebSocket。
3.1 数据格式要求
3.1.1 增量数据
「数据图层」、「更新参数模型」中配置的 WebSocket 为增量数据，需明确标记数据为新增、更新或删除。
数据格式要求为： { id: websocket配置的id; data: { opType: "upsert"/ "delete", 其他数据键值对 }[]; }[]
注1：数据需要转化为 JSON 字符串。
注2：传入数据为非数组格式时，报错：数据格式错误，要求为数组类型，当前传入数据为非数组类型。
数据格式具体说明如下表所示：
| 字段 | 说明 |
|---|---|
| id | 用于标识该组数据的唯一字符串 |
| data | 为数组类型，每个元素代表一次操作，包含操作类型（opType）及字段 opType 字段：
|
3.1.2 全量数据
「数据图层-初始化」、「模型实时运动」和「模型数据应用事件」中配置的 WebSocket 为全量数据。
数据格式为：{ id: websocket配置的id; data: { 数据键值对; }[]; }[]
注：WebSocket 初始化时，FVS 客户端会推送带有 ID 的消息，服务端接收到该消息后视为连接建立成功，即可开始推送全量数据。
3.2 异常场景
| 场景 | 报错信息 |
|---|---|
| 传入数据为非数组格式时 | 数据格式错误，要求为数组类型，当前传入数据为非数组类型 |
| 传入数据某项缺少 id 时 | 数据格式错误，缺少传入 id |
| 传入数据某项缺少 data 时 | “id”数据格式错误，缺少传入 data 数据 |
| 传入数据某项 data 为非数组格式时 | “id”数据格式错误，data 要求为数组类型，当前传入 data 为非数组类型 |
传入数据缺少字段 增量数据缺少 opType | “图层名称”数据格式错误，跳过当前数据，期望数据格式:{对应 配置的key}，实际数据格式:{对应配置的key} |
| 数据图层初始化中配置 WebSocket 超时 （60s） | “图层名称”等待接收全量数据超时 |
4. 注意事项
1）客户端初次建立 WebSocket 连接/复用连接后，会向服务端推送一条带有 ID 的数据以标识连接建立成功。
2）WebSocket 支持连接复用，同一 URL 仅建立一个连接。
3）当多个功能复用同一 WebSocket 连接时，可通过 ID 区分各功能接收的数据，实现数据按需分发。
4）配置了全量初始化场景功能时，增量数据处理规则如下：
接收到初始化数据前的增量数据丢弃
场景加载完成前、接收到初始化数据后的增量数据正常执行更新
5）当 WebSocket 连接异常断开时，系统支持自动重连机制，最多可尝试重连 5 次。
若连接关闭时未携带状态码 1000，则视为异常断连，系统将触发自动重连并输出报错。
若连接关闭时携带状态码 1000，则视为正常关闭连接，系统不再进行重连。
上一篇：三维场景组件数据图层
