vjmapext（唯杰地图 2D 扩展包）二次开发技能

面向 vjmapext —— 挂在 vjmap.Map 上的 CAD 绘图扩展（MapCadLayer）。底座地图 API 见 vjmap skill（本包依赖它）；三维见 vjmap3d skill。

〇、文档与示例来源（路径约定）

本 skill 的 references/ 已按 vjmapext@1.0.1 的 dist/vjmapext.d.ts 与 playground 示例核对。更深细节：

示例中的 env.serviceUrl / env.accessToken 由 playground 注入；自己项目里替换为实际服务地址与 token。冲突时以 .d.ts 与示例为准。

一、适用范围

二、安装与引入

npm：

npm i vjmap vjmapext        # vjmapext 依赖 vjmap（package.json 已声明依赖，但样式/初始化仍要按 vjmap 流程）

import vjmap from "vjmap";
import "vjmap/dist/vjmap.min.css";
import { MapCadLayer, LineEnt, TextEnt, VjmapextEvents } from "vjmapext";

CDN / 全局对象（必须先 vjmap 后 vjmapext，顺序错了 UMD 拿不到 peer）：

<link rel="stylesheet" href="https://unpkg.com/vjmap@1.0.161/dist/vjmap.min.css">
<script src="https://unpkg.com/vjmap@1.0.161/dist/vjmap.min.js"></script>
<script src="https://unpkg.com/vjmapext@1.0.1/dist/vjmapext.min.js"></script>
<!-- 全局对象 vjmapext：const { MapCadLayer, LineEnt } = vjmapext -->

起步模板（复制即用）：templates/vite-app/（npm + Vite，README）与 templates/cdn/（单 HTML），含空白 CAD 画布 + MapCadLayer + createUI + 实体添加完整流程。

三、心智模型

vjmap.Map（底座，见 vjmap skill）
   │
   │  map.addControl(mapcadLayer)   ← MapCadLayer 是一个 IControl
   v
+----------------------------+
| MapCadLayer                |   创建顺序：
|  - EntityStore（实体增删改）|   1. await map.onLoad()          （vjmap 流程）
|  - RenderPipeline           |   2. const cad = new MapCadLayer(options?)
|    (cold/hot/dynamic/fx)    |   3. map.addControl(cad)
|  - CommandRegistry          |   4. cad.createUI({theme:'dark'}) （可选，要工具栏才调）
|    (LINE/CIRCLE/MOVE/...)   |   5. cad.addEntity(ent) / cad.executeCommand('LINE')
|  - InputManager             |
|    (getPoint/getSelections) |
|  - CoordMapper (CAD<->经纬) |
|  - EventBus                 |
|    (entity:*/command:*/...) |
+----------------------------+

关键认知（均经 d.ts / 示例核对）：

1. MapCadLayer 不是图层文件里的 map.addLayer，而是 map.addControl(cad) 挂上去的控件；推荐先 await map.onLoad()（提前挂也行——onAdd 内部会等 load 事件再接管）。
2. 实体构造是位置参数不是 options 对象：new LineEnt([0,0],[100,100])、new TextEnt([x,y],'文字',字高)、new PolylineEnt([[x,y],...], isClosed)。
3. ent.color 是 0xRRGGBB 整数（如 0xff0000），不是 CSS 字符串，也不支持 CAD/ACI 色号（写 1 会渲染成近黑 #000001）；程序化直接构造的实体（new LineEnt(...) 等）默认白色 0xffffff。MapCadLayerOptions.defaultColor 只作交互命令绘图的默认色，且 localStorage 已保存的绘图默认色优先于它。
4. createUI 是方法不是构造选项：new MapCadLayer({createUI:true}) 无效，要 cad.createUI({ theme })。
5. 执行命令：await cad.executeCommand('LINE')（Promise）；命令结束监听 VjmapextEvents.CommandEnded（"command:ended"）。
6. 交互命令的 entity:added 时机不一：PLINE/SPLINE 结束时一次性 add 最终实体；LINE 每段即时 add 最终 LineEnt；DLINE 会先 add 再改端点（斜接/封口）甚至 U 删除——要拿最终结果请在 command:ended 后读。

