命令 API 参考

大约 6 分钟

命令 API 参考

本章汇总命令开发中常用的 API，作为快速参考手册。

Engine 核心对象

Engine 是 WebCAD 的核心单例对象，提供对各种子系统的访问。

常用属性

import { Engine } from 'vjcad';

// 画布控制
Engine.pcanvas

// 当前文档
Engine.currentDoc

// 撤销管理器
Engine.undoManager

// 坐标转换
Engine.trans

// 当前空间（模型空间或图纸空间）
Engine.currentSpace

// 活动文档
Engine.activeDocument

// 系统变量
Engine.CECOLOR       // 当前颜色
Engine.OFFSETDIST    // 偏移距离

pcanvas 方法

// 添加实体
Engine.pcanvas.addEntity(entity: EntityBase): EntityBase

// 图形重生成
Engine.pcanvas.regen(): void         // 局部更新，只重绘已修改的实体
Engine.pcanvas.regen(true): void     // 完全重绘，清除并重新绘制所有图形
Engine.pcanvas.redraw(): void        // 更新视图变换后渲染（平移/缩放/旋转）
Engine.pcanvas.render(): void        // 最底层渲染，只执行GPU绘制

// 高亮
Engine.pcanvas.highLightEntities(entities: EntityBase[]): void
Engine.pcanvas.clearHighLight(): void
Engine.pcanvas.clearGrip(): void

// 缩放
Engine.pcanvas.zoomExtents(): void

// 绘制控制
Engine.pcanvas.drawControl.drawPreviewEntity(entity: EntityBase): void
Engine.pcanvas.drawControl.drawPreviewEntities(entities: EntityBase[]): void
Engine.pcanvas.drawControl.drawHighLightEntity(entity: EntityBase): void
Engine.pcanvas.drawControl.previewGraphics.clear(): void
Engine.pcanvas.drawControl.setPreviewPosition(point: Point2D): void
Engine.pcanvas.drawControl.setPreviewRotation(angle: number): void
Engine.pcanvas.drawControl.setPreviewScale(sx: number, sy: number): void
Engine.pcanvas.drawControl.resetPreview(): void

undoManager 方法

// 撤销标记
Engine.undoManager.start_undoMark(): void
Engine.undoManager.end_undoMark(): void

// 记录操作
Engine.undoManager.added_undoMark(entities: EntityBase[]): void
Engine.undoManager.erased_undoMark(entities: EntityBase[]): void
Engine.undoManager.moved_undoMark(entities: EntityBase[], from: Point2D, to: Point2D): void
Engine.undoManager.rotate_undoMark(entities: EntityBase[], center: Point2D, angle: number): void
Engine.undoManager.mirrored_undoMark(entities: EntityBase[], pt1: Point2D, pt2: Point2D): void
Engine.undoManager.modEntity_undoMark(entity: EntityBase): void
Engine.undoManager.modLine_undoMark(line: LineEnt): void
Engine.undoManager.modArc_undoMark(arc: ArcEnt): void
Engine.undoManager.modRay_undoMark(ray: RayEnt): void

trans 坐标转换

// 画布坐标转世界坐标
Engine.trans.CanvasToWcs(canvasPoint: Point2D): Point2D

// 世界坐标转画布坐标
Engine.trans.WcsToCanvas(worldPoint: Point2D): Point2D

currentDoc / currentSpace

// 当前文档
Engine.currentDoc.currentSpace   // 当前空间
Engine.currentDoc.CLAYER         // 当前图层

// 当前空间操作
Engine.currentDoc.currentSpace.items      // 所有实体
Engine.currentDoc.currentSpace.erase(entities: EntityBase[]): void
Engine.currentDoc.currentSpace.addEntities(entities: EntityBase[]): void

输入函数

getPoint

获取点坐标输入。

import { getPoint, PointInputOptions, InputStatusEnum } from 'vjcad';

const options = new PointInputOptions("指定点:");
const result = await getPoint(options);

if (result.status === InputStatusEnum.OK) {
  const point: Point2D = result.value;
}

PointInputOptions 属性：

属性	类型	说明
`message`	string	提示消息
`keywords`	string[]	关键字列表
`useBasePoint`	boolean	是否使用基点（橡皮筋线）
`basePoint`	Point2D	基点坐标
`useOsnap`	boolean	是否启用对象捕捉
`callback`	function	鼠标移动回调
`allowNumberResult`	boolean	是否允许数字输入
`useOrthoMode`	boolean	是否使用正交模式
`forceOrthomode`	boolean	是否强制正交
`hideRubberBand`	boolean	是否隐藏橡皮筋线

返回值 PointInputResult：

属性	类型	说明
`status`	number	输入状态
`value`	Point2D	点坐标
`stringResult`	string	关键字结果
`numberValue`	number	数字结果（需 allowNumberResult）

getSelections

获取多个实体选择。

import { getSelections, SelectionInputOptions, InputStatusEnum } from 'vjcad';

