块插入实体 (InsertEnt)

大约 4 分钟

块插入实体 (InsertEnt)

InsertEnt 表示块定义的一个实例，将块定义插入到图纸中。

概述

块插入是对块定义（BlockDefinition）的引用，可以在图纸中重复使用同一块定义，并应用不同的位置、旋转和缩放。

构造函数

import { InsertEnt, Engine, Point2D } from 'vjcad';

const doc = Engine.currentDoc;
const blockDef = doc.blocks.itemByName('我的块');

// 推荐写法：分步设置属性
const insert1 = new InsertEnt();
insert1.blockId = blockDef.blockId;    // 块ID（8位GUID字符串，必须通过 blockDef.blockId 获取）
insert1.insertionPoint = [100, 100];   // 插入点（支持数组）
insert1.scaleFactor = 1;               // 缩放因子
insert1.rotation = 0;                  // 旋转角度（弧度）
insert1.setDefaults();

// 构造函数参数写法
const insert2 = new InsertEnt(blockDef.blockId, [100, 100], 1, 0);
insert2.setDefaults();

注意

blockId 参数必须传入从 blockDef.blockId 获取的 8 位 GUID 字符串，不能直接传入块名字符串。

简化写法

insertionPoint 属性支持 [x, y] 数组形式的坐标。

属性

属性	类型	说明
`blockId`	string	块ID（8位GUID字符串，通过 `blockDef.blockId` 获取）
`insertionPoint`	Point2D	插入点位置
`scaleFactor`	number	缩放因子
`rotation`	number	旋转角度（弧度）
`isReversedX`	boolean	X轴是否镜像
`isReversedY`	boolean	Y轴是否镜像
`name`	string	块名称（只读，根据 blockId 从文档获取）

属性文字 (Attributes)

块插入支持属性文字，可以为块的每个实例设置不同的文字内容。

addAttribute 方法

insert.addAttribute({
  tag: string,           // 属性标签（必须与块定义中的属性定义匹配）
  textString?: string,   // 属性文字内容
  height?: number,       // 文字高度（重要：必须显式指定）
  position?: Point2D,    // 位置偏移
  rotation?: number,     // 旋转角度
  invisible?: boolean,   // 是否隐藏
  color?: number,        // 颜色
});

height 参数

addAttribute 方法的 height 参数是可选的：

不传 height：自动使用块定义中属性文字的原始高度（乘以缩放因子）
传入 height：使用指定的高度值

// ✅ 推荐：不传 height，自动使用块定义中的高度
insert.addAttribute({ tag: "NAME", textString: "零件A" });

// ✅ 也可以：显式指定高度（覆盖块定义中的高度）
insert.addAttribute({ tag: "NAME", textString: "零件A", height: 30 });

示例

插入块

import { Engine, InsertEnt, Point2D } from 'vjcad';

const doc = Engine.currentDoc;

// 假设已有名为 "标准件" 的块定义
const blockDef = doc.blocks.itemByName('标准件');

const insert = new InsertEnt();
insert.blockId = blockDef.blockId;
insert.insertionPoint = new Point2D(100, 100);
insert.setDefaults();

Engine.addEntities(insert);

创建块并插入

import { Engine, InsertEnt, LineEnt, CircleEnt, Point2D } from 'vjcad';

const doc = Engine.currentDoc;

// 1. 创建块定义
const blockName = '十字标记';

let blockDef = doc.blocks.itemByName(blockName);
if (!blockDef) {
  blockDef = doc.blocks.add(blockName);
  blockDef.basePoint = new Point2D(0, 0);

  // 添加实体到块
  const hLine = new LineEnt(new Point2D(-10, 0), new Point2D(10, 0));
  const vLine = new LineEnt(new Point2D(0, -10), new Point2D(0, 10));
  const circle = new CircleEnt(new Point2D(0, 0), 5);
  
  hLine.setDefaults();
  vLine.setDefaults();
  circle.setDefaults();

  blockDef.addEntity(hLine);
  blockDef.addEntity(vLine);
  blockDef.addEntity(circle);
}

// 2. 插入块的多个实例
const positions = [
  new Point2D(50, 50),
  new Point2D(150, 50),
  new Point2D(100, 150)
];

for (const pos of positions) {
  const insert = new InsertEnt();
  insert.blockId = blockDef.blockId;
  insert.insertionPoint = pos;
  insert.setDefaults();
  Engine.addEntities(insert);
}

不同比例和旋转的插入

import { Engine, InsertEnt, Point2D } from 'vjcad';

const doc = Engine.currentDoc;
const blockDef = doc.blocks.itemByName('零件A');

// 原始大小
const insert1 = new InsertEnt();
insert1.blockId = blockDef.blockId;
insert1.insertionPoint = new Point2D(0, 0);
insert1.setDefaults();

// 放大 2 倍
const insert2 = new InsertEnt();
insert2.blockId = blockDef.blockId;
insert2.insertionPoint = new Point2D(200, 0);
insert2.scaleFactor = 2;
insert2.setDefaults();

// 旋转 45°
const insert3 = new InsertEnt();
insert3.blockId = blockDef.blockId;
insert3.insertionPoint = new Point2D(0, 200);
insert3.rotation = Math.PI / 4;
insert3.setDefaults();

// X轴镜像
const insert4 = new InsertEnt();
insert4.blockId = blockDef.blockId;
insert4.insertionPoint = new Point2D(200, 200);
insert4.isReversedX = true;
insert4.setDefaults();

Engine.addEntities([insert1, insert2, insert3, insert4]);

带属性文字的块

import { Engine, InsertEnt, LineEnt, TextEnt, TextAlignmentEnum } from 'vjcad';

const doc = Engine.currentDoc;
const blockName = 'TitleBlock';

// 1. 创建带属性定义的块
let blockDef = doc.blocks.itemByName(blockName);
if (!blockDef) {
  blockDef = doc.blocks.add(blockName);
  blockDef.basePoint = [0, 0];

  // 矩形边框
  const line1 = new LineEnt([0, 0], [60, 0]);
  const line2 = new LineEnt([60, 0], [60, 20]);
  const line3 = new LineEnt([60, 20], [0, 20]);
  const line4 = new LineEnt([0, 20], [0, 0]);
  [line1, line2, line3, line4].forEach(l => l.setDefaults());

  // 属性定义：设置 tag 和 prompt
  const attrName = new TextEnt([5, 12], "名称", 4, 0, TextAlignmentEnum.Left);
  attrName.tag = "NAME";           // 属性标签
  attrName.prompt = "请输入名称";   // 插入提示
  attrName.setDefaults();

  const attrCode = new TextEnt([5, 4], "编号", 4, 0, TextAlignmentEnum.Left);
  attrCode.tag = "CODE";
  attrCode.prompt = "请输入编号";
  attrCode.setDefaults();

  blockDef.addEntity(line1);
  blockDef.addEntity(line2);
  blockDef.addEntity(line3);
  blockDef.addEntity(line4);
  blockDef.addEntity(attrName);
  blockDef.addEntity(attrCode);
}

// 2. 插入块并设置属性值
const insert = new InsertEnt();
insert.blockId = blockDef.blockId;
insert.insertionPoint = [10, 50];
insert.setDefaults();

// 不传 height，自动使用块定义中属性文字的原始高度
insert.addAttribute({ tag: "NAME", textString: "零件A" });
insert.addAttribute({ tag: "CODE", textString: "P-001" });

Engine.addEntities(insert);