SDK Playground
SDK Playground
SDK Playground 是 @vp/sdk 的可运行示例库。它不只展示代码片段：337 个示例按 14 类组织，每个示例都会在真实运行时中执行、产生可浏览的效果截图，并经过类型检查、断言和浏览器 smoke 测试。覆盖门禁当前校验公开 API 触点与 25 个关键语义分支。
启动
在源码仓库根目录执行：
pnpm dev:playground要求 Node.js 20.19+。打开 http://localhost:5190 后，画廊按分类浏览卡片；点进示例进入三栏工作室：左侧示例树、中间代码（运行 / 复位，Ctrl/Command + Enter）、右侧运行效果（可放大铺满）。预览在脚本跑完后启用页面 fill-uniform + fill-auto-expand（响应式 / 百分比 / 流式页面除外），地图 / 三维 / 布局容器以及够大的卡片 / 图表吃掉剩余空间，不再改写组件几何。
Playground 使用 @vp/sdk 编译产物而不是源码别名，因此与发布给业务项目的消费形态一致。
示例覆盖
示例从简单任务逐步展开：
- 入门与挂载、工程与生命周期、页面与轮播。
- 组件句柄、数据绑定与实时推数。
- 组件事件、行为总线、脚本/请求宿主桥接。
- 窗口、第三方事件入站与连接运行时。
- 2D 地图、SCADA、三维场景。
- 自定义组件、异步注册与 Extension。
- 节点构建、工程初始化等进阶 API。
- 十个综合应用：能源、水务、园区孪生、化工安全，以及 CAD 图纸指挥、互联网管网 GIS、CAD 叠加互联网底图、离线工厂三维、CAD 巷道人员定位与三维瓦片城域。
本轮补充的独立任务配方包括挂载期行为、自动轮播、精确布局、多图表与单值仪表盘、多连接/DataReader、确定性实时 Tick、全量事件观察、跨页联动、选行填窗、窗口构建、入站去重限流和双落点、地图 FX/锚定窗口、SCADA 控制闭环、运行时三维搭建、挂载期自定义组件，以及 VpProject 逃生舱。它们不是把一个 API 拆成多个近似例，而是把综合应用中的高频组合抽成可单独迁移的配方。
完整 API 到示例的映射见 SDK API 任务索引。
编辑器中的全局对象
示例是裸 JavaScript。sdk 就是 @vp/sdk 的完整导出，可以直接抄到业务项目：
import { createProject, createVpViewer } from '@vp/sdk'
const body = createProject({ name: 'Hello SDK', subtitle: '从代码构造工程 body' })
const ctx = createVpViewer('#app', body)Playground runner 另外注入校验工具（不是 SDK API）：
assert(ctx.screens.length === 1, '页面已创建')
setStatus('运行正常', 'success')自定义组件示例可使用全局 Vue（Vue 3 render API）。
Monaco 的 sdk 提示直接来自随发布包维护的 vp-runtime.d.ts；同一份源码还会经过 TypeScript checkJs，不会出现“编辑器能补全、构建却不认识”的两套类型。
为什么默认离线
所有默认案例都禁止访问公网和后端：
- 地图使用内置空底图和本地 GeoJSON。
- 三维使用 SDK 自带图元，不加载远程模型。
- WebSocket、PocketBase、接口桥接使用浏览器内可控 transport。
- 模拟数据使用固定种子。
这保证截图、CI 和本地演示可复现。接入真实服务时，只需把示例中的 mock source 替换为业务 URL 或鉴权实现。
截图和正确性
pnpm --filter @vp/sdk-playground typecheck
pnpm --filter @vp/sdk-playground test
pnpm --filter @vp/sdk-playground test:e2e
pnpm screenshots:playground第一次运行浏览器测试或截图前执行 pnpm --filter @vp/sdk-playground exec playwright install chromium。
浏览器测试逐例等待 runner 进入 ready，并检查：
- 没有执行异常、
console.error或未处理 Promise。 - 示例断言全部通过，viewer 已挂载且产生有效 DOM。
- 没有失败的本地资源请求，以及未声明的后端或公网请求。
截图门禁另外检查 71 个目录项都存在对应的 1600×900 PNG，并校验文件签名、体积和尺寸。