# 媒体上传与图片 (media & image) ## 使用场景 ### 媒体上传 用户说"上传附件/传文件到表格/上传文件到表格/上传到表格": - 上传附件 → `media-upload`（需表格 ID 或 URL + 本地文件路径） - 用户指定了上传后的名称 → `media-upload --name "自定义名称"` - `media-upload` 的 `--name` 参数用于指定附件在表格中显示的名称（不改变本地文件名）；不传时默认使用本地文件名 用户说"写入图片/插入图片/加图片/放图片到单元格/嵌入图片到表格": - 写入图片 → `write-image`（需表格 ID + 工作表 ID + 单元格范围 + 本地图片路径） - 禁止使用 `range update` 写入图片；图片对象必须使用 `write-image` 命令 - 用户指定了图片尺寸 → `write-image --width N --height M` ### 浮动图片 用户说"浮动图片/悬浮图片/在表格上放一张图/加个浮动的图": - 创建浮动图片 → `create-float-image --file <本地图片>`；已有 `resourceUrl` 时可改用 `--src` - 浮动图片悬浮于单元格之上，不占用单元格内容，与 `write-image`（写入单元格内部的图片）不同 用户说"查看浮动图片/有哪些浮动图片/浮动图片列表": - 列出所有浮动图片 → `list-float-images` - 查看某个浮动图片详情 → `get-float-image` 用户说"移动浮动图片/调整浮动图片大小/修改浮动图片/更新浮动图片": - 更新浮动图片属性 → `update-float-image`（可更新锚点位置、尺寸、偏移量、图片资源路径） 用户说"删除浮动图片/移除浮动图片": - 删除浮动图片 → `delete-float-image` 关键区分：`write-image`（单元格内嵌图片，占据单元格内容）vs `create-float-image`（浮动图片，悬浮于单元格之上，不占内容） ## 命令详细参考 ### 上传附件到表格 ``` Usage: dws sheet media-upload [flags] Example: dws sheet media-upload --node --file ./report.pdf dws sheet media-upload --node --file ./data.bin --name "数据文件.dat" --mime-type application/octet-stream Flags: --node string 目标表格文档的标识，支持传入 URL 或 ID (必填) --file string 本地文件路径 (必填) --name string 附件显示名称 (默认使用文件名) --mime-type string 文件 MIME 类型 (默认根据扩展名推断) ``` ### 上传图片并写入表格单元格 ``` Usage: dws sheet write-image [flags] Example: dws sheet write-image --node --sheet-id --range A1:A1 --file ./chart.png dws sheet write-image --node --sheet-id --range B2:B2 --file ./logo.png --width 200 --height 100 Flags: --node string 目标表格文档的标识，支持传入 URL 或 ID (必填) --sheet-id string 工作表 ID 或名称 (必填) --range string 目标单元格区域地址，如 A1:A1 (必填) --file string 本地图片文件路径 (必填) --name string 图片显示名称 (默认使用文件名) --mime-type string 文件 MIME 类型 (默认根据扩展名推断) --width int 图片显示宽度 (可选) --height int 图片显示高度 (可选) ``` ### 创建浮动图片 ``` Usage: dws sheet create-float-image [flags] Example: # 直接上传本地图片并创建浮动图片 dws sheet create-float-image --node --sheet-id \ --file ./chart.png --range A1 --width 400 --height 300 # 高级用法：先上传图片获取 resourceUrl dws sheet media-upload --node --file ./chart.png # 输出: resourceUrl: /core/api/resources/img/xxxx... # 再创建浮动图片 dws sheet create-float-image --node --sheet-id \ --src "/core/api/resources/img/xxxx..." --range A1 --width 400 --height 300 # 带偏移量 dws sheet create-float-image --node --sheet-id \ --src "/core/api/resources/img/xxxx..." --range B2 --width 200 --height 150 --offset-x 10 --offset-y 20 Flags: --node string 表格文档 ID 或 URL (必填) --sheet-id string 工作表 ID 或名称 (必填) --file string 本地图片文件路径，与 --src 二选一 --src string 图片资源路径，通过 media-upload 获取的 resourceUrl，与 --file 二选一 --range string 锚点单元格，A1 表示法，如 A1、B3 (必填) --width int 图片宽度，像素，正整数 (必填) --height int 图片高度，像素，正整数 (必填) --offset-x int 水平偏移量，像素 (默认 0) --offset-y int 垂直偏移量，像素 (默认 0) ``` 浮动图片悬浮于单元格之上，不占用单元格内容，可自由定位和调整大小。 - `--file` 与 `--src` 必须且只能提供一个；`--file` 会在命令内完成凭证获取、文件上传和浮动图片创建 - `--src` 必须是 `media-upload` 返回的 `resourceUrl`（格式为 `/core/api/resources/img/...`），不能直接传外部 URL；需要自定义上传名称/MIME 时使用这个高级两步流程 - `--range` 使用 A1 表示法指定锚点单元格（如 `A1`、`B3`），支持带工作表前缀（如 `Sheet1!A1`） - `--width` / `--height` 为必填，单位像素，必须为正整数 - `--offset-x` / `--offset-y` 表示相对锚点单元格左上角的偏移量（像素），默认 0，不能为负数 ### 获取浮动图片详情 ``` Usage: dws sheet get-float-image [flags] Example: dws sheet get-float-image --node --sheet-id --float-image-id Flags: --node string 表格文档 ID 或 URL (必填) --sheet-id string 工作表 ID 或名称 (必填) --float-image-id string 浮动图片 ID (必填) ``` 获取单个浮动图片的详细信息，包括 ID、图片资源路径、锚点位置、尺寸和偏移量。 `--float-image-id` 可通过 `list-float-images` 获取。 ### 列出工作表所有浮动图片 ``` Usage: dws sheet list-float-images [flags] Example: dws sheet list-float-images --node --sheet-id Flags: --node string 表格文档 ID 或 URL (必填) --sheet-id string 工作表 ID 或名称 (必填) ``` 列出指定工作表中所有浮动图片，返回 `floatImages` 数组和 `totalCount`。 ### 更新浮动图片属性 ``` Usage: dws sheet update-float-image [flags] Example: # 移动浮动图片到新位置 dws sheet update-float-image --node --sheet-id --float-image-id --range C5 # 调整尺寸 dws sheet update-float-image --node --sheet-id --float-image-id --width 600 --height 400 # 直接用本地图片替换 dws sheet update-float-image --node --sheet-id --float-image-id \ --file ./replacement.png # 高级用法：通过已上传的 resourceUrl 替换 dws sheet update-float-image --node --sheet-id --float-image-id \ --src "/core/api/resources/img/xxxx..." Flags: --node string 表格文档 ID 或 URL (必填) --sheet-id string 工作表 ID 或名称 (必填) --float-image-id string 浮动图片 ID (必填) --file string 用于替换浮动图片的本地图片路径，与 --src 不能同时使用 --src string 新的图片资源路径，通过 media-upload 获取的 resourceUrl --range string 新的锚点单元格，A1 表示法 --width int 新的图片宽度，像素 --height int 新的图片高度，像素 --offset-x int 新的水平偏移量，像素 --offset-y int 新的垂直偏移量，像素 ``` 更新浮动图片的属性，`--file` / `--src` / `--range` / `--width` / `--height` / `--offset-x` / `--offset-y` 至少传入一个；`--file` 与 `--src` 不能同时使用。 `--float-image-id` 可通过 `list-float-images` 获取。 ### 删除浮动图片 ``` Usage: dws sheet delete-float-image [flags] Example: dws sheet delete-float-image --node --sheet-id --float-image-id Flags: --node string 表格文档 ID 或 URL (必填) --sheet-id string 工作表 ID 或名称 (必填) --float-image-id string 浮动图片 ID (必填) ``` 删除指定的浮动图片，操作不可恢复。`--float-image-id` 可通过 `list-float-images` 获取。 ## 核心工作流 ```bash # ── 工作流 9: 上传附件到表格 ── # 1. 基本用法: 上传本地文件到表格 dws sheet media-upload --node --file ./report.pdf -f json # 2. 自定义附件显示名称 (--name 指定上传后在表格中显示的名称) dws sheet media-upload --node --file ./data.csv --name "销售数据.csv" -f json # 3. 指定 MIME 类型 (文件扩展名无法推断时) dws sheet media-upload --node --file ./data.bin --name "导出数据.dat" --mime-type application/octet-stream -f json # 4. 完整流程: 创建表格 → 上传附件 dws sheet create --name "项目资料" -f json # 提取 nodeId 后: dws sheet media-upload --node --file ./design.pdf -f json dws sheet media-upload --node --file ./timeline.xlsx --name "项目时间线.xlsx" -f json # ── 工作流 10: 写入图片到表格单元格 ── # 1. 基本用法: 写入图片到指定单元格 dws sheet write-image --node --sheet-id --range A1:A1 --file ./chart.png -f json # 2. 指定显示尺寸 dws sheet write-image --node --sheet-id --range B2:B2 --file ./logo.png --width 200 --height 100 -f json # 3. 自定义图片名称 dws sheet write-image --node --sheet-id --range C3:C3 --file ./photo.jpg --name "产品图.jpg" -f json # 4. 完整流程: 创建表格 → 写表头 → 写入图片 dws sheet create --name "产品目录" -f json # 提取 nodeId 后，先用 list 获取真实 sheetId: dws sheet list --node -f json dws sheet range update --node --sheet-id --range "A1:B1" \ --values '[[{"type":"text","text":"产品名称"},{"type":"text","text":"产品图片"}]]' -f json dws sheet range update --node --sheet-id --range "A2:A2" \ --values '[[{"type":"text","text":"MacBook Pro"}]]' -f json dws sheet write-image --node --sheet-id --range B2:B2 --file ./macbook.png --width 150 --height 100 -f json # ── 工作流 11: 创建或替换浮动图片 ── # 从本地图片直接创建 dws sheet create-float-image --node --sheet-id \ --file ./chart.png --range A1 --width 400 --height 300 -f json # 从本地图片直接替换已有浮动图 dws sheet update-float-image --node --sheet-id \ --float-image-id --file ./replacement.png -f json ``` ## 上下文传递 | 操作 | 从返回中提取 | 用于 | |------|-------------|------| | `media-upload` | `resourceId`、`resourceUrl` | 附件已上传到表格；`resourceUrl` 可用于 `create-float-image` 的 `--src` | | `write-image` | `resourceId` | 图片已写入指定单元格 | | `create-float-image` | `floatImage`（含 `id`、`src`、`range`、`width`、`height`、`offsetX`、`offsetY`） | `id` 用于后续 get / update / delete 的 `--float-image-id` | | `get-float-image` | `floatImage`（完整信息） | 查看单个浮动图片详情 | | `list-float-images` | `floatImages` 数组、`totalCount` | 获取所有浮动图片的 `id`，用于后续操作 | | `update-float-image` | `floatImage`（更新后的完整信息） | 确认更新结果 | | `delete-float-image` | `message` | 确认删除完成 | | `list` | 工作表的 `sheetId` | info / range read / range update / find 的 --sheet-id | ## 注意事项 - ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等） - `media-upload` 会自动完成图片上传并返回后续命令需要的资源信息，无需手动拆分步骤 - `write-image` 会自动完成图片上传并写入目标单元格，无需手动拆分步骤 - ★ 向表格单元格中写入图片必须使用 `write-image`，禁止使用 `range update`。`range update` 不支持图片对象 - `write-image` 与 `media-upload` 的区别：`media-upload` 仅上传附件到表格获取 resourceId；`write-image` 在上传后还会将图片写入指定单元格 - `create-float-image --file` 可直接输入本地图片；仅在需要 `--name` / `--mime-type` 覆盖或复用既有资源时，先用 `media-upload` 获取 `resourceUrl` 再传 `--src` - `create-float-image` 的 `--range` 使用 A1 表示法指定锚点单元格（如 `A1`、`B3`），支持带工作表前缀（如 `Sheet1!A1`） - `create-float-image` 的 `--width` / `--height` 为必填，单位像素，必须为正整数；`--offset-x` / `--offset-y` 可选，默认 0，不能为负数 - `write-image`（单元格内嵌图片）vs `create-float-image`（浮动图片）：`write-image` 将图片写入单元格内部，占据单元格内容；`create-float-image` 创建悬浮于单元格之上的浮动图片，不占用单元格内容，可自由调整位置和大小 - ★ **浮动图片用 `create-float-image` 不用 `write-image`**：两者用途不同——`write-image` 写入单元格内部，`create-float-image` 创建悬浮于单元格之上的浮动图片；优先直接传 `--file` - `update-float-image` 的 `--file` / `--src` / `--range` / `--width` / `--height` / `--offset-x` / `--offset-y` 至少必须提供一个，且 `--file` 与 `--src` 不能同时使用 - `list-float-images` 返回 `floatImages` 数组和 `totalCount`，每个元素包含 `id`（用于后续 get / update / delete） - `delete-float-image` 操作不可恢复，删除后图片将从工作表中移除