入门教程

大约 4 分钟

入门教程

WebCAD 二次开发库，提供 CAD 绘图功能的核心 API。

快速入门（5分钟）

1. 初始化引擎

const { MainView, initCadContainer, Engine, LineEnt, message } = vjcad;

// 创建 MainView 实例，完整配置选项如下：
const cadView = new MainView({
    // 基础配置
    appname: "我的CAD应用",           // 应用名称
    version: "v1.0.0",               // 版本号
    
    // 服务配置
    serviceUrl: env.serviceUrl,       // 后端服务地址
    accessToken: env.accessToken,     // 访问令牌
    accessKey: "",                    // 访问密钥（加密图纸用）
    
    // 界面配置
    sidebarStyle: "none",             // "none" | "left" | "right" | "both"
    
});

// 挂载到 DOM 容器
initCadContainer("map", cadView);

// 等待初始化完成
await cadView.onLoad();

message.info("WebCAD 初始化完成");

2. 创建第一个图形

// 创建直线：起点 (0,0) 到终点 (100,100)
const line = new LineEnt([0, 0], [100, 100]);
line.setDefaults();  // 应用系统默认属性（必须调用）
Engine.addEntities(line);

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

3. 创建自定义命令

const { CommandDefinition, CommandRegistry, PointInputOptions, 
        InputStatusEnum, getPoint, writeMessage } = vjcad;

class MyLineCommand {
    async main() {
        // 获取起点
        const opt1 = new PointInputOptions("指定起点:");
        const result1 = await getPoint(opt1);
        if (result1.status !== InputStatusEnum.OK) return;
        
        // 获取终点（带橡皮筋线）
        const opt2 = new PointInputOptions("指定终点:");
        opt2.useBasePoint = true;
        opt2.basePoint = result1.value;
        const result2 = await getPoint(opt2);
        if (result2.status !== InputStatusEnum.OK) return;
        
        // 创建直线
        const line = new LineEnt(result1.value, result2.value);
        line.setDefaults();
        Engine.addEntities(line);
        
        writeMessage("<br/>直线已创建");
    }
}

// 注册并执行命令
const cmdDef = new CommandDefinition("MYLINE", "绘制直线", MyLineCommand);
CommandRegistry.regist(cmdDef);
await Engine.editor.executerWithOp("MYLINE");

核心 API 速查

常用实体

实体	创建方式	说明
`LineEnt`	`new LineEnt([x1,y1], [x2,y2])`	直线
`CircleEnt`	`new CircleEnt([cx,cy], radius)`	圆
`ArcEnt`	`new ArcEnt([cx,cy], r, startAng, endAng)`	圆弧
`PolylineEnt`	`new PolylineEnt()` + `setPoints()`	多段线
`TextEnt`	`new TextEnt()`	单行文字
`MTextEnt`	`new MTextEnt()`	多行文字

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

输入函数

// 获取点
const result = await getPoint(new PointInputOptions("指定点:"));
if (result.status === InputStatusEnum.OK) {
    const point = result.value;  // {x, y}
}

// 获取选择集
const result = await getSelections(new SelectionInputOptions("选择对象:"));
if (result.status === InputStatusEnum.OK) {
    const entities = result.value;  // 实体数组
}

// 获取数值
const result = await getReal(new RealInputOptions("输入半径:"));
const result = await getInteger(new IntegerInputOptions("输入边数:"));

Engine 核心方法

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

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

// 选择集
Engine.ssSetFirst([entity]);          // 设置选择集
Engine.ssGetFirst();                  // 获取选择集

// 查询
Engine.getEntities();                 // 获取所有实体
Engine.getEntities(ent => ent.layer === "图层A");  // 按条件过滤
Engine.getEntitiesByType('LINE');     // 按类型获取
Engine.getLayers();                   // 获取所有图层

属性设置

const line = new LineEnt([0, 0], [100, 0]);
line.setDefaults();           // 必须先调用

// 设置属性（在 setDefaults 之后）
line.color = 1;               // 颜色（1红 2黄 3绿 4青 5蓝 6洋红 7白）
line.layer = "图层名";         // 图层
line.lineType = "HIDDEN";     // 线型（CONTINUOUS, HIDDEN, CENTER）
line.lineTypeScale = 1.0;     // 线型比例

Engine.addEntities(line);

图层操作

// 创建图层
Engine.createLayer("新图层", {
    color: 1,
    lineType: "CONTINUOUS",
    layerOn: true,
    isFrozen: false,
    isLocked: false
});

// 切换当前图层
Engine.setCurrentLayer("图层名");

// 图层可见性
const layer = Engine.getLayerByName("图层名");
layer.layerOn = false;   // 关闭
layer.isFrozen = true;   // 冻结
layer.isLocked = true;   // 锁定
Engine.regen(true);

撤销操作

const undoMgr = Engine.undoManager;

// 撤销/重做
undoMgr.undo();
undoMgr.redo();

// 撤销分组（多个操作合并为一次撤销）
undoMgr.start_undoMark();
try {
    // 多个操作...
} finally {
    undoMgr.end_undoMark();
}

进阶功能索引

实体系统

常用实体 - Line, Circle, Arc, Polyline, Text
进阶实体 - Hatch, Dimension, Insert, MLeader
填充图案 - 80+ 内置图案、自定义图案、边界创建

命令与交互

命令系统 - 命令定义、预览、状态机、脚本
输入与事件 - 输入函数、事件监听

数据管理

图层与属性 - 图层管理、颜色、线型、XData
几何计算 - 距离、交点、面积、空间索引
文件操作 - 打开、保存、导入导出 DWG
模板成图 - 从模板克隆实体自动成图
SVG 导入 - 导入 SVG 矢量图形
高级线型 - 自定义线型、复杂线型、LIN 文件
版本管理 - 分支、版本保存、合并、冲突解决
瓦片模式 - 大图纸打开、区域/图层编辑
地图叠加 - CAD 与 vjmap 地图融合
互联网地图叠加 - 高德/天地图底图叠加与坐标对齐
表格提取 - 从图纸中提取表格数据

编辑操作

编辑与选择 - 移动、复制、旋转、选择、撤销

扩展开发

UI与插件 - Ribbon、内置对话框、插件系统
自定义对话框 - 模态/非模态对话框、拾取点和实体
反应器系统 - 实体关联、关联标注
符号系统 - 符号库创建、管理、插入

常见模式

实体创建标准流程

const entity = new XxxEnt(...);  // 1. 创建实体
entity.setDefaults();            // 2. 应用默认属性（必须）
entity.color = 1;                // 3. 设置自定义属性（可选）
Engine.addEntities(entity);      // 4. 添加到画布

命令类标准结构

class MyCommand {
    async main() {
        Engine.undoManager.start_undoMark();
        try {
            // 命令逻辑
        } finally {
            Engine.undoManager.end_undoMark();
            Engine.clearPreview();
        }
    }
}

事件监听

Engine.eventManager.on(CadEvents.EntityAdded, (args) => {
    console.log('实体已添加:', args.entity.type);
});

// 可取消事件
Engine.eventManager.on(CadEvents.EntityErasing, (args) => {
    if (args.entity.layer === "保护图层") {
        args.cancel = true;  // 阻止删除
    }
});