# tile / 瓦片模式总览

> 文档：`vjcad/doc/tile/index.md`、`vjcad/doc/tile/tile-mode.md`
> 示例：`vjcad/example/tile/01opentile.js` ~ `06webmapoverlay.js`

## 1. 是什么

**瓦片模式（Tile Mode）** 是 vjcad 处理"超大图纸"的策略。把图纸渲染成 **WMS 风格的图片瓦片**，浏览器只下载视口内的瓦片，避免一次性把几百万实体加载进矢量引擎。

它解决两类问题：

- 几十 MB 甚至上 GB 的 DWG，矢量加载会卡死
- 多个项目共用同一张底图，需要 **只读叠底 + 局部矢量编辑**

## 2. 三种打开方式对比

| 模式 | 数据形式 | 编辑能力 | 典型 API |
|---|---|---|---|
| **矢量模式** | 实体存在内存 | 全量编辑 | `Engine.view.openDbDoc(...)` |
| **瓦片只读** | WMS 瓦片图层 | 只能查看 / 圈选范围 | `pcanvas.enableWmsTileLayer(...)` |
| **瓦片局部编辑** | 瓦片 + 局部矢量 | 在指定区域 / 图层内编辑 | `TileEditAreaCommand` / `TileEditLayerCommand` |

## 3. 心智模型

```mermaid
flowchart TB
    subgraph 瓦片层
        T1[base 瓦片<br/>整图渲染] --> T2[编辑区遮罩<br/>背景色矩形]
    end
    subgraph 矢量层
        V1[currentDoc<br/>仅含编辑区/图层实体]
    end
    T1 -->|底图| Canvas
    T2 -->|遮罩| Canvas
    V1 -->|前景| Canvas
```

- 叠放顺序（`CanvasController` 舞台，自下而上）：互联网底图 → WMS 瓦片 → 只读层（编辑区遮罩）→ 模型层（矢量）。**矢量始终画在瓦片之上**，不会被瓦片盖住；`setWmsTileAlpha` 调瓦片透明度，`setReadOnlyAlpha` 调遮罩透明度
- 遮罩只在 **区域编辑** 时添加：`addTileMask` 在只读层上画一块当前主题背景色的矩形，挡住该区域的瓦片，让矢量不与瓦片重影；图层编辑不加遮罩
- 矢量层的实体属于真正的 `Engine.currentDoc`，所有编辑命令、Undo、Save 都跑在矢量层

## 4. 关键 API（按用途分组）

```js
// (1) 打开瓦片图层（只读）
const drawingManager = new DrawingManagerService();   // 顶层无 drawingManager 导出，须自行 new
const service = drawingManager.getService();
const meta = await service.metadata(mapid, version);   // Service.metadata
Engine.view.newDocument();
pcanvas.enableWmsTileLayer(service, {
    /* mapid, version, layers, tileSize, maxZoom, minZoom, transparent, ... */
});
Engine.currentDoc.isReadOnly = true;
Engine.currentDoc.serverSource = { type: 'imports', mapid, version, branchName: 'main', lastPatchId: 'base' };

// (2) 进入区域编辑（载入矩形内的矢量到 currentDoc）
await TileEditAreaCommand.loadEditArea(editArea, serverSource, pcanvas, currentDoc, drawingManager);

// (3) 进入图层编辑
const layers = await TileEditLayerCommand.getLayerListFromService(mapid, version);   // 签名是 (mapid, version?)
await TileEditLayerCommand.loadEditLayers(selectedLayers, serverSource, pcanvas, currentDoc, drawingManager);

// (4) 透明度
pcanvas.setWmsTileAlpha(0.5);    // 整体瓦片
pcanvas.setReadOnlyAlpha(0.3);   // 编辑区遮罩

// (5) 互联网底图叠加（WebMapTileConfig 单对象，详见 webmap-overlay.md）
Engine.enableWebMap({
    tileCrs: 'gcj02',
    tileUrl: 'https://webst0{s}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=6&x={x}&y={y}&z={z}',
    tileShards: '1,2,3,4',
    mapbounds: '0,0,100000,100000',      // TS 类型必填，但 1.0.16 不发送、不参与对齐
    srs: 'EPSG:4509',                    // 对齐靠 srs（或 fourParameterBefore）
});
Engine.setWebMapAlpha(0.6);
```

## 5. 命令一览

| 命令 | 作用 |
|---|---|
| `TILEEDITAREA` | 拉框，选定一块区域进入矢量编辑 |
| `TILEEDITLAYER` | 选择图层进入矢量编辑 |
| `TILEALPHA` | 设置瓦片透明度（命令行输入 0–100，无对话框；无瓦片层时仅提示） |
| `TILEMASKALPHA` | 设置编辑区遮罩透明度（同上，0–100） |

> 已注册命令中**没有** `TILEMODE` / `TILESAVE` / `TILEEXIT` / `SAVEDRAWING`：`TILEMODE` 只是 `CadDocument` 上的系统变量（1=模型空间 / 0=图纸空间，AutoCAD 同名变量语义），不是命令；保存走 `SAVESERVER` / `QSAVE` / `SAVELOCAL` 或 `LocalStorageService`，退出瓦片模式即重新按矢量方式打开图纸。

## 6. 子文档

- 打开瓦片图（API + URL 参数） → [open-mode](open-mode.md)
- 区域编辑 / 图层编辑 → [edit-area-layer](edit-area-layer.md)
- 透明度处理（瓦片 + 遮罩） → [transparency](transparency.md)
- 互联网地图叠加 → [webmap-overlay](webmap-overlay.md)

## 红旗

- 瓦片模式下 `Engine.currentDoc.isReadOnly = true` **不拦截编辑命令**——库内只用它显示只读标记、让 `QSAVE` 走另存为；`TILEEDITAREA`/`TILEEDITLAYER` 成功后会把它置回 `false`
- `enableWmsTileLayer` 不需要 viewBox：瓦片按每块的 WCS bbox 请求并定位，`metadata.bounds` 只影响初始视口
- 改瓦片 / 遮罩透明度后 `pcanvas.redraw()` 即可刷新（`TILEALPHA` 命令也只调 `redraw()`），无需 `regen(true)`
- 瓦片恒为 `mapid`/`version` 的 **base** 渲染（瓦片 URL 不带补丁号）；`serverSource.lastPatchId` 只影响区域/图层编辑载入的矢量和保存时的 `parentId`
- 互联网地图叠加时 CAD 本地坐标也能对齐：给 `fourParameterBefore`（CAD→EPSG:3857 四参数），无需标准 EPSG
- `WmsTileLayer`/`WebMapTileLayer`/`TileEditAreaCommand`/`TileEditLayerCommand`/`TileCache`/`TileScheduler`/`TileCalculator`/`showTileEditLayerDialog`/`TileAlphaSetvar`/`TileMaskAlphaSetvar` 均已导出；`tileKey({x,y,z})` 返回 `"z/x/y"` 格式字符串（如 `{x:3,y:-2,z:5}`→`"5/3/-2"`），`parseTileKey` 可逆

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/tile/index.md`、`vjcad/doc/tile/tile-mode.md`
- 示例：`vjcad/example/tile/01opentile.js` ~ `06webmapoverlay.js`