VjCAD SDK 快速参考

1. 创建实体

常用实体速查表

重要：创建实体后必须先调用 setDefaults()，再设置 color 等属性。

完整示例

// === 直线 ===
const line = new LineEnt([0, 0], [100, 100]);
line.setDefaults();
line.color = 1;  // 红色
Engine.addEntities(line);

// === 圆 ===
const circle = new CircleEnt([50, 50], 30);
circle.setDefaults();
Engine.addEntities(circle);

// === 圆弧（角度单位：弧度）===
// 方向规则：逆时针为正方向，从 startAngle 到 endAngle 逆时针绘制
// 角度基准：0 = 正右方(3点钟)，逆时针增加：π/2 = 正上方，π = 正左方
const arc = new ArcEnt([50, 50], 30, 0, Math.PI / 2);  // 从 0° 到 90°，逆时针画 1/4 圆
arc.setDefaults();
Engine.addEntities(arc);

// === 多段线（矩形）===
const rect = new PolylineEnt();
rect.setPoints([[0, 0], [100, 0], [100, 60], [0, 60]]);
rect.isClosed = true;
rect.setDefaults();
Engine.addEntities(rect);

// === 带圆弧的多段线 ===
const pline = new PolylineEnt();
pline.setPoints([
    [0, 0],           // 直线段
    [[50, 0], 0.5],   // 弧段（凸度0.5，逆时针）
    [100, 0]
]);
pline.setDefaults();
Engine.addEntities(pline);

// 凸度: bulge = tan(圆心角/4)，90°圆角用 Math.tan(Math.PI/8) ≈ 0.4142，半圆=1.0
// 圆角矩形: 直线段+圆角交替，每个圆角点用 [[x,y], bulge] 格式

// === 单行文字 ===
const text = new TextEnt();
text.insertionPoint = [0, 100];
text.text = "Hello VjCAD";
text.height = 10;
text.textAlignment = 5;  // 中心对齐
text.setDefaults();
Engine.addEntities(text);

// === 多行文字 ===
const mtext = new MTextEnt();
mtext.insertionPoint = [0, 200];
mtext.text = "第一行\n第二行";
mtext.height = 8;
mtext.maxWidth = 80;  // 超出自动换行
mtext.setDefaults();
Engine.addEntities(mtext);

// === 样条曲线（Spline）===
const spline = new SplineEnt();
// 方式1: 拟合点 — 曲线精确经过所有点
spline.setFitPoints([[0, 0], [30, 50], [60, 20], [100, 40]]);
// 方式2: 控制点 — 控制点"拉动"曲线但不经过
// spline.setControlPoints([[0, 0], [30, 50], [60, 20], [100, 40]]);
// 闭合样条：把首点再追加到末尾，如 setFitPoints([...pts, pts[0]])（SPLINE 命令的 C 选项同理）
// isClosed 是只读 getter（首末点重合即 true）；isPeriodic 只是存档标志，绘制时不读，设了也不会闭合
spline.setDefaults();
Engine.addEntities(spline);

Engine.zoomExtents();  // 缩放到全图

文本对齐方式（textAlignment）

7=左上     8=中上     9=右上
4=左中     5=中心     6=右中
1=左下     2=中下     3=右下

---

2. 修改实体

变换操作

const { Point2D, Engine } = vjcad;

// === 移动 ===
entity.move([0, 0], [50, 30]);  // 从 from 移动到 to
Engine.regen();

// === 复制 ===
const copy = entity.clone();
copy.move([0, 0], [100, 0]);
Engine.addEntities(copy);

// === 旋转（绕点旋转，角度为弧度）===
entity.rotate(new Point2D(0, 0), Math.PI / 4);  // 旋转 45°
Engine.regen();

// === 缩放 ===
entity.scale(new Point2D(0, 0), 2.0);  // 放大 2 倍
Engine.regen();

// === 镜像（沿 p1-p2 直线镜像）===
entity.mirror(new Point2D(100, 0), new Point2D(100, 100));
Engine.regen();

注意：move/rotate/scale/mirror 的点参数类型都是 PointInput（Point2D 或 [x,y] 数组均可）。

删除实体

Engine.eraseEntities(entity);           // 删除单个
Engine.eraseEntities([ent1, ent2]);     // 删除多个

---

3. 查询实体

// ⚠️ getEntities / getEntitiesByType 返回 currentSpace.items 原样——含已删除实体（isAlive=false）
// 获取所有存活实体
const all = Engine.getEntities(ent => ent.isAlive);   // 或 Engine.currentSpace.aliveItems

// 按类型获取（同样含已删除实体，需再过滤）
const lines = Engine.getEntitiesByType('LINE').filter(ent => ent.isAlive);
const circles = Engine.getEntitiesByType('CIRCLE').filter(ent => ent.isAlive);
const plines = Engine.getEntitiesByType('PLINE').filter(ent => ent.isAlive);
const texts = Engine.getEntitiesByType('TEXT').filter(ent => ent.isAlive);

// 按条件过滤（条件里带上 isAlive）
const redEnts = Engine.getEntities(ent => ent.isAlive && ent.color === 1);
const layerA = Engine.getEntities(ent => ent.isAlive && ent.layer === "图层A");

选择集操作

// 设置选择集
Engine.ssSetFirst([entity1, entity2]);