四、最小可运行模板（MRT）

在 vjmap MRT（见 vjmap skill）await map.onLoad() 之后追加：

// CDN 全局方式：const { MapCadLayer, LineEnt, TextEnt, VjmapextEvents } = vjmapext;
const cad = new MapCadLayer();          // 不要传 { createUI: true }，那是无效字段
map.addControl(cad);
cad.createUI({ theme: 'dark' });        // 可选：要内置工具栏才调

const line = new LineEnt([0, 0], [100, 100]);   // 位置参数 (startPoint, endPoint)
line.color = 0xffcc00;                          // 数字色值
cad.addEntity(line);

const label = new TextEnt([0, 120], '示例文字', 20);
label.color = 0xffffff;
cad.addEntity(label);

// 执行内置绘图命令
cad.eventBus.on(VjmapextEvents.CommandEnded, e => console.log('命令结束', e));
await cad.executeCommand('LINE');               // 用户开始交互式画线

参考示例：mapext/example/basic/01blankMap.js（空白图 + 多实体）、02cadMap.js（叠加到 CAD 底图）。

五、按用户场景速查

标 【vjmap】 的条目属底座能力，文件在 ../vjmap/references/。

六、完整文件地图

CAD 实体 (entity/)
overview · lifecycle · style-props · transform · line-polyline · circle-arc-ellipse · spline · point · hatch · text · font-text · block-reference · dimensions · leader · revcloud · custom-entity

绘图命令 (drawing/)
overview · execute-command · builtin-draw · builtin-edit · input-manager · snap · grip · preview · undo-redo · serialize · custom-command · shortcuts · mode

批量 (batch/)
overview · entity-bulk-add · mapdata-query · features-to-entities · mapdata-hider · bulk-style-update

事件 EventBus (event/)
bus-entity · bus-selection · bus-command-mode · bus-render-store（事件清理 off/offAll 见 vjmap skill event/cleanup）

性能 (perf/)
render-buckets · dynamic-entities · style-only-fast-path · render-cache · fx-overview · fx-quality · fx-presets · batch-rendering

坐标 (coord/)
cad-mapper（坐标空间概念见 vjmap skill coord/concepts）

常见坑 (trouble/)
createui-no-theme · batch-lag · fromjson-fit

七、约定与红旗

命名

• cad / mapcadLayer = MapCadLayer 实例；VjmapextEvents = 事件常量表（"entity:added" / "command:ended" / "selection:changed"…）。
• 实体一律 new LineEnt(...) / new TextEnt(...) 等位置参数（不是 options 对象）→ 设属性 → cad.addEntity(ent)。

Top 8 红旗

1. new MapCadLayer({ createUI: true }) → createUI 不是构造选项，工具栏出不来；要 cad.createUI({ theme })。
2. vjmapext.min.js 在 vjmap.min.js 之前加载 → peer 未就绪报错。
3. map.onLoad() 之前就 addControl(cad) → 其实安全（onAdd 在 !map.loaded() 时挂 map.on('load') 延后初始化）；但仍推荐先 await map.onLoad()（官方示例均如此），并紧接着挂——onLoad 之后又 await 其它异步、地图正在加载新瓦片时才挂，map.loaded() 可能为 false 而 load 不会再发，层永不接管（见 drawing/overview）。
4. ent.color = "#f00"（CSS 字符串）→ 不生效；色值是 0xRRGGBB 整数（0xff0000），ent.color = 1 这类 CAD 色号也不认（变近黑）。
5. 循环里逐条 addEntity + setDirty → 卡；用批量姿势（batch/entity-bulk-add）。
6. 把 DLINE 等命令中途的 entity:added 当最终结果 → 端点之后还会被改/删；等 command:ended 再读。
7. eventBus.on 没配对 off → 组件卸载后回调残留（泄漏排查见 vjmap skill trouble/listener-leak）。
8. fromJSON(doc) 后忘 zoomExtents() → 实体在屏外"看不到"（trouble/fromjson-fit）。