> **本文回答**：vjmapext CAD 实体总览 —— 16+ 实体类型、公共生命周期、基础样式。

# CAD 实体主题 (vjmapext)

vjmapext 在 vjmap 之上提供**面向 CAD 的实体系统**：点、线、多段线、圆、弧、椭圆、样条、填充、文字、块、标注、引线、云线，以及用户自定义实体。所有实体均继承 `EntityBase`，拥有统一的样式、变换、图层、自定义属性和序列化能力。

## 子项索引

| 文件 | 主题 |
|---|---|
| [lifecycle](lifecycle.md) | addEntity / deleteEntity / getEntities / 选中 |
| [style-props](style-props.md) | color / lineWidth / layer / lineType / visible 等公共样式 |
| [transform](transform.md) | move / rotate / scale / mirror |
| [line-polyline](line-polyline.md) | LineEnt / PolylineEnt（含 bulge 弧段、双线 dline） |
| [circle-arc-ellipse](circle-arc-ellipse.md) | CircleEnt / ArcEnt / EllipseEnt |
| [spline](spline.md) | SplineEnt 样条 |
| [point](point.md) | PointEnt |
| [hatch](hatch.md) | HatchEnt 填充（内环挖洞 / 图案） |
| [text](text.md) | TextEnt / MTextEnt |
| [font-text](font-text.md) | opentype 字体文字加载 |
| [block-reference](block-reference.md) | BlockDef + BlockRefEnt |
| [svg-import](svg-import.md) | svgToEntities / createBlockRefFromSvg |
| [dimensions](dimensions.md) | LinearDim / AlignedDim / AngleDim / RadialDim |
| [leader](leader.md) | MLeaderEnt 多重引线 |
| [revcloud](revcloud.md) | REVCLOUD 修订云线 |
| [custom-entity](custom-entity.md) | 继承 EntityBase 自定义实体 |

## 实体类型一览

### 基础几何

| 类名 | 注册名 | 说明 |
|---|---|---|
| `PointEnt` | `POINT` | 单个坐标点 |
| `LineEnt` | `LINE` | 直线段（起点 + 终点） |
| `PolylineEnt` | `PLINE` | 多段线 / 多边形，支持 bulge 弧段 |
| `CircleEnt` | `CIRCLE` | 圆 |
| `ArcEnt` | `ARC` | 圆弧 |
| `EllipseEnt` | `ELLIPSE` | 椭圆 / 椭圆弧 |
| `SplineEnt` | `SPLINE` | 样条曲线 |

### 填充与文字

| 类名 | 注册名 | 说明 |
|---|---|---|
| `HatchEnt` | `HATCH` | 填充区域（内外环 / 图案） |
| `TextEnt` | `TEXT` | 单行文字 |
| `MTextEnt` | `MTEXT` | 多行文字 |

### 块与引用

| 类名 | 注册名 | 说明 |
|---|---|---|
| `BlockDef` | — | 块定义（实体集合） |
| `BlockRefEnt` | `INSERT` | 块引用 |

### 标注与引线

| 类名 | 注册名 | 说明 |
|---|---|---|
| `LinearDimEnt` | `DIMLINEAR` | 水平 / 垂直线性标注 |
| `AlignedDimEnt` | `DIMALIGNED` | 对齐标注 |
| `AngleDimEnt` | `DIMANGLE` | 角度标注 |
| `RadialDimEnt` | `DIMRADIUS` | 半径标注 |
| `MLeaderEnt` | `MLEADER` | 多重引线标注 |

所有内置实体通过 `MapCadLayer.registerBuiltins()` 自动注册。

## 实体生命周期

```text
new LineEnt(...)
    ↓ 设置属性
addEntity(entity)
    ↓ 渲染
interact (move / rotate / gripEdit)
    ↓ changed() / styleChanged()
deleteEntity(id) 或 store.delete(id)
```

1. **创建**：`new LineEnt([0,0], [100,0])`
2. **配置**：`entity.color = 0xff0000; entity.lineWidth = 2;`
3. **添加**：`mapcadLayer.addEntity(entity)`
4. **编辑**：拖夹点 / 变换 → 回调里调 `entity.changed()`
5. **删除**：`mapcadLayer.deleteEntity(entity.id)`

## 最小代码

```js
const { MapCadLayer, LineEnt, CircleEnt } = vjmapext;

const mapcadLayer = new MapCadLayer();
map.addControl(mapcadLayer);   // addControl 即 onAdd

const line = new LineEnt([0, 0], [500, 500]);
line.color = 0xff4444;
line.lineWidth = 2;
mapcadLayer.addEntity(line);

const circle = new CircleEnt([250, 250], 200);
circle.color = 0x4488ff;
circle.fillColor = 0x4488ff;
circle.fillOpacity = 0.3;
mapcadLayer.addEntity(circle);
```

## 主题级 Top 3 陷阱

1. **颜色是 0x 十六进制整数**：`0xff0000`，不是 CSS 字符串。
2. **角度单位不一致**：`ArcEnt/EllipseEnt.startAngle`、`rotate()` 变换方法用**弧度**；`TextEnt.rotation` 属性存的是**度**（内部 `rotation += rad*180/π`）。
3. **修改属性后要调 changed() / styleChanged()**：不然不重绘；改几何用 `changed()`，只改颜色用 `styleChanged()` 更快。

## 相关主题

- 实体批量处理 → [batch/](../batch/overview.md)
- 命令系统（LINE/CIRCLE/PLINE/...）→ [drawing/](../drawing/overview.md)
- 实体事件（增删改选）→ [event/](../../../vjmap/references/event/overview.md)
- 性能优化 → [perf/](../../../vjmap/references/perf/overview.md)