SDK 与扩展开发

除了在编辑器里搭建，唯杰AI可视化平台还提供多种二次开发能力，把大屏融入你自己的系统：

• SDK 嵌入：把做好的大屏挂到你的网页里，用代码控制它、给它喂数据、听它的事件。
• 程序化搭建：完全用代码（不依赖固化的工程文件）动态创建页面、组件、窗口。
• 二次开发脚本：在编辑器「代码面板」里写脚本，响应交互、操作元素。
• 自定义组件：注册你自己的组件类型。
• Playground：按分类浏览、编辑并运行完整 JavaScript 示例，查看自动生成的效果截图。

本页重点讲 SDK 的用法与原理。

SDK 是什么

@vp/sdk 是运行时的门面（facade）。一行 createVpViewer 就能把一份工程挂载到页面并播放，同时返回一个运行上下文 ctx，让你程序化地操作这个大屏。

它只导出纯 TypeScript 接口与函数（不外露 Vue 组件），因此类型稳定、易于集成。

快速上手

import { createVpViewer } from '@vp/sdk'

const ctx = createVpViewer('#app', body /* 工程文件内容 */, {
  params: { theme: 'dark' },          // 项目参数（千人千面）
  onReady(ctx) {
    // 工程挂载完成，可在此用 ctx 操作大屏
    console.log('页面数：', ctx.screens.length)
  },
})

• 第一个参数：挂载容器（CSS 选择器或 DOM 元素）。
• 第二个参数：工程文件内容 body（编辑器导出的 { project, connections, connectionData, dataRules }）。
• 第三个参数：挂载选项（回调、参数、自定义组件等）。

想直接修改并观察运行效果，可启动 SDK Playground；需要按任务查全部公开方法，可看 SDK API 任务索引。

工作原理

createVpViewer 内部做的事，和独立运行时 / 编辑器预览完全同源：

所以 SDK 里渲染出来的大屏，与编辑器预览、独立 viewer 呈现的一模一样——它们用的是同一套运行时。

运行上下文 ctx 能做什么

createVpViewer 返回的 ctx（VpViewerContext）覆盖了二次开发的主要诉求：

分类	能力
工程信息	projectId / projectName / project（运行时工程实例，逃生舱）/ connectionData（响应式行数据）
页面	screens / activeScreen / getScreen / setActiveScreen / addScreen / removeScreen
窗口	windows / openWindows / getWindow / openWindow / closeWindow / closeTopWindow / addWindow / removeWindow
组件	getWidget / findWidgets / getWidgetsByType / getMap / getScada / addWidget / removeWidget（寻址与枚举覆盖页面 + 窗口）
数据 / 参数	setData / getData / getConnections / getTables / refreshData / onDataChange / getParams / setParams / onParamsChange
事件	on / emit（行为事件总线）/ startEventInbound（第三方入站）/ onScript / onRequest
生命周期	reload(body) / destroy()

组件句柄（ctx.getWidget(uid) 返回）还提供 setOption / setData / addField / on / onClick / emit 等操作。

常见任务

实时推数（把外部数据喂给大屏）：

setInterval(() => {
  ctx.setData('conn-sales', 'monthly', rows)  // 替换某连接某表的行，自动重渲
}, 3000)

监听大屏发出的行为事件：

ctx.on('open-detail', (event, payload) => {
  // 大屏里某个「发送行为事件」动作触发时收到
})

接管「调用接口 / 执行脚本」动作（加签 / 代理 / Mock）：

ctx.onRequest(async (req) => {
  const res = await myProxyFetch(req)
  return res  // 返回解析后的数据，交由动作结果模式落地
})

程序化搭建（完全用代码创建组件与窗口，见 sdk-demo）：

const bar = await ctx.addWidget({ type: 'chart-bar', name: '月度销售', position: [40, 120], size: [780, 360] })
bar?.addField(['conn-sales', 'monthly', 'month'])
bar?.addField(['conn-sales', 'monthly', 'sales'])

千人千面：用 params 注入 + setParams 修改项目参数，驱动数据规则 / 条件样式 / 状态重算。

挂载选项

选项	说明
params	项目参数注入（与 project.params 合并）
transformData(body)	挂载前对工程数据加工
widgets	挂载前注册自定义组件
onReady(ctx)	挂载就绪回调（在此用 ctx 操作大屏）
onBehavior	监听全部行为事件（等价 ctx.on(handler)）
onScript / onRequest	接管「执行脚本」/「调用接口」动作
carousel	多页面自动轮播

二次开发脚本

编辑器「代码面板」里可编写脚本（Extension），在运行态响应交互、读写元素与数据。它通过统一的 VpExtensionContext 暴露元素 / 工程 API，宿主可用 onScript 接管「执行脚本」动作把命令派发给你的实现。详见二次开发脚本（代码面板）。

自定义组件

组件类型可扩展。用 SDK 挂载时通过 widgets 选项、或直接调用 registerWidgetType(type, module) 注册。一个组件模块 = 模型类 + Vue 渲染组件 + 元信息（meta）。详见自定义组件开发。

---

延伸阅读：SDK Playground · SDK API 任务索引 · 工程文件结构 · 数据系统（ctx.setData 推数与平台数据订阅）· 事件交互（executeScript / sendBehaviorEvent 与宿主互通）· 组件手册（自定义组件的参数蓝图）。