gspread（Python）如何设置谷歌表格中复选框的取值

核心实现依赖DataValidationRule数据验证规则实现，谷歌表格的复选框本质是绑定了布尔值/固定二元值的特殊数据验证组件。

前置依赖 #

首先安装所需依赖库：

pip install gspread oauth2client

同时提前在谷歌云平台启用Google Sheets API，获取服务账号密钥文件，并将服务账号邮箱添加到目标谷歌表格的共享编辑权限列表中。

基础实现（默认勾选返回TRUE/未勾选返回FALSE） #

import gspread
from oauth2client.service_account import ServiceAccountCredentials
from gspread import DataValidationRule

# 初始化认证客户端
scope = ["https://spreadsheets.google.com/feeds", "https://www.googleapis.com/auth/drive"]
creds = ServiceAccountCredentials.from_json_keyfile_name("你的服务账号密钥文件路径.json", scope)
client = gspread.authorize(creds)

# 打开目标表格和对应工作表
spread = client.open("你的谷歌表格名称")
worksheet = spread.get_worksheet(0) # 此处取第一个工作表，可根据索引或名称自定义

# 构造复选框规则
default_checkbox = DataValidationRule(
    {
        "condition": {"type": "BOOLEAN"},
        "showCustomUi": True # 渲染为复选框UI，而非布尔值下拉选择
    }
)

# 给指定范围设置复选框，示例为A列第2行到第100行
worksheet.set_data_validation_rule("A2:A100", default_checkbox)

自定义复选框返回值 #

如果需要自定义勾选/未勾选对应的返回值（比如勾选返回"完成"，未勾选返回"未完成"），修改规则配置即可：

custom_checkbox = DataValidationRule(
    {
        "condition": {
            "type": "ONE_OF_LIST",
            "values": [
                {"userEnteredValue": "完成"},
                {"userEnteredValue": "未完成"}
            ]
        },
        "showCustomUi": True,
        "strict": True # 禁止输入规则外的内容
    }
)

# 给B列2到100行设置自定义值复选框
worksheet.set_data_validation_rule("B2:B100", custom_checkbox)

常见问题排查 #

• 规则设置后不生效：检查对应范围是否有其他冲突的条件格式/数据验证规则，可先清空目标范围格式后重试
• 权限报错：确认服务账号邮箱已经被添加到表格的共享列表，且授予了编辑权限

内容的提问来源于stack exchange，提问作者Jerred Kelley