const options = new SelectionInputOptions();
const result = await getSelections(options);

if (result.status === InputStatusEnum.OK) {
  const entities: EntityBase[] = result.value;
}

SelectionInputOptions 属性：

属性	类型	说明
`useOsnap`	boolean	是否启用对象捕捉

返回值 SelectionSetInputResult：

属性	类型	说明
`status`	number	输入状态
`value`	EntityBase[]	选中的实体数组
`stringResult`	string	关键字结果

getEntity

获取单个实体选择。

import { getEntity, SelectionSetInputOptions, InputStatusEnum } from 'vjcad';

const options = new SelectionSetInputOptions("选择一个对象:");
const result = await getEntity(options);

if (result.status === InputStatusEnum.OK) {
  const entity = result.pickedEntity;
  const pickPoint = result.pickedPoint;
}

SelectionSetInputOptions 属性：

属性	类型	说明
`message`	string	提示消息
`keywords`	string[]	关键字列表
`useNestedPick`	boolean	是否允许嵌套选择

返回值 EntityPickResult：

属性	类型	说明
`status`	number	输入状态
`pickedEntity`	EntityBase	拾取的实体
`pickedPoint`	Point2D	拾取点坐标
`stringResult`	string	关键字结果

getString

获取字符串输入。

import { Engine, StringInputOptions, InputStatusEnum } from 'vjcad';

const options = new StringInputOptions("输入文本:");
const result = await Engine.getString(options);

if (result.status === InputStatusEnum.OK) {
  const text: string = result.value;
}

getInteger

获取整数输入。

import { Engine, IntegerInputOptions, InputStatusEnum } from 'vjcad';

const options = new IntegerInputOptions("输入数量:");
options.defaultValue = 10;
options.lowerLimit = 1;
options.upperLimit = 100;

const result = await Engine.getInteger(options);

if (result.status === InputStatusEnum.OK) {
  const count: number = result.value;
}

getReal

获取实数输入。

import { Engine, RealInputOptions, InputStatusEnum } from 'vjcad';

const options = new RealInputOptions("输入比例:");
options.defaultValue = 1.0;

const result = await Engine.getReal(options);

if (result.status === InputStatusEnum.OK) {
  const scale: number = result.value;
}

getKeyword

获取关键字选择。

import { Engine, KeywordInputOptions, InputStatusEnum } from 'vjcad';

const options = new KeywordInputOptions("选择模式 [窗口(W)/交叉(C)]:");
options.keywords = ["W", "C"];
options.defaultKeyword = "W";

const result = await Engine.getKeyword(options);

if (result.status === InputStatusEnum.OK) {
  const keyword: string = result.value;
}

InputStatusEnum

输入状态枚举值。

值	名称	说明
5100	`OK`	成功获取输入
-5002	`Cancel`	用户取消
-5005	`Keyword`	用户输入关键字
3	`EnterOrSpace`	用户按回车或空格
4	`IsNumber`	用户输入数字
5000	`None`	无输入
-5001	`Error`	发生错误

输出函数

writeMessage

在命令行输出消息。

import { writeMessage } from 'vjcad';

writeMessage("<br/>操作完成。");
writeMessage(`<br/>已选择 ${count} 个实体。`);

ssSetFirst

清空选择集。

import { ssSetFirst } from 'vjcad';

ssSetFirst([]);  // 清空当前选择

实体操作

实体基类方法

所有实体都继承自 EntityBase，具有以下通用方法：

// 设置默认属性（图层、颜色等）
entity.setDefaults(): void

// 克隆实体
entity.clone(): EntityBase

// 几何变换
entity.move(from: Point2D, to: Point2D): void
entity.rotate(center: Point2D, angle: number): void
entity.mirror(pt1: Point2D, pt2: Point2D): void
entity.scale(center: Point2D, factor: number): void

// 从另一实体复制默认属性
entity.fromDefaultProps(source: EntityBase): void

实体属性

// 通用属性
entity.id: number          // 实体ID
entity.type: string        // 实体类型
entity.color: number       // 颜色
entity.layer: string       // 图层名
entity.layerId: number     // 图层ID

常用实体类型

类型	类名	type 值
直线	`LineEnt`	"LINE"
圆	`CircleEnt`	"CIRCLE"
圆弧	`ArcEnt`	"ARC"
多段线	`PolylineEnt`	"PLINE"
单行文字	`TextEnt`	"TEXT"
多行文字	`MTextEnt`	"MTEXT"
块参照	`InsertEnt`	"INSERT"
椭圆	`EllipseEnt`	"ELLIPSE"
样条曲线	`SplineEnt`	"SPLINE"
填充	`HatchEnt`	"HATCH"
图像	`ImageEnt`	"IMAGE"
点	`DotEnt`	"DOT"
射线	`RayEnt`	"RAY"
构造线	`XLineEnt`	"XLINE"
实体填充	`SolidEnt`	"SOLID"

创建实体示例

