selection-api

本文回答：Engine.ssGetFirst() / ssSetFirst([...]) 操作"当前选择集"，Engine.getEntities() / getEntitiesByType() 查询全部 / 按类型；按图层用 Engine.getEntities(e => e.layer === name)（没有 getEntitiesByLayer）；Engine.getEntities(filter) 用任意条件过滤。

一、当前选择集

// 设置：传数组（空数组 = 清空）
Engine.ssSetFirst([line1, line2, circle]);
Engine.ssSetFirst([]);

// 获取：返回 EntityBase[]
const sel = Engine.ssGetFirst();
console.log(sel.length);

// 追加（保留已选）
Engine.ssSetFirst([...Engine.ssGetFirst(), newEntity]);

// 全选：getEntities() 含已 erase 的实体（isAlive=false），也不排除关闭/冻结/锁定层，不能直接用
Engine.ssSetFirst(Engine.currentSpace.aliveItems.filter(
  e => Engine.currentDoc.layers.isLayerSelectable(e.layerId)
));
// 或交互命令：await Engine.editor.executerWithOp('SELECTALL');

MCP 参考：vjcad/example/selection/01setselection.js、02getselection.js、vjcad/doc/selection/index.md。

二、按类型 / 图层 / 过滤函数取实体

// 1. 单类型
const lines   = Engine.getEntitiesByType('LINE');
const circles = Engine.getEntitiesByType('CIRCLE');

// 2. 多类型：getEntitiesByType 只收单个 string，多类型用 getEntities 过滤
const lac = Engine.getEntities(e => ['LINE','CIRCLE','ARC'].includes(e.type));

// 3. 按图层（无 getEntitiesByLayer；e.layer 返回图层名）
const layerA = Engine.getEntities(e => e.layer === '图层A');

// 4. 自由过滤
const redLines = Engine.getEntities(ent => ent.type === 'LINE' && ent.color === 1);
const bigCircles = Engine.getEntities(
  ent => ent.type === 'CIRCLE' && ent.radius > 10
);

MCP 参考：vjcad/example/selection/03getbytype.js、04getbyfilter.js、vjcad/doc/selection/index.md。

三、type 字符串

const dims = Engine.getEntities(e => e.isAlive && e.type === 'CUSTOM' && e.customType?.endsWith('_DIMENSION'));

完整对照见 vjcad/doc/selection/index.md 与 vjcad/doc/command/api-reference.md。

四、与交互式选择互通

// 交互式选择后再覆盖到选择集
const result = await getSelections(new SelectionInputOptions());   // 无参构造
if (result.status === InputStatusEnum.OK) {
  Engine.ssSetFirst(result.value);
}

详见 input/get-selections。

五、综合：选择 + 高亮 + 编辑模板

const lines = Engine.getEntitiesByType('LINE');
Engine.ssSetFirst(lines);
Engine.highLightEntities(lines);

setTimeout(() => Engine.clearHighLight(), 3000);

反例

• Engine.getEntities('LINE') 把 getEntities 当 getEntitiesByType 用：getEntities 接受过滤函数，不是字符串。
• ssSetFirst(entity) 传单个实体：得传数组。
• 选完后没高亮 / 没设进 ssSetFirst：用户面板看不到反馈。
• ⚠️ getEntities() / getEntitiesByType() 包含已删除实体：erase 是软删（isAlive=false，留在 items 供 undo），这两个 API 返回 [...items] 不过滤。统计/遍历存活实体用 currentSpace.aliveItems 或 getEntities(e => e.isAlive)。

参考（官方文档 MCP）

• 文档：vjcad/doc/selection/index.md、vjcad/doc/selection/entity-selection.md
• 示例：vjcad/example/selection/01setselection.js ~ 04getbyfilter.js