唯杰地图 logo唯杰地图
VJMAP
EN

quickref/

vjcad/references/quickref/
README.mdVjCAD SDK 快速参考 commands.md命令系统 custom-dialog.md自定义对话框 edit-selection.md编辑、选择与撤销 entities-advanced.md进阶实体 entities-basic.md常用实体 file-operations.md文件操作 geometry.md几何计算 hatch-pattern.md填充图案 input-events.md输入与事件系统 layer-property.md图层与属性 linetype-advanced.md高级线型管理 map-overlay.md地图叠加模式 plugin-development.md插件项目开发 reactor.md反应器系统 svg-import.mdSVG 导入 symbol-system.md符号系统 table-extraction.md表格提取 tile-mode.md瓦片模式 ui-plugin.mdUI 与插件系统 version-control.md版本管理

VjCAD SDK 快速参考

1. 创建实体

常用实体速查表

实体 创建方式 关键属性
LineEnt new LineEnt([x1,y1], [x2,y2]) startPoint, endPoint
CircleEnt new CircleEnt([cx,cy], radius) center, radius
ArcEnt new ArcEnt([cx,cy], r, startAng, endAng) center, radius, startAngle, endAngle
PolylineEnt new PolylineEnt() + setPoints(pts) isClosed, bulgePoints
TextEnt new TextEnt() insertionPoint, text, height, textAlignment
MTextEnt new MTextEnt() insertionPoint, text, height, maxWidth
SplineEnt new SplineEnt() + setFitPoints(pts) 或 setControlPoints(pts) fitPoints, controlPoints, isClosed

重要：创建实体后必须先调用 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. 颜色与属性

颜色代码表

代码 颜色 代码 颜色
1 红色 5 蓝色
2 黄色 6 洋红
3 绿色 7 白色
4 青色 8 灰色

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. 进阶功能

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