import { 
  LineEnt, 
  CircleEnt, 
  ArcEnt, 
  PolylineEnt, 
  BulgePoint,
  Point2D 
} from 'vjcad';

// 创建直线
const line = new LineEnt(
  new Point2D(0, 0),
  new Point2D(100, 100)
);
line.setDefaults();

// 创建圆
const circle = new CircleEnt(
  new Point2D(50, 50),  // 圆心
  25                     // 半径
);
circle.setDefaults();

// 创建圆弧
const arc = new ArcEnt(
  new Point2D(50, 50),  // 圆心
  25,                    // 半径
  0,                     // 起始角度（弧度）
  Math.PI                // 结束角度（弧度）
);
arc.setDefaults();

// 创建多段线
const pline = new PolylineEnt();
pline.bulgePoints.add(new BulgePoint(new Point2D(0, 0), 0));
pline.bulgePoints.add(new BulgePoint(new Point2D(100, 0), 0));
pline.bulgePoints.add(new BulgePoint(new Point2D(100, 100), 0));
pline.isClosed = true;
pline.setDefaults();

命令注册

CommandDefinition

import { CommandDefinition, CommandOptions } from 'vjcad';

const options = new CommandOptions();
options.useAutoComplete = true;

const definition = new CommandDefinition(
  'MYCMD',          // 命令名
  '命令描述',        // 描述
  MyCommand,        // 命令类
  options           // 选项
);

CommandRegistry

import { CommandRegistry } from 'vjcad';

// 注册命令
CommandRegistry.regist(definition);

// 查询命令
const cmd = CommandRegistry.item('MYCMD');

// 所有命令
const allCommands = CommandRegistry.items;

插件中注册命令

// 在 onActivate 中
context.registerCommand('MYCMD', '命令描述', MyCommand);

// 在 onDeactivate 中
context.unregisterCommand('MYCMD');

辅助函数

startUndoMark / endUndoMark

便捷的撤销标记函数：

import { startUndoMark, endUndoMark } from 'vjcad';

startUndoMark();
try {
  // 操作...
} finally {
  endUndoMark();
}

regen

重新生成图形（局部更新已修改的实体）：

import { regen } from 'vjcad';

// 局部更新：只重绘已 setModified() 标记的实体
regen();  // 等同于 Engine.regen()

// 完全重绘：清除并重新绘制所有图形
Engine.regen(true);

方法区别

render(): 最底层，只调用GPU渲染当前帧
redraw(): 更新视图变换（位置/缩放/旋转），然后调用render
regen(): 局部更新，只重新渲染已setModified的实体
regen(true): 完全重绘，清除并重新绘制所有图形

几何计算

Point2D

import { Point2D } from 'vjcad';

const p1 = new Point2D(0, 0);
const p2 = new Point2D(100, 100);

// 属性
p1.x
p1.y

// 方法
p1.clone(): Point2D
p1.distanceTo(p2): number
p1.move(from: Point2D, to: Point2D): void
p1.rotate(angle: number, center?: Point2D): void
p1.offset(delta: Point2D): void

GeometryCalculator

几何计算工具类：

import { GeometryCalculator } from 'vjcad';

// 直线与直线交点
GeometryCalculator.LineToLine(line1, line2): Point2D[]

// 直线与圆交点
GeometryCalculator.LineToCircle(line, circle): Point2D[]

// 直线与圆弧交点
GeometryCalculator.LineToArc(line, arc): Point2D[]

// 直线与多段线交点
GeometryCalculator.LineToPline(line, pline): Point2D[]

// 圆与圆交点
GeometryCalculator.CircleToCircle(circle1, circle2): Point2D[]

// 判断点在直线哪一侧
GeometryCalculator.witchSidePointToLine(lineStart, lineEnd, point): number

角度常量

import { ANGLE_90, ANGLE_180, ANGLE_270 } from 'vjcad';

// 90度（弧度）
ANGLE_90   // Math.PI / 2

// 180度（弧度）
ANGLE_180  // Math.PI

// 270度（弧度）
ANGLE_270  // Math.PI * 3 / 2

角度工具

import { normalizeAngleAlt, polarToCartesian } from 'vjcad';

// 规范化角度到 [-PI, PI]
normalizeAngleAlt(angle: number): number

// 极坐标转笛卡尔坐标
polarToCartesian(center: Point2D, angle: number, distance: number): Point2D

坐标工具

import { 
  getAngleBetweenPoints, 
  rotatePointAroundCenter 
} from 'vjcad';

// 计算两点间角度
getAngleBetweenPoints(p1: Point2D, p2: Point2D): number

// 绕中心点旋转
rotatePointAroundCenter(center: Point2D, point: Point2D, angle: number): Point2D

通用工具

import { distance, formatNumberEx } from 'vjcad';

// 计算两点距离
distance(p1: Point2D, p2: Point2D): number

// 格式化数字
formatNumberEx(value: number, decimals: number): string