# 透明度（瓦片 + 遮罩）

> 文档：`vjcad/doc/tile/tile-mode.md`
> 示例：
> - `vjcad/example/tile/04tilealpha.js` — 瓦片透明度
> - `vjcad/example/tile/05tilemaskalpha.js` — 遮罩透明度

瓦片模式下有 **两个独立的透明度通道**：

| 通道 | API | 默认 | 影响 |
|---|---|---|---|
| **瓦片层** | `pcanvas.setWmsTileAlpha(a)` | 1.0 | 整张图纸瓦片 |
| **编辑区遮罩** | `pcanvas.setReadOnlyAlpha(a)` | 1.0 | 区域编辑加的背景色遮罩（图层编辑不加遮罩） |

## 1. 瓦片透明度

### API 用法

```js
// 读
const cur = pcanvas.getWmsTileAlpha();   // 0~1

// 写
pcanvas.setWmsTileAlpha(0.5);
pcanvas.redraw();                        // 立刻刷新（不需要 regen）
```

### 命令用法

```js
await Engine.editor.executerWithOp('TILEALPHA');
// 命令行 getReal 提示输入 0~100（百分比，内部 /100），无对话框/滑块；
// 超出范围重新提示；当前没有瓦片层时只提示一句并结束
```

> 完整代码：`vjcad/example/tile/04tilealpha.js`

### 典型场景

- 整图加 50% 透明 + 互联网底图叠加 → 看背景对位
- 黑底瓦片，矢量颜色看不清 → 透明度调到 0.3 临时查看

## 2. 编辑区遮罩透明度

进入区域编辑后，该矩形会被一块当前主题背景色的 **遮罩**（只读层上的填充矩形，默认 alpha 1 即不透明）盖住，避免瓦片与矢量重影；图层编辑不加遮罩。这层独立调透明：

```js
const cur = pcanvas.getReadOnlyAlpha();  // 0~1
pcanvas.setReadOnlyAlpha(0.3);           // 0=不挡（看见瓦片） 1=完全挡（纯白/纯黑）
pcanvas.redraw();
```

命令（同样是命令行输入 0~100）：

```js
await Engine.editor.executerWithOp('TILEMASKALPHA');
```

> 完整代码：`vjcad/example/tile/05tilemaskalpha.js`

## 3. 联动场景

### 场景 A：瓦片只读，矢量编辑同时可见

```js
pcanvas.setWmsTileAlpha(0.4);    // 瓦片调暗当背景
pcanvas.setReadOnlyAlpha(0.6);   // 遮罩稍重一点突出编辑区
```

### 场景 B：瓦片透明对照地图

```js
Engine.enableWebMap({            // WebMapTileConfig 单对象（tileCrs/tileUrl/mapbounds 为 TS 必填）
    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', // 1.0.16 不发送、不参与对齐
    srs: 'EPSG:4509',               // 对齐靠 srs / fourParameterBefore
});
pcanvas.setWmsTileAlpha(0.6);    // 瓦片半透
Engine.setWebMapAlpha(0.5);      // 互联网地图也半透
pcanvas.redraw();
```

### 场景 C：把遮罩关掉对比"瓦片版"和"矢量版"

```js
pcanvas.setReadOnlyAlpha(0);    // 让瓦片在编辑区也透出
pcanvas.redraw();
// ...对比之后再恢复
pcanvas.setReadOnlyAlpha(1);
```

## 4. 注意

- `setWmsTileAlpha` / `setReadOnlyAlpha` 只改容器 alpha，之后 `pcanvas.redraw()` 即可立即生效（画布不自动渲染）；`regen(true)` 会重建全部实体图形，没必要
- 瓦片透明度 `tileAlpha` 会随 `SAVESERVER` / `SAVELOCAL` 保存，重新瓦片打开时自动恢复；遮罩透明度（`ReadOnlyAlpha`）不保存。重新 `enableWmsTileLayer` 会新建瓦片层，瓦片 alpha 回到 1
- `getWmsTileAlpha` / `getReadOnlyAlpha` 只在瓦片模式下有意义；普通矢量模式拿到的是默认值
- `TILEALPHA` / `TILEMASKALPHA` 是命令行输入 0~100 的百分比（没有面板）；要 0~1 小数直接用 API

## 红旗

- 把 `setReadOnlyAlpha(0)` 之后忘了恢复，下次进编辑区会以为遮罩失效
- 移动端 GPU 性能差，瓦片透明渲染会掉帧；建议默认 1.0，需要时再调
- 设备像素比 / 屏幕缩放对透明度无影响；改完记得 `pcanvas.redraw()`

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/tile/tile-mode.md`
- 示例：
- `vjcad/example/tile/04tilealpha.js` — 瓦片透明度
- `vjcad/example/tile/05tilemaskalpha.js` — 遮罩透明度