vjcad — 唯杰 WebCAD 编辑器 SDK 二次开发

pkg: vjcad@1.0.16          # npm 已发布；UMD 全局对象 vjcad
docsMcp: https://vjmap.com/server/aimcp/mcp?products=vjcad

本 skill 的 references/ 基于官方文档整理改编（合并实体专页、增补 quickref/autodraw 等自撰章节）。仍需更深细节时按下列来源查证，冲突时以 npm 包 dist/types.d.ts 与 playground 示例为准：

服务地址与 token 换为你自己的（公有云 https://vjmap.com/server/api/v1，私有化 http://<ip>:27660/api/v1，见 vjmap-service skill）。wasm / 字体默认由 serviceUrl 所指服务提供（<serviceRoot>_webcad/wasm），不要另设 wasmServiceUrl。不要把 token 写进提交的代码。

安装与模板

npm i vjcad

• vite 模板 → templates/vite-app/（README）
• 纯 HTML / CDN 模板 → templates/cdn/（<script src> UMD，全局对象 vjcad）

// npm / ESM
import { MainView, initCadContainer } from "vjcad";

// CDN / UMD
const { MainView, initCadContainer, message } = vjcad;

心智模型

                              [DWG / WebCAD JSON / 互联网底图]
                                            |
                                            v
   +-----------------------+     await      +------------------------+
   |  new MainView({...})  | ---> onLoad -> |       Engine            |  <-- 运行时上下文唯一入口
   +-----------------------+     PixiJS/    +-----------+------------+
              |                  WASM/                  |
   initCadContainer(id, view)    Fonts/                 v
              |                  Plugins/         +-----------------+
              v                  URL params      |  pcanvas         |  (画布、regen/redraw/zoomExtents)
        DOM 容器挂载                              +-----------------+
                                                  |  currentDoc       |  (CadDocument，含 layers/blocks/...)
                                                  |    └ currentSpace |  (ModelSpace/PaperSpace，items/addEntities/erase)
                                                  |  editor           |  (executerWithOp / 命令调度 / contextMenu 右键菜单)
                                                  |  eventManager     |  (on/off/once/suspendEvents/resumeEvents + CadEvents)
                                                  |  undoManager      |  (undo/redo/start/end/UndoDescriptor)
                                                  |  trans            |  (CanvasToWcs / WcsToCanvas / WcsToUcs)
                                                  +-----------------+

关键认知：

1. 入口三段式：new MainView({...}) → initCadContainer(elementId, cadView) → await cadView.onLoad()。onLoad() 之前禁止使用 Engine。
2. 实体三段式：new XxxEnt(位置参数…)（如 new LineEnt([0,0],[100,0])、new CircleEnt([0,0],50)，构造函数不收选项对象）→ setDefaults() → Engine.addEntities([ent])（自动记录撤销）；若用 Engine.pcanvas.addEntity 需自行 added_undoMark。
3. 命令三段式：class { async main() {...} } + CommandDefinition + CommandRegistry.regist(cmdDef) → Engine.editor.executerWithOp('CMDNAME') 触发；main 内 getPoint / getSelections / getEntity / Engine.getString 交互，逐步检查 InputStatusEnum.OK/Cancel（getPoint 空回车/空格返回 None，EnterOrSpace 仅 getEntity）。
4. 服务端图纸：drawingManager.openDrawing({...}) → new File([jsonString], docName) → await Engine.view.openDbDoc(virtualFile, webcadData)，并在 Engine.currentDoc.serverSource 记录 type/mapid/version/branchName/lastPatchId（openDbDoc 不会设置；须在 setOriginalJson 之前赋值，否则后者直接返回 false）。
5. 事件清理：监听必须有对应 off(event, handler)；勿用 offAll（会连内核自己的监听一起移除，关联标注/Ribbon 刷新失效）；交互式命令（PLINE/SPLINE）的 EntityAdded 拿到中间态，命令结束（CommandEnded）后再读最终点位。

最小可运行模板

import { MainView, initCadContainer, Engine } from "vjcad";

const cadView = new MainView({
  appname: "我的CAD应用",
  version: "v1.0.0",
  serviceUrl,      // 你的服务地址（wasm/字体也从这里加载）
  accessToken,     // 你的 token
});
initCadContainer("cad-app", cadView);   // 容器需有非零宽高
await cadView.onLoad();

// onLoad 之后才可用 Engine；Engine 是全局单例绑最近活跃视图，多实例先 Engine.bindViewCache(cadView)
// 或直接用视图实例成员 cadView.editor / cadView.pcanvas（cadView.Engine 不存在）
Engine.editor.executerWithOp("LINE");

只读 Viewer：MainView 配置加 viewMode: "viewer"（是 viewMode 不是 viewerMode），可叠加 showUcsIcon:false / showAxis:false / enableContextMenu:false / showGrips:false。

按场景速查

约定与红旗

命名

• cadView = MainView 实例；Engine = vjcad 导出的全局单例（onLoad 后才可用，cadView.Engine 不存在）。
• doc = Engine.currentDoc；space = Engine.currentSpace；pcanvas = Engine.pcanvas；editor = Engine.editor；eventManager = Engine.eventManager；undoManager = Engine.undoManager。
• cmdDef = CommandDefinition；drawingManager = DrawingManagerService 实例。

Top 红旗

1. cadView.onLoad() 之前 用 Engine / Engine.currentDoc / Engine.eventManager → undefined。
2. 把 vjmap 的 new vjmap.Service() / new vjmap.Map() 套到 vjcad → vjcad 只走 MainView + initCadContainer。
3. 忽略 InputStatusEnum.Cancel，用户 Esc 后还继续建实体。
4. 监听事件不 off → 泄漏；用 offAll() 清理 → 误删内核内部监听。
5. EntityAdded 里读 PLINE/SPLINE 完整点位 → 中间态；命令结束后再读。
6. viewMode:"viewer" 下调编辑命令。
7. 编造未在文档/示例出现的 API（见 trouble/source-conflicts：命名不一致时以能跑的示例为准）。
8. 容器 <div> 无宽高 → 黑屏。
9. Engine.pcanvas.addEntity(ent) 后忘 added_undoMark 或 regen/redraw。
10. 循环里逐个 addEntities 且每次 regen/zoomExtents → 卡顿；批量加完再统一 regen。