SDK API 任务索引

本页按“要完成什么任务”组织 @vp/sdk 公开 API。精确参数和返回类型以包内 vp-runtime.d.ts 为准；可运行效果与完整 JavaScript 见 SDK Playground。

挂载与卸载

import { createVpViewer } from '@vp/sdk'
import '@vp/sdk/vp-runtime.css'

const ctx = createVpViewer('#app', body, {
  params: { region: '华东' },
  transformData(body) {
    // 挂载前加工工程数据
    return body
  },
  onReady(ctx) {
    console.info(ctx.projectName)
  },
})

ctx.reload(nextBody)
ctx.destroy()

createVpViewer 的第二个参数是已经加载到内存的 VpProjectBody，不是 URL。工程在服务端时，由宿主先 fetch/鉴权/解析，再传给 SDK。

挂载相关导出：

• createVpViewer(target, body, options)
• createProject(input) 用名称/组件/连接构造 VpProjectBody（传入 subtitle 时带顶部标题条；组件已占用该区域则不插入）
• mergeProjectParams(body, params)
• buildProjectInit(body)
• VP_SDK_VERSION

工程、页面与参数

VpViewerContext 提供：

• 工程：projectId、projectName、project、connectionData
• 页面：screens、activeScreen、getScreen、setActiveScreen、addScreen、removeScreen
• 参数：getParams、setParams、onParamsChange
• 生命周期：reload、destroy

VpScreenHandle 提供：

• getWidgets / getAllWidgets / getWidget
• findWidgets / getWidgetsByType
• addWidget / removeWidget
• activate / onAppear
• getSize / getOption / setOption

页面参数适合做租户、区域、主题和权限差异；修改后会驱动依赖参数的数据规则、条件样式和组件状态重算。

创建和操作组件

const chart = await ctx.addWidget({
  type: 'chart-line',
  uid: 'load-trend',
  name: '负荷趋势',
  position: [40, 120],
  size: [720, 360],
})

chart
  ?.setOption('title', '实时负荷')
  .setPosition([60, 140])
  .setSize([760, 380])
  .show()

寻址和 CRUD：

• 上下文：getWidget、findWidgets、getWidgetsByType、addWidget、removeWidget
• 句柄标识：uid、type、name、raw
• 属性：getOption、setOption、setOptions、getOptions
• 几何：getPosition、setPosition、getSize、setSize、getRotate、setRotate
• 状态：isVisible、setVisible、show、hide、setEnabled、setName
• 树：getChildren、addChild、getParent、getScreen、remove
• builder 子元素：getPieces、addPiece、removePiece（三维加罐/删管、组态图元、地图图层；scene3d-scene / scene3d-camera / map-body 不可删）

完全从代码构造节点时可使用 buildWidgetNode、buildPieceNode、buildScreenNode。

数据探查、绑定与推数

const connections = ctx.getConnections()
const tables = ctx.getTables(connections[0].uid)

chart?.bindField('series-field', ['conn-energy', 'trend', 'load'])
chart?.addField(['conn-energy', 'trend', 'time'])

const off = ctx.onDataChange('conn-energy', 'trend', (rows) => {
  console.info('新行数', rows.length)
})
ctx.setData('conn-energy', 'trend', nextRows)

上下文数据 API：

• setData / getData
• getConnections / getTables
• refreshData
• onDataChange

组件数据 API：

• getData
• getBoundFields / bindField / addField
• setData
• getPrivateData / setPrivateData
• getValue / getSelectedData / select

需要自行管理连接运行时的进阶场景可使用 startConnectionRuntime。一般应用不必调用：createVpViewer 已自动启动并在 destroy 时停止。

事件与宿主桥接

组件事件：

• on / emit
• onClick / click
• onSelect
• onValueChange
• watchOption

工程行为总线：

const off = ctx.on('open-device', (_event, payload) => {
  ctx.openWindow('device-detail')
})

ctx.emit('open-device', { id: 'P-101' })
ctx.emit('highlight', { level: 2 }, 'target-widget-uid')

宿主桥接：

• ctx.onScript(handler) 接管工程中的“执行脚本”动作。
• ctx.onRequest(handler) 接管工程中的“调用接口”动作，用于鉴权、代理和 Mock。
• 挂载选项 onBehavior / onScript / onRequest 可注册首批监听者。

第三方事件入站

ctx.startEventInbound(source, options) 把第三方消息归一为行为事件，也可同时写入连接表。

内置 source：

• postMessageEventSource({ origin? })
• websocketEventSource(url)
• pollingEventSource(pull, intervalMs)
• pocketbaseEventSource(options)

辅助 API：

• parseInboundEvent(raw)
• VpInboundChannelOptions.allowNames：事件白名单
• dedupBy：去重键
• minIntervalMs：限流
• setData：replace / append / prepend 写表

