> **本文回答**：图片导出**纯前端**，不依赖服务端：`exportEntitiesToImageAndDownload({width, theme, transparent, fileName, ...})` 直接下载；`exportEntitiesToImage({...})` 返回 `{success, blob}`，可用于上传。命令 `EXPORTPNG` 弹出对话框（可选实体、主题色、宽度等）。

## 一、命令式

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

弹出对话框，让用户选择实体范围 / 主题色 / 宽度等。

MCP 参考：`vjcad/doc/file/file-operations.md`、`vjcad/example/file/09exportpng.js`。

## 二、API 式（最常用）

```js
import { exportEntitiesToImageAndDownload } from 'vjcad';

// 默认透明背景 PNG
await exportEntitiesToImageAndDownload({
  width: 2048,
  fileName: 'my-drawing.png'
});

// 白色背景 PNG
await exportEntitiesToImageAndDownload({
  width: 2048,
  transparent: false,
  theme: 'light',
  fileName: 'my-drawing-white.png'
});

// 黑色背景 PNG
await exportEntitiesToImageAndDownload({
  width: 1920,
  transparent: false,
  theme: 'dark',
  fileName: 'my-drawing-dark.png'
});

// 仅指定实体
await exportEntitiesToImageAndDownload({
  entities: [line1, circle1],
  width: 1280,
  fileName: 'partial.png'
});

// 导出为 JPEG（不支持透明，自动用主题色）
await exportEntitiesToImageAndDownload({
  width: 1920,
  theme: 'dark',
  mimeType: 'image/jpeg',
  quality: 0.9,
  fileName: 'my-drawing.jpg'
});
```

MCP 参考：`vjcad/example/file/09exportpng.js`、`vjcad/doc/file/file-operations.md`。

## 三、获取 Blob（不下载，用于上传）

```js
import { exportEntitiesToImage } from 'vjcad';

const result = await exportEntitiesToImage({
  entities: myEntities,
  width: 1920
});

if (result.success && result.blob) {
  const formData = new FormData();
  formData.append('file', result.blob, 'screenshot.png');
  // await fetch('/upload', { method: 'POST', body: formData });
}
```

MCP 参考：`vjcad/example/file/09exportpng.js`。

## 四、`IExportImageOptions` 参数表

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `entities` | `EntityBase[]` | 当前空间全部 | 要导出的实体 |
| `width` | number | 自动（长边 1000） | 像素；省略时按包围盒比例取长边 1000px（宽≥高则 width=1000）；内部渲染上限 4096（超出后缩放到请求尺寸） |
| `height` | number | 自动 | 按 bbox 比例算 |
| `theme` | `'dark'`\|`'light'` | `'light'` | 主题色（透明时只影响 colorIndex 7 反色） |
| `transparent` | boolean | true | 仅 PNG 有效 |
| `mimeType` | `'image/png'`\|`'image/jpeg'` | `'image/png'` | 格式 |
| `quality` | number 0~1 | 0.92 | JPEG 质量 |
| `fileName` | string | `'export.png'`（jpeg 为 `'export.jpg'`） | 下载文件名 |

MCP 参考：`vjcad/doc/file/file-operations.md`。

## 五、说明要点

- **透明背景 PNG**：可直接用于文档 / PPT
- **`light` 主题**：白底，colorIndex 7（白）自动反色为黑
- **`dark` 主题**：黑底，colorIndex 7 保持白
- **JPEG 不支持透明**：`transparent` 自动忽略
- **高度自动算**：根据实体包围盒宽高比
- **画布上限 4096px**：超出自动缩放

MCP 参考：`vjcad/doc/file/file-operations.md`。

## 反例

- 把 `width: 8000` 当超清：实际仍按 4096 渲染再缩放，看起来反而模糊；想要超清要分块导出。
- `transparent: true` + `mimeType: 'image/jpeg'`：JPEG 不透明，参数被忽略。
- 想生成"白底图，红线条"但 `colorIndex = 7`：透明 + light 时 7 会被反色为黑，这是预期行为。
- `entities` 子集**退化边界**（如单条零高度的水平线）：返回 `success:true` 但 `blob.size=0`、`dataUrl="data:,"`——导出前确保实体包围盒有宽高。
- `IExportImageResult` 同时带 `dataUrl`（存在），不止 `blob`。
- `EXPORTPNG` 命令弹 `vjcad-export-png-panel` 对话框并 `await` 用户确认——**不可脚本化**（无头环境 promise 永久挂起）；且编辑器命令串行，挂起的对话框会**阻塞后续所有 `executerWithOp`**（EXPORTDWG 在其后排队不弹框）。

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/file/file-operations.md`
- 示例：`vjcad/example/file/09exportpng.js`