// 获取选择集
const { ssGetFirst } = vjcad;
const selected = ssGetFirst();

获取实体范围

// 单个实体：返回 BoundingBox（pt1/pt2/width/height/center/minPoint/maxPoint/minX..maxY）
const bbox = entity.boundingBox();
// 多个实体的组合范围（保证返回 BoundingBox 实例）
const combinedBbox = Engine.getBoundsByEntities([ent1, ent2], "WCS");

---

4. 颜色与属性

颜色代码表

RGB 真彩色

RGB 颜色使用 ColorConverter 工具类：

const { ColorConverter } = vjcad;
entity.color = ColorConverter.createRgbColorIndexFromHexStr("#FFD700");  // 金色

通用属性

entity.color = 1;              // ACI 颜色（1-255），256=随层，0=随块
entity.layer = "图层名";        // 图层
entity.lineType = "HIDDEN";    // 线型：CONTINUOUS, HIDDEN, CENTER
entity.lineTypeScale = 1.0;    // 线型比例

直接赋属性不记录撤销。需要可撤销时改用 Engine 批量方法（自动记录撤销）：Engine.setEntityColor(ents, 1) / Engine.setEntityLayer(ents, "图层名") 可传单个实体或数组；Engine.setEntityLineType / setEntityLineTypeScale / setEntityTransparency 只收数组（传单个实体会在撤销记录里 t.map 抛 TypeError）。

---

5. Engine 核心方法

// 实体操作
Engine.addEntities(entity);           // 添加
Engine.addEntities([ent1, ent2]);     // 批量添加
Engine.eraseEntities(entity);         // 删除

// 视图操作
Engine.zoomExtents();                 // 缩放到全图
Engine.zoomToEntities(entities);      // 缩放到指定实体
Engine.regen();                       // 刷新显示
Engine.regen(true);                   // 完全重绘

---

6. 撤销/重做

关键规则：能否撤销取决于是否记录了撤销标记——Engine.addEntities / eraseEntities / setEntityColor / setEntityLayer 等已自动记录；直接改属性或 entity.move/rotate/scale/mirror 不记录，需先 Engine.markModified(ent)（或事后补 moved_undoMark 等）。start_undoMark / end_undoMark 只负责把多条标记合并成一步撤销（单条标记本身就是一步）。

基本用法

const undoMgr = Engine.undoManager;

// 字符串简写（最常用，默认 category: 'edit'）
undoMgr.start_undoMark('绘制图形');
try {
    // ... 创建/修改/删除实体 ...
    Engine.addEntities(entity);   // 已自动 added_undoMark，切勿再手动记一次（重复记录会在撤销时多删一个无关实体）
} finally {
    undoMgr.end_undoMark();
}

仅在改用底层 Engine.pcanvas.addEntity / Engine.currentSpace.erase 时才手动补 added_undoMark / erased_undoMark。

支持嵌套的包装（推荐在命令中使用）

Engine.startUndoRecord('我的操作');  // 支持嵌套，只有最外层生效
// ... 操作 ...
Engine.endUndoRecord();

撤销/重做

undoMgr.undo();                           // 撤销一步
undoMgr.redo();                           // 重做一步
undoMgr.undoSteps(3);                     // 撤销3步
undoMgr.undoSteps('绘制图形');             // 按名称撤销到最近匹配项（含），无匹配不执行
undoMgr.redoSteps('绘制图形');             // 按名称重做
undoMgr.undoSteps(3, { silent: true });   // 静默撤销（不触发命令行消息）

修改已有实体的撤销模式

undoMgr.start_undoMark('修改颜色');
try {
    Engine.markModified(entity);   // 先标记（记录修改前状态）
    entity.color = 1;              // 再修改属性
    entity.setModified();          // 通知修改完成
} finally {
    undoMgr.end_undoMark();
}

删除实体的撤销

undoMgr.start_undoMark('删除实体');
try {
    Engine.eraseEntities(entities);     // 已自动 erased_undoMark，勿再手动记录（组外重复记录会多出一个空撤销步）
} finally {
    undoMgr.end_undoMark();
}

---

7. 进阶功能

需要更多功能时，请查阅以下文档：

• 常用实体详解 - Line, Circle, Arc, Polyline, Text 完整属性
• 进阶实体 - Hatch 填充, Dimension 标注, Insert 块
• 填充图案 - 80+ 内置图案、自定义图案
• 编辑与选择 - 移动、复制、旋转、选择集、撤销
• 命令系统 - 自定义交互命令
• 输入与事件 - getPoint、getSelections、事件监听
• 图层与属性 - 图层管理、XData
• 几何计算 - 距离、交点、面积
• 文件操作 - 打开、保存 DWG
• UI 用户界面 - 界面插件、面板、对话框、工具栏、浮动工具栏
• 自定义对话框 - 对话框结构与回调
• 插件开发 - Plugin 生命周期、PluginContext
• 反应器 - IEntityReactor、实体联动
• 线型进阶 - 线型文件、线型管理
• SVG 导入 - SVG 转实体
• 符号系统 - 符号库创建与插入
• 地图叠加 - CAD 叠互联网底图
• 瓦片模式 - 大图分块编辑
• 表格提取 - 图纸表格识别
• 版本控制 - 分支、补丁、合并