所有入站通道都会被上下文跟踪；ctx.destroy() 会自动停止。手动停止时调用 startEventInbound 返回的退订函数。

窗口

上下文：

• windows / openWindows
• getWindow
• openWindow / closeWindow / closeTopWindow
• addWindow / removeWindow

VpWindowHandle：

• isOpen
• open(context?) / close
• onOpen
• 与页面相同的组件查询、添加、移除和 option API

VpWindowOpenContext 可携带 openerUid、地图经纬度和锚点偏移，用于组件旁或地图点位旁的锚定窗口。

2D 地图句柄

const map = ctx.getMap('park-map')
map?.getSource('enterprise-source')?.setData(geojsonRows)
map?.getLayer('risk-layer')?.show()
map?.flyTo({ lng: 120.1, lat: 30.2, zoom: 13 })

VpMapHandle：

• 图层：listLayers、getLayer、setLayerOption、setLayerVisible
• 数据源：listSources、getSource、setSourceData、setSourceVisible、refreshData
• 相机：flyTo、fitData、fitWhole、setZoom
• 选择：clearSelection
• 交互绘制：canDraw、startDraw、getDraw

VpLayerHandle 提供 option 与显隐链式操作；VpSourceHandle 提供推数、刷新和显隐操作。组件句柄也可通过 asMap() 转为地图句柄。

交互绘制与图形编辑

想让用户「在地图上选坐标」「画一块区域边界」时，用 startDraw() 开一个绘制会话， 它包的是引擎自带的 vjmap Draw 工具（mapbox-gl-draw 一脉），交互都是原生的： 双击/回车结束绘制、点中图形拖顶点、点边中点加顶点、Backspace 删顶点、Esc 取消。

const map = ctx.getMap('park-map')
if (!map?.canDraw()) return // 地图异步初始化，建议 map-ready 之后再问

const draw = map.startDraw({
  mode: 'polygon',
  // 只留必要按钮；传 false 则不建引擎工具栏，完全用自己的界面 + setMode 驱动
  toolbar: ['polygon', 'trash'],
  // 编辑既有图形：把当前几何送进去，用户直接拖顶点改
  features: { type: 'FeatureCollection', features: [{ type: 'Feature', geometry: existing, properties: {} }] },
})

draw?.onChange((change) => {
  // change.kind: create / update / delete / select / mode
  // change.all 是变化后的全量要素，省一次 getAll()
  const polygon = change.all.features.find((f) => f.geometry?.type === 'Polygon')
  console.log(polygon?.geometry)
})

// 用完务必收尾：移除控件与事件监听
draw?.dispose()

会话方法：setMode / getMode / set / add / getAll / getSelectedIds / delete / deleteAll / trash / undo / redo / setFeatureProperty / onChange / dispose。

几点约定：

• 模式 select(选中拖动整体) / edit(拖顶点，需 featureId) / browse(只读) / point / line / polygon / rectangle / circle。
• 几何一律是地图渲染坐标（地理底图=经纬度）；CAD 底图要源 X/Y 时用 map.fromLngLat 自行换算。
• 同一地图重复 startDraw 返回同一会话（避免叠出多个控件）；要换初始化参数先 dispose()。
• 引擎版本没有 Draw.Tool 时 canDraw() 为 false、startDraw() 返回 null，据此降级到手工输入即可。

SCADA 句柄

ctx.getScada(uid) 或 widget.asScada() 返回 VpScadaHandle：

• 测点：setPoint、setPoints、getPoint、clearPoints、pointKeys
• 结构：listNodes、listLinks
• 改图元选项：setPieceOption(pieceUid, option, value)（运行时指定图像集第几张、起停精灵图等）
• 事件：onNodeClick、onNodeDblClick、onLinkClick、onBlankClick

三维场景目前没有独立 handle；通过通用 VpWidgetHandle 操作 pieces（getPieces / addPiece / removePiece）、数据绑定和行为事件完成控制。

自定义组件

主要导出：

• VpWidget
• useWidget / useWidgetSafe
• registerWidgetType
• registerWidgetLoader
• registerBuiltinWidgets
• VpWidgetModule / VpWidgetMeta
• VpOptionGroupDef / VpOptionItemDef

挂载前可把组件放到 VpMountOptions.widgets，避免全局提前注册。完整结构见 自定义组件开发。

Extension

组件句柄可在运行时管理代码面板脚本：

• getExtensions
• addExtension
• updateExtension
• removeExtension

公开类型包括 VpExtension、VpExtensionContext、VpExtensionElementApi、VpExtensionProjectApi、VpExtensionInstance。生命周期和安全边界见 二次开发脚本。

逃生舱原则

ctx.project 和各句柄的 raw 暴露底层模型，适合 SDK 尚未提供高层封装的少数能力。业务代码应优先使用本页列出的稳定门面；使用逃生舱时要封装在自己的适配层中，避免内核升级扩散到应用各处。