前言
前段时间我们发布了 WebCAD 平台（vjmap.com/app/webcad/），解决了"在 Web 端打开和编辑 CAD 图纸"这件事。
这次发布 唯杰地图扩展包 vjmapext，不是重复造一个平台，而是补上另一块能力：把 CAD 绘制、编辑和高性能渲染，以插件方式接入你现有的 vjmap 项目。
一句话定位
vjmapext 是 vjmap 的 CAD 绘图扩展层，核心入口是 MapCadLayer。
它不是一个独立平台，而是一个可嵌入的能力组件：你把它加到地图里，就有了 CAD 级别的图元绘制、编辑、标注、动画和扩展能力。
官方文档入口：
WebCAD 和 vjmapext 是什么关系
可以把它理解成"平台 + 插件能力"的分工：
- WebCAD：更像开箱即用的平台能力，适合直接在线打开和编辑图纸。
- vjmapext：更像开发者工具箱，适合把 CAD 能力嵌入你的业务系统里，和业务流程、绘制、数据、界面一起做深度集成。
所以它们不是替代关系，而是互补关系。
如果你要"直接编辑用"，WebCAD 合适；如果你要"接入自己的系统基于vjmap开发并持续迭代"，vjmapext 更合适。
vjmapext 能做什么
从业务角度看，最常见的是下面几类能力组合。
1) 在 CAD 底图上做业务标注和交互、自动成图
你可以打开 CAD 图作为底图，然后叠加区域、点位、路径、文字和图例，把静态图变成可交互业务图。
这类能力常见于：
-
园区设施管理；
-
工厂设备点巡检；
-
室内平面图上的状态展示。
-
自动成图功能
-
图形的绘制，编辑
2) 浏览模式与编辑模式
vjmapext 支持只读浏览和编辑模式切换，便于做"查看"和"编辑"的显示不同。
例如在只读模式下仍允许关键对象可选中，用于查看属性、定位问题。
可以在编辑模式下对数据方便进行编辑，在浏览模式下对数据进行数据查看效果展示。
3） 动画与特效
- CPU 动画：拖尾、弹簧、关键帧、闪烁、线段渐现
- GPU FX：点/线预设效果，支持较大数量级渲染
- FX 与 CAD 实体可绑定，实体移动后特效可跟随
- 支持性能相关控制（比如更新频率、渲染策略）
- 支持shadertoy上面的shader支持复制过来使用
如果你要做态势图、告警图、运行状态图，这块会非常好用。
可以直接参考这个示例页：
vjmap.com/app/demoext...
安装
依赖与环境（必读）
- vjmapext 不能脱离 vjmap 单独使用。 必须先具备 vjmap 运行环境（地图 SDK、底图样式、服务与
vjmap.Map等），再使用本库。 - npm 工程 ：请同时安装
vjmap与vjmapext（或已安装满足版本要求的vjmap）。仅安装vjmapext、未安装/未加载vjmap时无法正常工作。 - 本包发布内容 ：以
package.json的files为准，一般为dist下的vjmapext.min.js（UMD） 与类型声明；
npm 安装
bash
npm install vjmapext快速接入（最小工程骨架）
ts
import { MapCadLayer } from "vjmapext";
const mapcad = new MapCadLayer({
locale: "zh",
mode: "edit",
defaultColor: 0x7fd3ff,
});
map.addControl(mapcad);
mapcad.createUI({ theme: "dark" });建议启动前先配置这 6 项：
mode：edit或browse；drawingDefaults：颜色、线宽、图层默认值；shortcuts：是否覆盖默认快捷键；- 字体：有文字实体时先
loadFont()； - 交互：是否启用捕捉及捕捉模式；
- 持久化：先确定
toJSON/fromJSON存储位置。
SDK 功能详解（含作用说明）
1）命令系统
核心 API：
executeCommand(name, opts?)repeatLastCommand()getLastCommandName()
内置命令覆盖（40+）：
- 绘图：
LINE、PLINE、POINT、CIRCLE、ARC、ELLIPSE、SPLINE、FREEHAND、RECTPOLY、DLINE、REVCLOUD、HATCH - 编辑：
MOVE、COPY、ERASE、MIRROR、OFFSET、SCALE、STRETCH、BREAK、TRIM、EXTEND、FILLET、ARRAY、EXPLODE、DRAWORDER - 标注：
DIMLINEAR、DIMALIGNED、DIMANGLE、DIMRADIUS、MLEADER - 文字：
TEXT、TEXTEDIT、MTEXT - 块与导入：
BLOCK、INSERT、IMPORTSVG
作用描述（详细）：
- 把 CAD 操作抽象成统一命令后，业务系统只需绑定命令，不需要重复造编辑逻辑；
- 多模式命令（如
CIRCLE、ARC）可通过关键字切换子流程，减少多命令拆分维护成本； - 命令可以统一挂到工具栏、右键菜单、快捷键与业务流程引导页面；
- 命令执行链可接日志，形成"用户操作轨迹"。
逐命令功能说明（精简版）：
-
绘图命令
-
LINE：按点创建直线段，适合轴线、连线、边界基础绘制。 -
PLINE：连续多段线，支持闭合和回退点，适合轮廓线与路径线。 -
POINT：创建点实体，常用于定位点、控制点、设备锚点。 -
CIRCLE：圆绘制，支持圆心半径、直径、两点、三点、切线等模式。 -
ARC：圆弧绘制，支持多构造方式，适合弧形边界和连接段。 -
ELLIPSE：椭圆绘制，支持中心法/轴端点法，常用于设备包络或符号。 -
SPLINE：样条曲线，适合平滑边界、自由曲线表达。 -
FREEHAND：自由手绘，适合快速草绘与现场标记。 -
RECTPOLY：矩形/多边形绘制，适合区域框选、面状边界初稿。 -
ARROW：箭头绘制，用于流程方向、流向标识。 -
HATCH：填充封闭区域，适合功能分区、材质区、风险区高亮。 -
TOHATCH：将封闭图形转换为填充对象，便于后处理。 -
DLINE：双线绘制，适合道路、墙体、管廊边界等平行线对象。 -
REVCLOUD：修订云线，常用于审图圈改、问题标注。 -
文字命令
-
TEXT：单行文字，适合点位名、编号、简短说明。 -
TEXTEDIT：编辑既有文字内容，适合在线修正文案。 -
MTEXT：多行文字，适合批注段落、说明块。 -
标注命令
-
DIMLINEAR：线性标注，输出水平或垂直尺寸。 -
DIMALIGNED：对齐标注，沿对象方向标注真实长度。 -
DIMANGLE：角度标注，适合角点控制与转角校核。 -
DIMRADIUS：半径标注，适合圆/弧尺寸表达。 -
MLEADER：多重引线，适合复杂构件说明与指向标注。 -
编辑命令
-
MOVE：整体平移对象到新位置。 -
COPY：复制对象，适合重复布置。 -
ERASE：删除对象。 -
MIRROR：镜像对象，适合对称图形快速生成。 -
OFFSET：平行偏移对象，适合生成内外边界。 -
SCALE：按比例缩放对象。 -
STRETCH：局部拉伸对象几何。 -
BREAK：打断对象，生成断开段。 -
TRIM：按边界修剪超出部分。 -
EXTEND：按边界延伸对象到交界处。 -
FILLET：圆角连接两对象，生成平滑转角。 -
ARRAY：阵列复制，适合规则分布对象。 -
EXPLODE：分解复合对象（块、多段线等）为基础实体。 -
DRAWORDER：调整前后绘制顺序，控制遮挡与可见层次。 -
块与导入命令
-
BLOCK：将一组对象定义为块，便于复用和规范化管理。 -
INSERT：插入块引用，支持重复放置。 -
PASTECLIP：粘贴剪贴板对象，提升跨区域编辑效率。 -
IMPORTSVG：导入 SVG 并转为可编辑对象，便于外部图标/图形接入。
命令使用建议：
- 前台工具栏通常优先暴露
LINE/PLINE/CIRCLE/MOVE/COPY/ERASE/TRIM/EXTEND/DIMLINEAR/TEXT； - 审图类页面建议增加
REVCLOUD/MLEADER/TEXTEDIT； - 模板化制图建议优先启用
BLOCK/INSERT/ARRAY； - 若是存量图改造，命令层要与
MapData + Hider + exportDwg一起设计。
示例：
2）输入系统（InputManager）
输入能力：
- 点输入（坐标点采集）
- 选集输入（单选、框选、多选）
- 数值输入（长度、半径等）
- 关键字输入（命令子模式切换）
- 字符串输入（文字命令等）
作用描述（详细）：
- 输入统一后，所有命令交互行为一致，降低用户学习成本；
- 对开发者来说，命令只管业务逻辑，输入边界（取消、确认、回退）交给统一系统处理；
- 输入与预览联动后，用户在确认前就能看到结果，减少误提交；
- 是"可编辑能力稳定性"的底座。
示例：
3）对象捕捉（Snap）与夹点编辑（Grip）
捕捉能力：
- 端点、中点、圆心、交点、最近点等模式；
- 支持模式组合与开关控制；
- 在命令点输入阶段实时生效。
夹点能力：
- 选中实体后显示可编辑夹点；
- 拖拽夹点修改几何；
- 可与撤销重做联动。
作用描述（详细）：
- 捕捉解决"线上操作精度不足"问题；
- 夹点解决"局部改图要重画"问题；
- 两者配合，能在网页端做可用的精修工作流，而不是仅展示级编辑。
示例：
4）实体存储与选择管理
核心 API：
addEntity(entity)deleteEntity(id)getEntities()getSelectedEntities()clearSelection()
作用描述（详细）：
- 实体层统一管理后，渲染层、属性面板、事件系统都能共享同一数据源；
- 选择集明确后，编辑命令可避免"误改全部对象"；
- 可在业务系统里按选择集做批处理（改颜色、改图层、改属性）；
- 是批量编辑、批量审查、批量导出的前置基础。
示例：
5）撤销重做（Undo/Redo）
核心 API：
undo()redo()
作用描述（详细）：
- 在线编辑可回退，用户才敢进行复杂操作；
- 支持和快捷键联动，操作习惯接近桌面 CAD；
- 可用于审图流程中的"试改-对比-还原"。
示例：
6）标注体系
相关命令：
DIMLINEARDIMALIGNEDDIMANGLEDIMRADIUSMLEADER
作用描述（详细）：
- 标注能力决定图纸可审核性，不只是视觉增强；
- 统一标注命令可把尺寸、角度、说明纳入标准编辑流；
- 对工程协同来说，标注是交底、复核、验收的核心数据表达。
示例：
7）文字与字体管理
相关能力：
- 命令：
TEXT、TEXTEDIT、MTEXT - API：
loadFont(url, name?)
作用描述（详细）：
- 文字是图纸语义信息的重要组成；
- 字体加载可避免线上渲染错位或替换字体导致排版变化；
- 文字编辑能力可直接承接审图意见修订流程。
示例：
8）块（Block）能力
相关能力：
- 命令：
BLOCK、INSERT - 数据：块定义、块引用
- 序列化：块信息可随文档保存恢复
作用描述（详细）：
- 块能力是减少重复绘制和统一规范的核心；
- 适合设备符号、标准构件、图例模板等复用对象；
- 可建立企业标准块库，提升制图一致性。
示例：
9）序列化与绘图默认值
核心 API：
toJSON()fromJSON(doc)setDrawingDefaults(partial)getDrawingDefaults()
作用描述（详细）：
- 支持"保存当前进度 -> 跨会话继续编辑"；
- 支持"模板化初始化图纸"；
- 支持团队统一绘图规范（图层、线宽、颜色）；
- 是多人协作和版本回放的基础。
10）MapData 数据联动
核心 API：
queryMapEntities(opts)queryMapEntitiesByLayer(layer, entType, extra?)featuresToEntities(featureCollection, opts?)createMapDataHider()
标准链路：
- 按条件查询后端 DWG 实体；
- Feature 转 SDK 实体；
- 隐藏原图被接管对象；
- 前端叠加编辑；
- 最终导出。
作用描述（详细）：
- 不需要一次性迁移历史图纸；
- 可在原图基础上做增量改造；
- 可把"后端存量数据"接入"前端可编辑流程"；
- 适合传统项目数字化升级。
示例：
11）DWG 导出交付
核心 API：
exportDwg(opts)setExportDwgCallback(cb)
常见组合：
exportDwg({ hider })onBeforeUpdate导出前加工deleteFromSource导出时清理源对象
作用描述（详细）：
- 打通"在线编辑 -> DWG 文件交付"；
- 保持与传统 CAD 工具链衔接；
- 减少人工二次整理步骤。
12）渲染与性能机制
可核验机制：
- 三源分桶：
hot/cold/dynamic - 增量更新与脏标记刷新
- 渲染缓存复用
styleOnly样式快路径
作用描述（详细）：
- 高频操作时减少全量刷新；
- 大图场景下更稳定；
- 只改样式时避免几何重建；
- 给后续性能调优提供结构基础。
13）FX 特效层
能力点：
- 批量添加特效对象；
- 质量档位调节；
- 指标与事件输出；
- CAD 实体绑定。
作用描述（详细）：
- 可用于状态表达（告警、流向、活跃度）；
- 可根据设备性能动态降级；
- 可通过指标事件接入监控系统；
- 是"可编辑图纸 + 运行态表达"组合能力的关键层。
示例：
14）UI、事件与扩展能力
相关能力：
createUI(options)/getUI()eventBus事件总线loadPlugin(plugin)与插件生命周期
作用描述（详细）：
- UI 能力让你快速构建可用工作台；
- 事件体系让 CAD 编辑流程可接入业务日志、审批、统计；
- 插件机制支持"先上线核心，再按模块扩展"；
- 有利于长期维护与团队协作开发。
示例：