ai_member_xiaobian/.agents/skills/lark-sheets/references/lark-sheets-float-images.md

Sheets Float Images

前置条件： 先阅读 ../lark-shared/SKILL.md 了解认证、全局参数和安全规则。

这份 reference 汇总浮动图片相关能力：

• +media-upload
• +create-float-image
• +update-float-image
• +get-float-image
• +list-float-images
• +delete-float-image

+media-upload

对应命令：lark-cli sheets +media-upload

把本地图片上传到指定电子表格的素材空间，返回 file_token，供 +create-float-image 使用。

lark-cli sheets +media-upload --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --file ./image.png

说明：

• 内部调用 drive/v1/medias/upload_all
• >20MB 自动分片上传
• --file 只能是当前工作目录下的相对路径

参数：

参数	必填	说明
--url	否	电子表格 URL（与 --spreadsheet-token 二选一）
--spreadsheet-token	否	表格 token
--file	是	本地图片路径，必须是相对路径
--dry-run	否	仅打印请求，不执行

输出：file_token、file_name、size、spreadsheet_token

+create-float-image

对应命令：lark-cli sheets +create-float-image

lark-cli sheets +create-float-image --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --sheet-id "<sheetId>" --float-image-token "boxcnXXXX" \
  --range "<sheetId>!A1:A1" --width 200 --height 150

关键规则：

• --float-image-token 必须来自 +media-upload
• --range 必须锚定单个单元格
• width / height 必须 >=20
• offset-x / offset-y 必须 >=0

输出：float_image

+update-float-image

对应命令：lark-cli sheets +update-float-image

lark-cli sheets +update-float-image --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --sheet-id "<sheetId>" --float-image-id "fi12345678" \
  --width 400 --height 300 --offset-y 20

至少需要传一个更新字段：--range / --width / --height / --offset-x / --offset-y

输出：更新后的 float_image

+get-float-image

对应命令：lark-cli sheets +get-float-image

lark-cli sheets +get-float-image --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --sheet-id "<sheetId>" --float-image-id "fi12345678"

输出：float_image

+list-float-images

对应命令：lark-cli sheets +list-float-images

lark-cli sheets +list-float-images --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --sheet-id "<sheetId>"

输出：items[]

+delete-float-image

对应命令：lark-cli sheets +delete-float-image

lark-cli sheets +delete-float-image --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --sheet-id "<sheetId>" --float-image-id "fi12345678"

输出：code、msg

读取图片内容

上述读接口只返回元数据，不返回图片字节。要读取图片内容，用 float_image_token 调：

lark-cli docs +media-preview --token "<float_image_token>" --output ./image.png

参考

• cell-images — 写入到单元格的图片
• spreadsheet-management — 先获取 sheet_id