企业官网建设流程全解析

gogcli 实操指南：用gog sheets validation get读取 Google Sheets 数据验证规则

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli

导读

在 Google Sheets 中，数据验证规则（Data Validation Rule）控制着单元格可输入的内容——例如下拉列表、数字范围、日期限制或自定义公式。gogcli（Google Workspace in your terminal）提供了gog sheets validation get命令，让你无需打开浏览器即可从任意表格范围读取全部验证规则，并以人类可读表格或机器可解析的 JSON 输出。读完本文，你将掌握该命令的完整用法、两种范围寻址方式、JSON 结构化输出，以及它如何同时识别普通单元格验证与"表格托管的下拉列"（table-managed dropdown）验证。

命令定位：validation 家族中的读取端

gog sheets validation get属于gog sheets validation子命令族，该家族在 internal/cmd/sheets_validation.go 中定义，共包含三个操作：

对应文档见 gog-sheets-validation.md 及其子命令页面：get、set、clear。

get是整个命令族中唯一的纯读取操作，因此即使开启--readonly保护模式也可以安全执行（--readonly会在运行时拦截所有变更型 API 请求）。

基本用法与命令形态

命令语法如下：

gog sheets (sheet) validation (data-validation,validations) get (list,show) <spreadsheetId> <range>

其中括号表示可选别名：sheets可用sheet，validation可用data-validation或validations，get可用list或show。因此以下写法完全等价：

gog sheets validation get 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms Sheet1!A1:B10 gog sheets validation list 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms Sheet1!A1:B10 gog sheet validations show 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms Sheet1!A1:B10

命令接收两个必填位置参数：

• <spreadsheetId>：电子表格 ID（即 URL 中/spreadsheets/d/与/edit之间的字符串）。
• <range>：目标范围，支持A1 记法（如Sheet1!A1:B10）或命名范围名称（如MyNamedRange）；范围中若不带工作表名（如直接写A1:B10），命令会自动解析为第一个工作表并补全工作表前缀（见 resolveValidationReadRange）。

缺省任一参数都会返回 usage 错误（源码中通过usage("empty spreadsheetId")/usage("empty range")校验，见 Run 方法）。

输出格式：表格与 JSON 双模式

默认表格输出

默认情况下，命令把匹配到的每个带验证规则的单元格输出为一行，列包含：工作表名（Sheet）、A1 坐标（A1）、行号（Row）、列号（Col）以及规则详情（Rule）。列定义来自sheetsValidationColumns()。

示例输出：

SHEET A1 ROW COL RULE Sheet1 A2 2 1 {"condition":{"type":"ONE_OF_LIST","values":[{"userEnteredValue":"Low"},{"userEnteredValue":"Medium"},{"userEnteredValue":"High"}]}}

如果目标范围内不存在任何验证规则，命令会向 stderr 打印No data validation rules found并以成功状态退出（不会报错）。

JSON 输出（适合脚本化）

配合-j/--json/--machine标志，输出切换为结构化 JSON，外层包含三个字段：

gog sheets validation get -j 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms 'Sheet1!A1:B10'

{ "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms", "range": "Sheet1!A1:B10", "validations": [ { "sheet": "Sheet1", "a1": "A2", "row": 2, "col": 1, "rule": { "condition": { "type": "ONE_OF_LIST", "values": [ {"userEnteredValue": "Low"}, {"userEnteredValue": "Medium"}, {"userEnteredValue": "High"} ] }, "showCustomUi": true } } ] }

validations数组中的每个元素对应一个带规则的单元格，其中rule字段直接透传 Google Sheets API 的DataValidationRule结构（条件类型condition.type、条件值condition.values、strict是否拒绝非法输入、inputMessage提示消息等）。该结构定义于 sheetsCellValidation，JSON 序列化逻辑见 Run 中的 JSON 分支。

与-j搭配的常用辅助标志：

• --results-only：仅输出主结果（validations数组），丢弃外层信封字段；
• --select/--pick：按逗号分隔的字段路径选择子集输出；
• -p/--plain/--tsv：输出稳定、可解析的 TSV 文本，适合awk/cut等管道工具。

底层原理：两类验证规则的合并读取

gog sheets validation get的核心价值在于它同时覆盖了两种验证规则来源，这在源码层面体现得非常清晰（见 Run 方法）：

