# reactor / 反应器总览

vjcad 中"反应器"（Reactor）指的是 **当一个实体（Owner）发生变化时，自动联动更新另一个实体（Reactor）** 的机制。常用于关联标注、几何约束、参数化设计、智能符号等场景。

> 文档：`vjcad/doc/reactor/index.md`、`vjcad/doc/reactor/reactor-system.md`
> 示例：`vjcad/example/reactor/01basic.js` ~ `05lifecycle.js`

## 两条实现路径

| 路径 | 适用 | 关键 API |
|---|---|---|
| ① **基于事件** | 业务自定义联动 / 简单约束 / 统计监控 | `Engine.eventManager.on(CadEvents.EntityModified, ...)` |
| ② **IEntityReactor 接口** | 内置标注关联 / 自定义"反应器实体" | `IEntityReactor` / `ReactorEvent` / `Engine.reactorManager` |

两条路径并不冲突：
- 业务联动一般走 ①，开发量小、适合在已有实体之间临时建立关系；
- 内置 `LinearDimensionEnt` 等标注、以及希望被 DWG 持久化保存的关联，应使用 ②。

## 心智模型

```mermaid
flowchart LR
    A[Owner 实体修改] -->|EntityModified 事件| B(事件监听 / 回调)
    A -->|notifyOwnerChanged| C(IEntityReactor.onOwnerChanged)
    B --> D[手动改 Reactor 实体]
    C --> E[setReactorDirty -> updateFromOwners]
    D --> F[Engine.regen]
    E --> F
```

## 何时用 ① 何时用 ②

- 仅运行时联动、不需要保存到 DWG → ①
- 需要保存到文件、跨会话生效 → ②（标注/复杂自定义实体）
- 内置 `LinearDimensionEnt.setSourceEntities(...)` 已经走 ② → 直接用，不要自己造

## 通用红旗

- 在 `EntityModified` 事件里再修改实体属性会触发递归 → 用 `this.updating` 标志保护，见 `vjcad/example/reactor/04constraint.js`
- 多个反应器同时挂载时，要避免一个反应器创建的实体又触发自己 → 在事件回调里按 `entity.type`、`layer`、`extData` 过滤
- 改完后必须 `Engine.regen()`，否则视图不刷新

## 子文档

- 事件型反应器写法 → [event-based](event-based.md)
- IEntityReactor 接口定义 → [ireactor-interface](ireactor-interface.md)
- 标注关联（最常用）→ [dimension-association](dimension-association.md)
- 几何约束实战 → [constraint](constraint.md)

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/reactor/index.md`、`vjcad/doc/reactor/reactor-system.md`
- 示例：`vjcad/example/reactor/01basic.js` ~ `05lifecycle.js`