# 浮动图片使用指南
本文档介绍云文档电子表格中浮动图片能力相关的参数和方法列表。
## 基本概念
浮动图片指悬浮在表格单元格上方的图片。图片大小可自行调整，不会随单元格大小而变化。
## 注意事项
- 电子表格只存储图片的 token。这意味着：
- 在调用[创建浮动图片](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/sheets-v3/spreadsheet-sheet-float_image/create)接口之前，你需先调用[上传素材](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_all)或[分片上传素材](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_prepare)上传图片至表格
- 查询浮动图片和获取浮动图片接口只返回图片的 token。你需调用[下载素材](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/download)和[获取素材临时下载链接](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/batch_get_tmp_download_url)下载图片
- 单个电子表格最多支持放置 4,000 张不同 token 的图片，即表格内不重复的图片（包括浮动图片和单元格图片）总数不超过 4,000 张。将相同 token 的图片多次放置在表格的不同位置，数量上仅算一张图片。
## 浮动图片参数
本小节介绍浮动图片中涉及的主要参数及其描述。
浮动图片参数 | 描述
---|---
float_image_id | 工作表内浮动图片的唯一标识。用于对图片进行增删改查操作。可选择自定义，也可不传由系统自动生成。自定义需要满足字符长度为 10，可由 0-9、a-z、A-Z 组合而成。
float_image_token | 浮动图片的 token，用于图片的上传和下载操作。
- 通过[上传素材](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_all)或[分片上传素材](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_prepare)获得。
- 通过该 token，调用[下载素材](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/download)接口下载图片。
range | 浮动图片左上角所在单元格位置，格式为 `sheetId!{开始单元格}:{结束单元格}`，仅支持填写单个单元格，如 "ahgsch!A1:A1"。
width | 如下图，浮动图片展示的宽度。创建浮动图片时不传会默认采用图片实际宽度，如果传则需要大于等于 20 像素。
height | 如上图，浮动图片展示的高度，创建浮动图片时不传会默认采用图片实际高度，如果传则需要大于等于 20 像素。
offset_x | 如上图，浮动图片左上角距离所在单元格左上角的横向偏移，单位为像素，默认为 0。设置的值需要大于等于 0、小于浮动图片左上角所在单元格的宽度。
offset_y | 如上图，浮动图片左上角距离所在单元格左上角的纵向偏移，单位为像素，默认为 0。设置的值需要大于等于 0、小于浮动图片左上角所在单元格的高度。
## 方法列表
以下为浮动图片的方法列表。其中，“商店”代表应用商店应用；“自建”代表企业自建应用，了解更多应用相关信息，参考[应用类型简介](https://open.feishu.cn/document/home/app-types-introduction/overview)。了解调用服务端 API 的流程，参考[流程概述](https://open.feishu.cn/document/uMzNwEjLzcDMx4yM3ATM/ugzNwEjL4cDMx4CO3ATM)。
方法 (API) | 权限要求（满足任一） | 访问凭证 | 商店 | 自建
---|---|---|---|---
`POST` [创建浮动图片](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/sheets-v3/spreadsheet-sheet-float_image/create) /open-apis/sheets/v3/spreadsheets/:spreadsheet_token/sheets/:sheet_id/float_images | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论、编辑和管理电子表格(sheets:spreadsheet) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
`POST` [更新浮动图片](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/sheets-v3/spreadsheet-sheet-float_image/patch) /open-apis/sheets/v3/spreadsheets/:spreadsheet_token/sheets/:sheet_id/float_images/:float_image_id | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论、编辑和管理电子表格(sheets:spreadsheet) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
`GET` [获取浮动图片](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/sheets-v3/spreadsheet-sheet-float_image/get) /open-apis/sheets/v3/spreadsheets/:spreadsheet_token/sheets/:sheet_id/float_images/:float_image_id | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论和下载云空间中所有文件(drive:drive:readonly)
查看、评论、编辑和管理电子表格(sheets:spreadsheet)
查看、评论和导出电子表格(sheets:spreadsheet:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
`GET` [查询浮动图片](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/sheets-v3/spreadsheet-sheet-float_image/query) /open-apis/sheets/v3/spreadsheets/:spreadsheet_token/sheets/:sheet_id/float_images/query | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论和下载云空间中所有文件(drive:drive:readonly)
查看、评论、编辑和管理电子表格(sheets:spreadsheet)
查看、评论和导出电子表格(sheets:spreadsheet:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
`DELETE` [删除浮动图片](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/sheets-v3/spreadsheet-sheet-float_image/delete) /open-apis/sheets/v3/spreadsheets/:spreadsheet_token/sheets/:sheet_id/float_images/:float_image_id | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论、编辑和管理电子表格(sheets:spreadsheet) | `tenant_access_token`
`user_access_token` | **✓** | **✓**