1. 普通单元格验证（cell-level validation）：通过一次Spreadsheets.GetAPI 请求，带上IncludeGridData(true)和字段掩码sheets(properties(title),data(startRow,startColumn,rowData(values(dataValidation))))，让服务端直接把范围内每个单元格的dataValidation内联返回。随后 collectCellValidations 遍历行数据，把每个带DataValidation的单元格转换成sheet + a1 + row + col + rule记录，并按数据块的startRow/startColumn偏移换算成真实行列号。

2. 表格托管下拉列验证（table-managed dropdown）：Google Sheets 的"表格"（Table）功能把数据验证规则挂在列属性上（columnProperties.dataValidationRule），这类规则不会出现在普通单元格的 dataValidation 里。命令通过 fetchTableValidationSpans 另行拉取表格元数据（字段掩码覆盖tables(tableId,range,columnProperties(columnIndex,columnName,columnType,dataValidationRule))），把每个下拉列展开为从表头下一行到表尾（自动扣除 footer 行）的连续 Span。

3. 合并去重：appendTableCellValidations用sheet:row:col作为 key 对两类结果去重合并，再用Sheet → Row → Col顺序排序后输出。Span 的几何模型（SheetID、TableID、ColumnIndex、StartRow/EndRow、StartCol/EndCol、Rule）定义于 internal/sheetsvalidation/planner.go，行/列区间求交与剪裁算法见 IntersectGridIndexes。

也就是说：即使某列验证规则是表格功能托管的（界面上体现为整列下拉箭头），get也能把该列所有数据行的规则如实列出来，而不是只报告"表格列有规则"。

命名范围与 A1 解析

范围解析由resolveValidationReadRange完成：若入参不含!，先尝试按命名范围名称解析（resolveNamedRangeByNameOrID），解析成功则使用规范名称并定位网格区间；否则走 A1 解析路径，无工作表名时自动补第一个工作表标题。这套解析依赖 fetchSpreadsheetRangeCatalog 拉取的工作表 ID/标题/命名范围目录。

常用标志速查

get继承 gogcli 全局标志体系，以下是读取场景最常涉及的标志（完整清单见 gog-sheets-validation-get.md）：

实战场景

1. 审计一张表的全部验证规则

gog sheets validation get 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms Sheet1

不指定行范围时，命令按整表读取（源码中resolveValidationReadRange对无行号的范围会保留开放区间）。此时建议配合--color never避免管道输出夹杂颜色码。

2. 检查单个单元格是否有下拉限制

gog sheets validation get -p 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms 'Sheet1!C5'

输出 TSV 便于grep/awk快速判断。

3. 用命名范围定位

gog sheets validation get -j --results-only <spreadsheetId> MyNamedRange

只拿到validations数组，可直接喂给jq做二次处理。

4. 配合 set/clear 实现验证规则的"读-改-写"

get是验证规则管理流程的读取端，配合 gog-sheets-validation-set.md 的set（支持ONE_OF_LIST、ONE_OF_RANGE、NUMBER_BETWEEN、DATE_AFTER、BOOLEAN、CUSTOM_FORMULA等条件类型，以及--value、--strict、--show-custom-ui、--input-message标志）和 gog-sheets-validation-clear.md 的clear，即可在脚本中完成"先审计现有规则 → 再增删改"的完整闭环。

5. 注意表格下拉列的特殊约束

若后续要set/clear表格托管下拉列，源码强制要求附加--filtered-rows-included标志，且set时表格列只支持ONE_OF_LIST下拉（见 BuildSetRequests 与 BuildClearRequests）。先用get确认目标列是否属于表格托管，能帮你提前规避这些 usage 错误。

测试与实现验证

该功能的正确性由以下测试保障，可继续深入阅读：

• internal/cmd/sheets_validation_more_test.go：覆盖参数缺失、A1 解析、GridRange 转换与ForceSendFields（如第一个工作表的SheetId=0仍需强制发送）等边界；
• internal/sheetsvalidation/planner_test.go：覆盖 Span 求交、区间剪裁与表格列验证规则的构建/清除逻辑；
• internal/sheetsvalidation/copy.go：验证规则复制（PASTE_DATA_VALIDATION）相关的补充请求构建逻辑。

小结

gog sheets validation get是把 Google Sheets 数据验证规则暴露给终端和脚本的最短路径：一条命令同时覆盖普通单元格验证与表格托管下拉列，支持 A1 记法、命名范围、TSV 与 JSON 输出，是数据治理、规则审计与 CI 校验流程中的实用一环。结合set、clear与--readonly保护模式，你可以在不打开浏览器的情况下，把整张表的输入约束变成可检索、可版本化、可自动化的数据资产。

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli