主题
数据源
大屏数据有两种来源：静态数据（写在组件里）和 动态数据源（HTTP / WebSocket）。二者可并存：绑定了数据源时，预览以接口数据为准。
数据源库（Phase 1）
侧栏 数据源库（需 datasource:list 权限）可集中管理 REST / WebSocket / 课堂评价 API 数据源，供多个大屏复用。
| 操作 | 权限 |
|---|---|
| 进入列表 | datasource:list |
| 查看详情 / 测试 | datasource:read |
| 新建 | datasource:create |
| 编辑 | datasource:update |
| 删除 | datasource:delete（有组件引用时不可删） |
编辑器内引用：数据源面板 → 从库选择，或新建时勾选 同时保存到数据源库。绑定方式与屏内数据源相同（组件「数据」→ 选数据源 → dataPath）。
与屏内数据源区别
- 屏内数据源：挂在大屏下，随大屏权限管理；可设 仅本人 / 可编辑大屏间共享。
- 库内数据源：在 数据源库 维护；可设 私有 / 团队 / 共享（授权指定用户、团队或大屏）；被引用后可在已授权大屏的编辑器里选用。
共享与可见范围
在数据源库编辑时可配置 可见范围：
| 范围 | 说明 |
|---|---|
| 私有 | 仅创建者（及平台管理员）维护 |
| 团队 | 归属团队内可见、可选用 |
| 共享 | 可额外授权指定用户、团队或 大屏（下拉选择，无需手填 ID） |
编辑器内新建数据源时，仍可选择 仅本人 或 可编辑大屏间共享（写入该大屏下的屏内源）。
打开数据源管理
编辑器工具栏 更多 → 数据源，或右栏 数据源 Tab。
手把手创建 REST 数据源
以「柱状图显示接口里的列表」为例：
- 编辑器 → 顶栏 更多 ▼ → 数据源（或右侧 Tab 数据源）。
- 点 添加 → 选 HTTP。
- 名称：随便起，如「销售接口」。
- URL：粘贴完整地址（
http://或https://）。 - 方法：多数用 GET；POST 接口见 POST 接口手把手。
- 点 保存。
- 在列表里点刚建的数据源 → 展开 调试。
- 点 发送请求。
- 下面出现 JSON：
- 成功：树形结构，单击 你要的数组节点，会自动填 dataPath
- 失败：看错误信息（404、401、超时等）
- 选中画布上的 柱状图 → 右侧 数据 → 绑定数据源 → 选「销售接口」。
- dataPath 与调试里一致（如
data.list）。 - 若图表字段名和接口不一致，在 系列/映射 里改字段名。
- 保存 → 预览，看是否有柱子。
还是空？ 先确认调试里 发送请求 有数据，再确认没只填示例数据而忘了绑定。
手把手创建 WebSocket 数据源
适合：实时推送、监控大屏、秒级刷新。
1. 新建 WS 数据源
- 编辑器 → 更多 → 数据源 或右栏 数据源 Tab。
- 点 添加（或展开添加表单）。
- 类型 选 WebSocket（不要选 HTTP）。
- 名称：如「实时产量」。
- WebSocket URL：填
ws://...或wss://...（生产环境建议 wss）。 - 数据路径（可选）：若消息是
{ "data": { "value": 1 } }，填data或data.value；整包就是数组可留空。 - 点 保存 / 确定 创建。
2. 看连接状态
创建后列表里该数据源下方有 WebSocket 调试区：
| 状态文字 | 含义 |
|---|---|
| 连接中 | 正在握手 |
| 已连接 | 正常，可收消息 |
| 已断开 / 失败 | 地址错、服务未开、或被防火墙拦 |
失败时点 重新连接 再试。
3. 看消息日志
- 消息日志 显示最近约 20 条 收/发记录。
- 接收：服务端推来的内容
- 发送：你在下面输入框发的测试消息
若一直 暂无消息，说明还没连上或服务端没推送。
4. 发测试消息（可选）
- 底部输入框输入文本或 JSON。
- 点 发送 或回车。
- 日志里应出现 发送 一行。
只有 已连接 时发送按钮才可用。
5. 绑定到组件
- 选中 数字翻牌 / 仪表盘 / 列表 等组件。
- 右侧 数据 → 选刚建的 WebSocket 数据源。
- dataPath 与 WS 配置一致或更细（指向具体字段）。
- 保存 → 预览 看是否随推送变化。
6. 和 REST 的区别（必看）
| REST | WebSocket | |
|---|---|---|
| 数据怎么来 | 定时或手动 请求 | 服务端 推送 |
| 公开预览 | 经平台 代理 | 访客浏览器 直连 WS |
| 跨域 | 平台帮忙 | 需 WS 服务允许外网访问 |
本地预览有数、公开页没数？ 常见原因是 WS 地址是内网 ws://192.168...，外人访问不到。需运维提供公网 wss 地址。
新建数据源
点击 添加，选择类型：
HTTP（REST）
| 字段 | 说明 |
|---|---|
| 名称 | 便于识别的别名 |
| URL | 接口地址 |
| 方法 | GET / POST |
| 刷新间隔 | 毫秒；0 表示不自动刷新 |
关于 Query 参数
新建表单里 没有 单独的 Params 输入框。若数据源配置里 已带有 params 定义（常见于 导入 JSON 备份 或同事预先配好），保存后列表展开会出现 参数配置，可填运行时取值并点 使用参数刷新。
保存后出现在列表，可 手动拉取 更新缓存。
WebSocket
| 字段 | 说明 |
|---|---|
| WebSocket URL | ws:// 或 wss:// |
| 数据路径 | 可选，如 data.list；留空则取完整消息 |
创建后自动尝试连接；编辑时可看 连接状态 与 消息日志，支持 重连、手动发送 测试消息。
在线测试与调试（HTTP）
编辑 REST 数据源时展开 调试面板：
- 点 发送请求 测试连通性
- 在 响应预览 JSON 树中点击节点，自动填入 dataPath
- 查看 推荐路径 快捷标签
- 路径下方 预览值；格式不对会有 警告
绑定组件前建议先在此确认接口返回结构与路径正确。
绑定到组件
- 选中 图表、列表、表格 等数据类组件
- 右栏 数据源 Tab（或组件「数据」段内的绑定区）
- 选择数据源
- 填写 dataPath（如
data.items） - 列表 / 表格 类配置 列映射：接口字段 → 列字段
- （REST）可选开启 自动刷新：仅 预览 / 发布页 生效，编辑器内不轮询；间隔建议 ≥ 2 秒
- 保存大屏（绑定含自动刷新开关会写入项目 JSON）
列映射示例
接口返回：
json
{ "rows": [{ "n": "华东", "v": 120 }] }表格列定义为 name、value 时，列映射可设：name ← n，value ← v。
POST 接口手把手
适合：接口要求 POST、或参数写在 URL 查询串里（?id=1 可直接写在 URL 里）。
步骤
- 更多 → 数据源 → 添加 → 类型 HTTP。
- URL：完整地址（可含
?key=value）。 - 方法 选 POST（不要选 GET）。
- 展开下方 调试 → 发送请求，确认返回 JSON 与 HTTP 状态正常。
- 在 JSON 树里 单击 目标数组节点，记下 dataPath。
- 创建 保存数据源。
- 选中图表/表格 → 数据 → 绑定数据源 → 选刚建的源 → 填 dataPath → 保存绑定。
- 保存大屏 → 预览 验证。
说明
| 情况 | 建议 |
|---|---|
参数在 URL 上（?page=1） | 直接写进 URL 字段 |
| 需要 JSON Body | 当前编辑器 不提供 Body 编辑框；可请运维把参数改到 URL，或由技术人员在导入的 JSON 里配置 body 字段 |
| 调试成功、预览无数据 | 是否 保存绑定 并 保存大屏；dataPath 是否与调试一致 |
调试面板测试时只发送 URL + 方法，不会带上你在「参数配置」里填的运行时值（该区块仅在数据源 已有 params 定义 时出现）。
跟做教程：实操 · POST 接口与点击下钻（含 POST 绑定 + 点柱子跳第二页）。
参数映射与事件变量
点击图表下钻、筛选后 换一批接口数据 时，常配合 菜单与事件链 · 变量 使用。
什么时候能看到「参数映射」
- 选中已绑定数据源的组件 → 右侧 数据 → 数据源绑定。
- 若该 REST 数据源的配置里 定义了 params（见上节 info），会出现 参数映射 区块。
- 每个参数一行，下拉选择映射方式：
| 选项 | 含义 |
|---|---|
| 未绑定 | 不参与请求 |
| 使用默认值 | 用 params 定义里的 defaultValue |
| 自定义值 | 自己输入固定文本；可写 {{vars.变量名}}（须先用事件链 setVariable 写入，见 下钻示例） |
| 组件属性: xxx | 把接口参数值同步到组件某个属性 |
- 点 保存绑定。
- 在 数据源 Tab 对应项下可改 参数配置 里的值 → 使用参数刷新（编辑器内试接口）。
跟做：点击柱子记住类目（只存变量 + 跳页）
不依赖 params 定义，零基础也能做：
- 柱状图 行为 → 交互事件 → 模板 下钻：存变量并跳页。
- 把
pageId改成目标页（页面下拉里的那一页）。 - 保存 → 预览 → 点柱子 → 应跳到第二页。
- 第二页组件若需「按选中项过滤」，需接口侧支持 + 数据源 params 与 参数映射（进阶，可联系技术支持）。
数据源面板里的「参数配置」
REST 数据源 展开列表项 时，若存在 params 定义，会显示各参数字段输入框：
- 修改参数值（预览会话内有效）。
- 点 使用参数刷新 重新拉取。
- 绑定该源的所有组件会读新缓存。
静态数据 vs 动态数据
| 方式 | 何时使用 |
|---|---|
| 静态 | 演示稿、固定文案、临时数值 |
| 动态 | 生产环境、实时指标 |
推荐流程：填入示例数据 搭版 → 接好 API → 绑定数据源 → 预览验证。
预览与发布时的数据
- 登录预览：浏览器经平台后端 代理 请求 REST，减轻跨域问题
- 公开预览
/p/{token}：同样由后端代理 REST - WebSocket：在访客浏览器直连（需 WS 服务允许跨域或同域）
若本地预览正常、公开页无数据，检查 WS 地址是否对外可达。
课堂评价 API
V2.0.0 起支持课堂评价 API；V2.1.0 起活动 发布 后会在 数据源库 自动预置 五条 消费端数据源（含评委状态）。
创建步骤
编辑器 → 更多 → 数据源 或右栏 数据源 Tab。
添加 → 类型选 课堂评价 API。
选择评价活动（须已 发布，系统会自动填充凭证，无需手动填写 API Key）。
消费端点：
端点 用途 /rankings排行榜、雷达、颁奖台等 /progress进度条、进度环 /feed/recent实时动态 /tags评语词云 /judge-status评委展示（头像/进度/liveScore） 保存后，在组件 数据 中绑定该数据源。
实时推送
- 预览/发布页上，排行榜、进度、实时动态等会 随打分自动更新。
- 活动结束 后不再变化，仅展示最终排名与数据。
跨大屏共享
- 普通大屏：数据源列表包含您有 编辑权限 的全部大屏下的数据源，可跨项目复用。
- 评价活动关联大屏：仅显示 当前活动 的 eval-api 数据源（如「我的答辩-排行榜」）。
从活动创建大屏
在 评价活动 → 创建大屏 时，系统会在 数据源库 预置并绑定「活动标题-排行榜/进度/动态/评分对象/评语词频」等 五条 eval-api 数据源（活动须已 发布）。apiKey 不落库 组件 props，由运行时注入（D9）。
大屏 协作者（仅有大屏编辑权限、未加入活动协作）也可正常预览/编辑已绑定评价数据的大屏；活动名称会在组件与画布标签中显示。
相关：课堂实时评价
编辑器与预览的数据加载
| 场景 | 行为 |
|---|---|
| 编辑器 · 进入/切页 | 仅拉取 当前页、组件已绑定 的数据源；未绑定的不自动请求 |
| 编辑器 · 评价组件 | 已绑定 课堂评价 API 时，由数据源统一拉取，组件不再重复请求 |
| 预览/发布 · 空画布 | 若没有任何组件绑定数据源，不会 批量拉取评价 rankings/progress 等，也不建立多余 SSE |
| 预览/发布 · 有绑定 | 只激活已绑定数据源；评价实时仍走 SSE（同一活动多数据源共用一条连接） |
| 手动刷新 | 数据源面板 刷新图标 可随时拉取单条 |
列表里有很多数据源但画布是空的？
数据源 列表 展示的是本屏可用配置；只有绑到组件上 的才会在预览/发布时自动拉数。空大屏预览 Network 应很少请求，属正常现象。
注意事项
- 先保存大屏 再预览，绑定关系随项目 JSON 持久化
- 敏感信息（内网地址、密钥）不要写进要分享的模板；贡献模板时会 脱敏检查
- 模板编辑模式 下数据源仅在内存，不落库（模板编辑器专用）
- 接口持续失败时，组件可能显示空或上次缓存，请用调试面板排查