飞书开放平台 Server API 文档

主题

批量创建条件格式 ​

在电子表格工作表的指定区域中，为满足指定条件的单元格和单元格中的数据设置样式。支持跨工作表创建多个条件格式。

使用限制 ​

  • 单次调用该接口，最多支持创建 10 个条件格式。
  • 单个工作表中最多支持 20 个条件格式。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/sheets/v2/spreadsheets/:spreadsheet_token/condition_formats/batch_create
HTTP MethodPOST
接口频率限制100 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可drive:drive 查看、评论、编辑和管理云空间中所有文件 sheets:spreadsheet 查看、评论、编辑和管理电子表格

请求头 ​

名称类型必填描述
Authorizationstring是通过访问凭证（access_token）对调用者身份进行鉴权。可选值： - tenant_access_token： 租户授权凭证。应用代表租户（即企业或团队）执行对应操作。示例值："Bearer t-7f1bcd13fc57d46bac21793aabcef" - user_access_token：用户授权凭证。应用代表用户执行对应操作。示例值："Bearer u-7f1bcd13fc57d46bac21793aabcef" 了解更多，参考获取访问凭证。
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
spreadsheet_tokenstring电子表格的 token。可通过以下两种方式获取。了解更多，参考电子表格概述。 - 电子表格的 URL：https://sample.feishu.cn/sheets/==Iow7sNNEphp3WbtnbCscPqabcef== - 调用获取文件夹中的文件清单

请求体 ​

参数类型是否必填说明
sheet_condition_formatsarray<interface>是要创建的条件格式的信息。最多可创建 10 个条件格式。 注意：
响应体中将返回每个条件格式的设置结果，包括成功或具体的失败信息。
  └ sheet_idstring是电子表格工作表的 ID。调用获取工作表获取 ID。
  └ condition_format/是条件格式的详细信息
    └ rangesarray<string>是条件格式应用的范围，支持以下五种写法，了解更多，参考条件格式指南。
- sheetId：填写工作表 ID，表示将条件格式应用于整表 - sheetId!{开始行索引}:{结束行索引}：填写工作表 ID 和行数区间，表示将条件格式应用于整行 - sheetId!{开始列索引}:{结束列索引}：填写工作表 ID 和列的区间，表示将条件格式应用于整列 - sheetId!{开始单元格}:{结束单元格}：填写工作表 ID 和单元格区间，表示将条件格式应用于单元格选定的区域中 - sheetId!{开始单元格}:{结束列索引}：填写工作表 ID、起始单元格和结束列，表示省略结束行，使用表格的最后行作为结束行
注意： - 每个范围的区间不可超过表格的行总数和列总数 - 每个范围的 sheetId 的值必须与 sheet_id 参数的值一致 示例值：["40a7b0!C3:C3"]
    └ rule_typestring是创建条件时的规则类型。可选值： - containsBlanks：为空 - notContainsBlanks：不为空 - duplicateValues：重复值 - uniqueValues：唯一值 - cellIs：限定值范围 - containsText：包含内容 - timePeriod：日期
    └ attrsarray<object>是rule_type 参数对应的具体属性信息
注意：
当 rule_type 为 containsBlanks（为空）、notContainsBlanks（不为空）、duplicateValues（重复值）或 uniqueValues（唯一值）时，无需传入 attrs 参数。了解更多，参考条件格式指南。
      └ operatorstring否操作方法。了解更多，参考条件格式指南。
      └ time_periodstring否时间范围。当 rule_type 为 timePeriod 时，该参数必填，且 operator 参数仅支持 is。可选值： - yesterday：昨天 - today：今天 - tomorrow：明天 - last7Days：最近 7 天
      └ formulaarray<string>否公式。当 rule_type 为 cellIs 时，该参数必填。
注意： - 当 operator 为 between 或 notBetween 时，需要填写两个元素，其他情况下只需填一个元素，值为用户自定义。 - 填写的值若是数字类型，需填写为如 "1" 的格式；若是文本类型，需填写为 "\"aaaaa\"" 格式。即文本需要用 "" 包裹并转义。了解更多示例，请参考条件格式指南。
      └ textstring否文本。当 rule_type 为 containsText 时，该参数必填。值为用户自定义。
    └ style/否条件格式的样式。支持设置字体样式、文本装饰、字体颜色和背景颜色。 注意： style 不可设置为 ""。默认不传该值，即不设置样式。
      └ font/否符合条件的数据的字体样式
        └ boldbool否字体是否加粗
        └ italicbool否字体是否为斜体
      └ text_decorationint否文本装饰。为文本设置下划线或删除线。可选值： - 0：无下划线和删除线 - 1：下划线 - 2：删除线 - 3：同时设置下划线和删除线
      └ fore_colorstring否设置字体颜色。需填写字体颜色的十六进制代码。如 #faf1d1。
      └ back_colorstring否设置背景颜色。需填写背景颜色的十六进制代码。如 #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
                }
            }
        }
    ]
}'

响应 ​

响应体 ​

参数类型说明
codeint错误码，非 0 表示失败。
msgstring错误描述
data//
  └ responsesarray<interface>响应信息
    └ sheet_idstring工作表的 ID
    └ cf_idstring要创建的条件格式的 ID
    └ res_codeint当前条件格式创建的状态码。0 表示成功创建，非 0 表示失败。
    └ res_msgstring条件格式设置返回的状态信息，success 表示成功，非 success 将返回失败原因。

res_code 说明 ​

res_coderes_msg排查建议
90230unknown rule_typerule_type 参数填写错误。电子表格支持以下规则类型： - containsBlanks：为空 - notContainsBlanks：不为空 - duplicateValues：重复值 - uniqueValues：唯一值 - cellIs：限定值范围 - containsText：包含内容 - timePeriod：日期 参考规则类型 rule_type 与属性 attrs 了解如何选择与填写 rule_type。

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "responses": [
            {
                "cf_id": "1gJelvenW9",
                "res_code": 0,
                "res_msg": "success",
                "sheet_id": "40a7b0"
            }
        ]
    }
}

错误码 ​

具体可参考：服务端错误码说明

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有