> **本文回答**：图层用 `Engine.createLayer(name, opts)` 创建、`Engine.setCurrentLayer(name)` 切换、`Engine.getLayerByName / getLayers` 查询；图层有三种独立状态 `layerOn` / `isFrozen` / `isLocked`；"0 图层和当前图层不能冻结 / 删除"**只有图层面板（LAYER 命令 UI）拦截**，API 赋值 `isFrozen` / `layers.remove()` 不设防，需自行跳过 `'0'` 与当前层；按图层取实体 `Engine.getEntities(e => e.layer === name)`（无 getEntitiesByLayer）。

## 一、按子主题挑

| 想做的 | 子主题 |
|---|---|
| 创建图层 / 切换当前图层 | [create-switch](create-switch.md) |
| 显示 / 冻结 / 锁定 | [visibility-frozen-locked](visibility-frozen-locked.md) |
| 列出 / 按图层取实体 | [list-query](list-query.md) |
| 三态对比 / 业务实战 | [layer-states](layer-states.md) |

## 二、心智模型

```
CadDocument
  └─ layers
       ├─ '0'           （默认图层；仅 UI 禁止删除/冻结，API 不设防）
       ├─ '墙体'        layerOn=true / isFrozen=false / isLocked=false
       ├─ '门窗'
       └─ ...
```

每个实体通过 `entity.layer = '墙体'` 或 `entity.layerId = layer.layerId` 关联到图层（`Layer` 的 id 字段名是 `layerId`，没有 `id`）。

```mermaid
graph LR
  Doc[CadDocument]
  Doc --> Layers[Layers 集合]
  Layers --> L0["Layer 0 默认"]
  Layers --> L1["Layer 墙体"]
  Layers --> L2["Layer 门窗"]
  L1 --> E1[LineEnt]
  L1 --> E2[PolylineEnt]
  L2 --> E3[InsertEnt]
```

MCP 参考：`vjcad/doc/layer/layers.md`。

## 三、最快入门

```js
Engine.createLayer('标注层', { color: 1, lineType: 'CONTINUOUS' });
Engine.setCurrentLayer('标注层');

const line = new LineEnt([0, 0], [100, 100]);
line.setDefaults();          // layer 自动 = '标注层'
Engine.addEntities(line);
```

MCP 参考：`vjcad/example/layer/01create.js`、`vjcad/doc/layer/index.md`。

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/layer/index.md`、`vjcad/doc/layer/layers.md`、`vjcad/doc/layer/layer-commands.md`
- 示例：`vjcad/example/layer/01create.js` ~ `08states.js`