# 批量创建条件格式 在电子表格工作表的指定区域中，为满足指定条件的单元格和单元格中的数据设置样式。支持跨工作表创建多个条件格式。 ## 使用限制 - 单次调用该接口，最多支持创建 10 个条件格式。 - 单个工作表中最多支持 20 个条件格式。 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/:spreadsheet_token/condition_formats/batch_create HTTP Method | POST 接口频率限制 | [100 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论、编辑和管理电子表格(sheets:spreadsheet) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | 通过访问凭证（access_token）对调用者身份进行鉴权。可选值：
- `tenant_access_token`： 租户授权凭证。应用代表租户（即企业或团队）执行对应操作。示例值："Bearer t-7f1bcd13fc57d46bac21793aabcef"
- `user_access_token`：用户授权凭证。应用代表用户执行对应操作。示例值："Bearer u-7f1bcd13fc57d46bac21793aabcef"
了解更多，参考[获取访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)。 Content-Type | string | 是 | **固定值**："application/json; charset=utf-8" ### 路径参数 名称 | 类型 | 描述 ---|---|--- spreadsheet_token | string | 电子表格的 token。可通过以下两种方式获取。了解更多，参考[电子表格概述](https://open.feishu.cn/document/ukTMukTMukTM/uATMzUjLwEzM14CMxMTN/overview)。
- 电子表格的 URL：https://sample.feishu.cn/sheets/==Iow7sNNEphp3WbtnbCscPqabcef==
- 调用[获取文件夹中的文件清单](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/list) | **示例值**："Iow7sNNEphp3WbtnbCscPqabcef" ### 请求体 参数 | 类型 | 是否必填 | 说明 ---|---|---|--- sheet_condition_formats | array<interface> | 是 | 要创建的条件格式的信息。最多可创建 10 个条件格式。
**注意**：
响应体中将返回每个条件格式的设置结果，包括成功或具体的失败信息。 sheet_id | string | 是 | 电子表格工作表的 ID。调用[获取工作表](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/sheets-v3/spreadsheet-sheet/query)获取 ID。 condition_format | / | 是 | 条件格式的详细信息 ranges | array<string> | 是 | 条件格式应用的范围，支持以下五种写法，了解更多，参考[条件格式指南](https://open.feishu.cn/document/ukTMukTMukTM/uATMzUjLwEzM14CMxMTN/conditionformat/condition-format-guide)。
- `sheetId`：填写工作表 ID，表示将条件格式应用于整表
- `sheetId!{开始行索引}:{结束行索引}`：填写工作表 ID 和行数区间，表示将条件格式应用于整行
- `sheetId!{开始列索引}:{结束列索引}`：填写工作表 ID 和列的区间，表示将条件格式应用于整列
- `sheetId!{开始单元格}:{结束单元格}`：填写工作表 ID 和单元格区间，表示将条件格式应用于单元格选定的区域中
- `sheetId!{开始单元格}:{结束列索引}`：填写工作表 ID、起始单元格和结束列，表示省略结束行，使用表格的最后行作为结束行
**注意**：
- 每个范围的区间不可超过表格的行总数和列总数
- 每个范围的 sheetId 的值必须与 `sheet_id` 参数的值一致
**示例值**：["40a7b0!C3:C3"] rule_type | string | 是 | 创建条件时的规则类型。可选值：
- containsBlanks：为空
- notContainsBlanks：不为空
- duplicateValues：重复值
- uniqueValues：唯一值
- cellIs：限定值范围
- containsText：包含内容
- timePeriod：日期 attrs | array<object> | 是 | `rule_type` 参数对应的具体属性信息
**注意**：
当 `rule_type` 为 containsBlanks（为空）、notContainsBlanks（不为空）、duplicateValues（重复值）或 uniqueValues（唯一值）时，无需传入 `attrs` 参数。了解更多，参考[条件格式指南](https://open.feishu.cn/document/ukTMukTMukTM/uATMzUjLwEzM14CMxMTN/conditionformat/condition-format-guide)。 operator | string | 否 | 操作方法。了解更多，参考[条件格式指南](https://open.feishu.cn/document/ukTMukTMukTM/uATMzUjLwEzM14CMxMTN/conditionformat/condition-format-guide)。 time_period | string | 否 | 时间范围。当 `rule_type` 为 `timePeriod` 时，该参数必填，且 `operator` 参数仅支持 `is`。可选值：
- yesterday：昨天
- today：今天
- tomorrow：明天
- last7Days：最近 7 天 formula | array<string> | 否 | 公式。当 `rule_type` 为 `cellIs` 时，该参数必填。
**注意**：
- 当 `operator` 为 `between` 或 `notBetween` 时，需要填写两个元素，其他情况下只需填一个元素，值为用户自定义。
- 填写的值若是数字类型，需填写为如 `"1"` 的格式；若是文本类型，需填写为 `"\"aaaaa\""` 格式。即文本需要用 "" 包裹并转义。了解更多示例，请参考[条件格式指南](https://open.feishu.cn/document/ukTMukTMukTM/uATMzUjLwEzM14CMxMTN/conditionformat/condition-format-guide)。 text | string | 否 | 文本。当 `rule_type` 为 `containsText` 时，该参数必填。值为用户自定义。 style | / | 否 | 条件格式的样式。支持设置字体样式、文本装饰、字体颜色和背景颜色。
**注意**：
`style` 不可设置为 `""`。默认不传该值，即不设置样式。 font | / | 否 | 符合条件的数据的字体样式 bold | bool | 否 | 字体是否加粗 italic | bool | 否 | 字体是否为斜体 text_decoration | int | 否 | 文本装饰。为文本设置下划线或删除线。可选值：
- 0：无下划线和删除线
- 1：下划线
- 2：删除线
- 3：同时设置下划线和删除线 fore_color | string | 否 | 设置字体颜色。需填写字体颜色的十六进制代码。如 #faf1d1。 back_color | string | 否 | 设置背景颜色。需填写背景颜色的十六进制代码。如 #faf1d1。 ### 请求体示例 ```json { "sheet_condition_formats": [ { "sheet_id": "40a7b0", "condition_format": { "ranges": [ "40a7b0!C3:C3" ], "rule_type": "timePeriod", "attrs": [ { "operator": "is", "time_period": "today", // rule_type 为 timePeriod 时必填 "formula": ["\"aaaaa\""], // rule_type 为 cellIs 时必填；若其中是文本，则需要用 "" 包裹并转义 "text": "" // rule_type 为 containsText 时必填 } ], "style": { "font": { "bold": true, "italic": true }, "fore_color": "#faf1d1", "back_color": "#d9f5d6", "text_decoration": 3 } } } ] } ``` ### cURL 请求示例 ```bash curl --location --request POST 'https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/shtcngNygNfuqhxTBf588jwgWbJ/condition_formats/batch_create' \ --header 'Authorization: Bearer t-e346617a4acfc3a11d4ed24dca0d0c0fc8e0067e' \ --header 'Content-Type: application/json' \ --data-raw '{ "sheet_condition_formats": [ { "sheet_id": "Q7PlXT", "condition_format": { "ranges": [ "Q7PlXT!C3:D9" ], "rule_type": "uniqueValues", "style": { "font": { "bold": true, "italic": true }, "fore_color": "#faf1d1", "back_color": "#d9f5d6", "text_decoration": 3 } } } ] }' ``` ## 响应 ### 响应体 参数 | 类型 | 说明 ---|---|--- code | int | 错误码，非 0 表示失败。 msg | string | 错误描述 data | / | / responses | array<interface> | 响应信息 sheet_id | string | 工作表的 ID cf_id | string | 要创建的条件格式的 ID res_code | int | 当前条件格式创建的状态码。0 表示成功创建，非 0 表示失败。 res_msg | string | 条件格式设置返回的状态信息，success 表示成功，非 success 将返回失败原因。 #### res_code 说明 res_code | res_msg | 排查建议 ---|---|--- 90230 | unknown rule_type | `rule_type` 参数填写错误。电子表格支持以下规则类型：
- containsBlanks：为空
- notContainsBlanks：不为空
- duplicateValues：重复值
- uniqueValues：唯一值
- cellIs：限定值范围
- containsText：包含内容
- timePeriod：日期
参考[规则类型 rule_type 与属性 attrs](https://open.feishu.cn/document/ukTMukTMukTM/uATMzUjLwEzM14CMxMTN/conditionformat/condition-format-guide#6de1dc32) 了解如何选择与填写 `rule_type`。 ### 响应体示例 ```json { "code": 0, "msg": "success", "data": { "responses": [ { "cf_id": "1gJelvenW9", "res_code": 0, "res_msg": "success", "sheet_id": "40a7b0" } ] } } ``` ### 错误码 具体可参考：[服务端错误码说明](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)