# insert / 插入资源总览

> 文档：`vjcad/doc/insert/index.md`
> 示例：`vjcad/example/insert/svg/`、`vjcad/example/insert/symbol/`、`vjcad/example/insert/vectorize/`

`insert` 模块用于把 **外部资源** 转成 vjcad 实体并插入到当前文档，三大子领域：

| 子领域 | 用途 | 关键 API / 命令 |
|---|---|---|
| **符号库** | 用户预制图形片段（图块/符号） | `getLocalStorageService()` / `Engine.service` / `mergeSymbolToDocument` / `insertSymbolInteractive` |
| **SVG 导入** | 任意 SVG 文件转成实体 | `IMPORTSVG` 命令 / `getWebCadCoreService().parseSvgToWebcad(...)` |
| **图片转矢量** | 栅格图片（PNG/JPG）→ 矢量实体 | `INSERTIMAGE` 命令 / `VectroizeConfig` |

## 三种插入路径对比

```mermaid
flowchart LR
    A[本地 / 服务端符号<br/>vcadData] --> M[parseSymbolVcadData<br/>→ symbolDoc] --> P[mergeSymbolToDocument]
    B[SVG 字符串] --> S[getWebCadCoreService<br/>.parseSvgToWebcad] --> N[CadDocument.fromDb] --> P
    C[PNG / JPG / 拖拽 / 粘贴] --> V[VectroizeService<br/>convertToSvg] --> S
    P --> E[Engine.pcanvas.addEntity<br/>不记 undo]
```

三条路径在最后都走 **临时 CadDocument → 把 *Model 块里的实体 clone 后 move 到插入点 → `Engine.pcanvas.addEntity`**（`mergeSymbolToDocument` 内部逐个 `pcanvas.addEntity`，**不是** `Engine.addEntities`，**不记录 undo**）。需要可撤销时自己包一层：

```js
Engine.startUndoMark('插入符号');
const ents = mergeSymbolToDocument(symbolDoc, insertPoint, basePoint, 1, 0, false);
if (ents.length) Engine.undoManager.added_undoMark(ents);
Engine.endUndoMark();
Engine.regen();
```

## 子文档

- 符号创建（本地 / 服务端）→ [symbol-create](symbol-create.md)
- 符号插入（基础 / 交互式 / 修改属性）→ [symbol-insert](symbol-insert.md)
- 符号管理（分类 / CRUD）→ [symbol-manage](symbol-manage.md)
- SVG 导入 → [svg-import](svg-import.md)
- 图片转矢量 → [vectorize](vectorize.md)

## 通用红旗

- `parseSvgToWebcad` 等 async WASM 方法内部会自动 `await this.initWasm()`，无需手动先调；失败时**返回 `null` 而非抛错**，`JSON.parse` 前必须判空
- 服务端符号 / 服务端图纸依赖 `serviceUrl + accessToken`：未配置 `serviceUrl` 时访问 `Engine.service` 会**直接抛错**（`SERVICE_URL is not configured`），不会返回空值——`if (!Engine.service)` 判断无效，要用 try/catch
- 用 `mergeSymbolToDocument(symbolDoc, insertPoint, basePoint, scale, rotation, clearSourceInfo)`，参数顺序是 **doc → 插入点 → 基点 → 缩放 → 旋转**，不要反过来
- 旋转角度单位是 **度**（`mergeSymbolToDocument` / `SymbolInteractiveInserter` 都按度），但实体级 `entity.rotate(center, ang)` 是 **弧度**。两套不要混

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/insert/index.md`
- 示例：`vjcad/example/insert/svg/`、`vjcad/example/insert/symbol/`、`vjcad/example/insert/vectorize/`