官方插件指南

文档：vjcad/doc/plugin/plugin-annotation.md、vjcad/doc/plugin/plugin-architecture.md 示例：vjcad/example/plugin/05architecture.js

vjcad 自带几个官方插件，理解它们就掌握了"标准插件长什么样"。

1. 批注插件（annotation-plugin）

命令一览

设计要点

• 专属图层 _ANNOTATION：所有批注实体落入此图层，颜色 ACI 1（红）
• 自适应线宽：批注用多段线 globalWidth（不是 lineWeight），按 WCS 对角线 /500 计算
• 自适应弧长：云线弧长 = WCS 对角线 /30
• 命令委托：ANNO_TEXT / ANNO_LEADER 通过 setTimeout 异步调度委托给 MTEXT / MLEADER，避免命令嵌套

加载

const pm = PluginManager.getInstance();
await pm.loadFromUrl('./plugins/vcad-plugin-annotation.js');
// 或
await pm.loadByName('vcad-plugin-annotation');

激活后：

await Engine.editor.executerWithOp('ANNOTATION');   // 打开浮动工具栏

2. 建筑插件（architecture-plugin）

命令分类

加载与 SDK API

const pm = PluginManager.getInstance();
await pm.loadByName('vcad-plugin-architecture');

const {
    AxisGridEnt, ColumnEnt, WallEnt,
    DoorEnt, WindowEnt, StairEnt, BalconyEnt,
    ElevationMarkEnt, SectionMarkEnt
} = window.vjcadArchEntities;

// 例：建轴网
const grid = AxisGridEnt.create(
    new Point2D(0, 0),
    [3600, 3900, 5700],   // 横向间距
    [4200, 2100, 4200]    // 纵向间距
);
Engine.addEntities([grid]);

// 例：墙体（厚 240，中线对齐）
const wall = WallEnt.create(new Point2D(0, 0), new Point2D(13200, 0), 240);
Engine.addEntities([wall]);

// 例：门 + 关联墙
const door = DoorEnt.create(new Point2D(5000, 0), 'single', 900);
door.rotation = 0;
door.wallThickness = 240;

Engine.addEntities([door]);     // 必须先 add 才有 id
door.wallHandle = String(wall.id);
wall.doorWindowHandles = [String(door.id)];
wall.setModified();             // 触发墙体重绘 / 自动开洞

完整两室两厅户型例子：vjcad/example/plugin/05architecture.js

关联机制（核心）

• 墙体 WallEnt.doorWindowHandles: string[]、门窗 wallHandle: string 双向引用
• WallEnt.buildNestEnts() 在绘制时按 doorWindowHandles 自动开洞
• 门窗夹点编辑时被 约束在墙中线
• 墙体移动时 WallService 监听 EntityModified 自动 重投影门窗 位置
• 门窗删除前 WallService 监听 EntitiesErasing 把对应 ID 从 doorWindowHandles 移除，墙体补洞

国标图层（自动创建）

3. 三维视图插件（view3d-plugin，最小骨架）

官方插件里最精简的完整插件，源码结构就是上文"标准 Plugin 接口"的最小实现，可以拷贝它的 index.ts 当起点：

• manifest 必填字段示范（id: 'view3d'）
• onActivate 中 registerIcon('VIEW3D') → registerCommand('VIEW3D', ..., View3dCommand) → addMenuItem('tool', …) → addRibbonGroup('plugins', …) 的顺序
• onDeactivate 只需销毁插件自建的 UI（源码里仅 destroyView3dPanel()）；命令/菜单/Ribbon/on 事件等注册项由 PluginManager 调 context._cleanup() 自动注销，无需手写逆序注销（图标与 once 监听不在清理范围，侧栏面板仅 unload 时移除）

参考实现：vjcad/example/plugin/04pluginmanager.js（运行时构造 pluginCode 并 loadFromContent 加载，等价于真实文件）。

4. insert-plugin（图片矢量化）

INSERTIMAGE / INSERTTABLE / EXTRACTTABLE 三个命令都由 insert 插件（manifest.id: 'insert'）在 onActivate 里自己注册，核心库没有；插件未加载时执行这些命令无效果。图片矢量化用插件内部的 VectroizeService（WASM）。插件 dist 带 vcad-plugin-insert.css，而 loadByName 不加载 CSS，推荐：

await pm.loadFromUrl('./plugins/vcad-plugin-insert.js', './plugins/vcad-plugin-insert.css');
// 或（只有 JS，样式缺失）
await pm.loadByName('vcad-plugin-insert');          // 包名是 vcad-plugin-insert，构建产物 vcad-plugin-insert.js

API 用法见 insert/vectorize.md。

红旗

• 加载顺序：建筑插件依赖批注？依赖 dim？目前各官方插件相互独立，但自定义插件如果有 dependencies，先 activate 依赖，再 activate 自身
• 建筑插件实体使用 *.create() 工厂方法，不要 new WallEnt(...)：构造函数无参，传进去的起终点/厚度会被忽略，得到默认墙（0,0→1000,0）
• 关联门窗时 Engine.addEntities 之后才有 entity.id，需要在 add 后再设置 wallHandle / doorWindowHandles
• wall.setModified() 是触发开洞重绘的开关，新增/解除关联后必须调用
• 批注插件的 _ANNOTATION 图层由 ensureLayer() 按需创建（默认可见，颜色 ACI 1）；ANNO_HIDE 只是把它 layerOn=false（若它是当前图层会先切回 0）。保存图纸时图层会随文档带过去
• vjcad/example/plugin/05architecture.js 需要 先构建并复制建筑插件 dist 文件 到 playground 才能跑

参考（官方文档 MCP）

• 文档：vjcad/doc/plugin/plugin-annotation.md、vjcad/doc/plugin/plugin-architecture.md
• 示例：vjcad/example/plugin/05architecture.js