块定义 (BlockDefinition)

大约 3 分钟

块定义 (BlockDefinition)

块定义是一组实体的集合，可以在图纸中重复使用。

概述

块是 CAD 中重要的组织机制，将多个实体组合成一个可重用的单元。修改块定义会影响所有引用该块的插入实例。

创建块定义

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

const doc = Engine.currentDoc;

// 创建块定义（推荐方式：通过 blocks.add 传入块名）
const blockDef = doc.blocks.add('标准螺栓');
blockDef.basePoint = [0, 0];  // 块的基点（支持数组形式）

// 创建块内实体（支持 [x, y] 数组形式）
const circle = new CircleEnt([0, 0], 10);
circle.setDefaults();

const line1 = new LineEnt([-10, 0], [10, 0]);
line1.setDefaults();

const line2 = new LineEnt([0, -10], [0, 10]);
line2.setDefaults();

// 添加实体到块
blockDef.addEntity(circle);
blockDef.addEntity(line1);
blockDef.addEntity(line2);

属性

属性	类型	说明
`name`	string	块名称（唯一）
`basePoint`	Point2D	块的基点（插入参考点）
`blockId`	string	块ID（8位GUID字符串）
`items`	EntityBase[]	块内实体集合
`isLayout`	boolean	是否为布局块
`isXref`	boolean	是否为外部引用

方法

addEntity() / add() - 添加实体

const blockDef = doc.blocks.add('新块');

const line = new LineEnt([0, 0], [100, 0]);  // 支持数组形式
line.setDefaults();

blockDef.addEntity(line);  // 推荐
// 或
blockDef.add(line);        // 等效

remove() - 移除实体

blockDef.remove(line);

count - 获取实体数量

console.log(`实体数量: ${blockDef.count}`);

块集合管理 (Blocks)

import { Engine } from 'vjcad';

const doc = Engine.currentDoc;
const blocks = doc.blocks;

// 创建新块（传入字符串名称）
const blockDef = blocks.add('我的块');

// 检查块是否存在
if (blocks.has('标准件')) {
  console.log('块存在');
}

// 按名称查找块
const myBlock = blocks.itemByName('我的块');

// 按ID查找块
const blockById = blocks.itemById('abcdefgh');

// 获取块数量
console.log(`块数量: ${blocks.count}`);

// 遍历所有块
for (const block of blocks.items) {
  console.log(`块名: ${block.name}, 实体数: ${block.count}`);
}

// 获取命名块（排除匿名块和布局块）
const namedBlocks = blocks.getNamedItems();

// 删除块定义
blocks.remove(blockDef);

完整示例

创建可重用的图框块

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

function createTitleBlock() {
  const doc = Engine.currentDoc;
  
  // 创建块定义
  const blockDef = doc.blocks.add('A4图框');
  blockDef.basePoint = [0, 0];
  
  // 外框 (A4: 297 x 210) - 使用简化接口
  const outerFrame = new PolylineEnt();
  outerFrame.setPoints([
      [0, 0],
      [297, 0],
      [297, 210],
      [0, 210]
  ]);
  outerFrame.isClosed = true;
  outerFrame.setDefaults();
  blockDef.addEntity(outerFrame);
  
  // 内框 (留边距)
  const innerFrame = new PolylineEnt();
  innerFrame.setPoints([
      [25, 5],
      [292, 5],
      [292, 205],
      [25, 205]
  ]);
  innerFrame.isClosed = true;
  innerFrame.setDefaults();
  blockDef.addEntity(innerFrame);
  
  // 标题栏分隔线
  const titleLine = new LineEnt([200, 5], [200, 45]);
  titleLine.setDefaults();
  blockDef.addEntity(titleLine);
  
  // 标题
  const titleText = new TextEnt();
  titleText.insertionPoint = [246, 25];
  titleText.text = '图纸名称';
  titleText.height = 5;
  titleText.textAlignment = TextAlignmentEnum.Center;
  titleText.setDefaults();
  blockDef.addEntity(titleText);
  
  return blockDef;
}

// 使用图框
const titleBlock = createTitleBlock();

const insert = new InsertEnt();
insert.blockId = titleBlock.blockId;
insert.insertionPoint = [0, 0];  // 支持数组形式
insert.setDefaults();

Engine.addEntities(insert);

从选择创建块

import { 
  Engine, 
  InsertEnt,
  Point2D,
  SelectionInputOptions,
  PointInputOptions,
  InputStatusEnum
} from 'vjcad';

async function createBlockFromSelection() {
  const doc = Engine.currentDoc;
  
  // 选择实体
  const selOpt = new SelectionInputOptions('选择要创建块的实体:');
  const selResult = await Engine.getSelections(selOpt);
  
  if (selResult.status !== InputStatusEnum.OK || !selResult.selections?.length) {
    Engine.writeMessage('未选择任何实体');
    return;
  }
  
  // 获取基点
  const ptOpt = new PointInputOptions('指定块的基点:');
  const ptResult = await Engine.getPoint(ptOpt);
  
  if (ptResult.status !== InputStatusEnum.OK) {
    return;
  }
  
  const basePoint = ptResult.value as Point2D;
  
  // 创建块定义
  const blockName = `Block_${Date.now()}`;
  const blockDef = doc.blocks.add(blockName);
  blockDef.basePoint = basePoint;
  
  // 复制选中实体到块（相对于基点）
  for (const ent of selResult.selections) {
    const cloned = ent.clone();
    // 移动到相对于基点的位置
    cloned.move(basePoint, [0, 0]);  // 支持数组形式
    blockDef.addEntity(cloned);
  }
  
  // 删除原实体，替换为块插入
  Engine.eraseEntities(selResult.selections);
  
  const insert = new InsertEnt();
  insert.blockId = blockDef.blockId;
  insert.insertionPoint = basePoint;  // Point2D 或 [x, y]
  insert.setDefaults();
  
  Engine.addEntities(insert);
  
  Engine.writeMessage(`已创建块: ${blockName}`);
}

注意事项

块名唯一性：每个块定义的名称必须唯一，blocks.add() 传入已存在的名称会返回现有块
基点选择：合理选择块的 basePoint，方便后续插入定位
嵌套块：块可以包含其他块的插入实例
修改传播：修改块定义会影响所有插入实例