gog sheets banding list：gogcli 中查询 Google Sheets 隔行变色带状区域的完整实践

gog sheets banding listgogcli 中查询 Google Sheets 隔行变色带状区域的完整实践【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog sheets banding list是 gogcliGoogle Workspace 终端 CLI中用于列出电子表格中所有隔行变色alternating color banding带状区域 / Banded Range的只读命令。本篇以该命令的官方参考页为核心结合仓库中的命令实现、通用列表辅助函数与测试用例讲清它的调用方式、全部参数、输出契约表格 / TSV / JSON以及它与banding set、banding clear配合完成先查询、再清除自动化闭环的完整工作流并深入到 Sheets APIspreadsheets.get的 fields 投影与BandedRange数据模型层面解释其底层原理。命令定位与基本用法banding命令族管理电子表格中随数据变化持续生效的隔行/隔列着色样式包含三个子命令见 命令族参考页gog sheets banding list列出隔行变色带状区域本文主题只读gog sheets banding set给指定区域应用隔行变色gog sheets banding clear移除隔行变色list的基本用法源自 命令参考gog sheets (sheet) banding (banded-ranges) list spreadsheetId [flags]其中(sheet)、(banded-ranges)是 kong 框架生成的命令别名/分组标记实际输入gog sheets banding list spreadsheetId即可。该命令是gog sheets banding的默认子命令源码中List带有default:withargs标签因此在省略子命令名时直接跟 spreadsheetId 也会被解析为 list见 SheetsBandingCmd 定义。一个典型只读示例gog sheets banding list $spreadsheet_id --json参数说明命令专属参数只有一个--sheet其余为全局根参数。以下参数表完整继承自官方生成文档该文档由gog schema --json生成通过make docs-commands重新生成。命令级参数Flag类型默认值说明--sheetstringOnly list banding from this sheet仅列出该工作表上的带状区域全局参数RootFlagsFlag类型默认值说明--access-tokenstringUse provided access token directly (bypasses stored refresh tokens; token expires in ~1h)-a/--account/--acctstringAccount email, alias, or auto for authenticated Google API commands--clientstringOAuth client name (selects stored credentials token bucket)--colorstringautoColor output: auto|always|never--disable-commandsstringComma-separated list of disabled commands; dot paths allowed-n/--dry-run/--dryrun/--noop/--previewboolDo not make changes; print intended actions and exit successfully--enable-commandsstringComma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)--enable-commands-exactstringComma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children-y/--force/--assume-yes/--yesboolSkip confirmations for destructive commands--gmail-no-sendboolfalseBlock Gmail send operations (agent safety)-h/--helpkong.helpFlagShow context-sensitive help.--homestringOverride gogcli config/data/state/cache root (equivalent to GOG_HOME)-j/--json/--machineboolfalseOutput JSON to stdout (best for scripting)--no-input/--non-interactive/--noninteractiveboolNever prompt; fail instead (useful for CI)-p/--plain/--tsvboolfalseOutput stable, parseable text to stdout (TSV; no colors)--quota-projectstringGoogle Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)--readonlyboolfalseBlock mutating API requests at runtime; auth add also requests read-only OAuth scopes--results-onlyboolIn JSON mode, emit only the primary result (drops envelope fields like nextPageToken)--select/--pick/--projectstringIn JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands.-v/--verboseboolEnable verbose logging--versionkong.VersionFlagPrint version and exit--wrap-untrustedboolfalseIn JSON/raw output, wrap fetched text fields in external untrusted-content markers与 list 场景直接相关的几个全局参数值得展开--sheet title按工作表标题精确过滤只返回该表的带状区域避免遍历整个工作簿-j/--json输出 JSON最适合脚本与 Agent 消费-p/--plain/--tsv输出稳定的 TSV 文本无颜色便于awk、cut等工具解析--readonly在运行时拦截一切写请求。list 本身是只读命令但加上--readonly可把只查不改作为运行时安全约束固化下来与配套的 safety-profiles 等 Agent 安全档案配套使用--enable-commands/--enable-commands-exact在 Agent 场景中把 CLI 收窄到白名单前缀如只允许sheets.banding防止误触其他命令。输出契约表格、TSV 与 JSONgog sheets banding list的输出行为由两条路径决定均可在 SheetsBandingListCmd.Run 中确认JSON 模式-j输出{bandedRanges: [...]}信封jsonKey固定为bandedRanges人类可读模式输出三列表格若整个工作簿没有任何带状区域向 stderr 打印No banded ranges并以成功状态退出空消息也是硬编码契约的一部分。表格模式下固定的三列表头由 sheetsBandingColumns 定义列含义来源字段BANDED_RANGE_ID带状区域 ID清除时要用到的句柄BandedRange.BandedRangeIdSHEET工作表标题sheet.Properties.TitleRANGEA1 表示的区域如Data Set!A1:B10sheetsa1.FormatGridRange由GridRange渲染JSON 模式下每个条目是 sheetsbanding.Item 结构字段及语义如下字段类型说明bandedRangeIdint64带状区域 IDbanding clear --id的入参sheetIdint64工作表数字 IDsheetTitlestring工作表标题a1stringA1 表示的区域omitemptyrangesheets.GridRange原始GridRange含sheetId、startRowIndex、endRowIndex等omitemptyrowPropertiessheets.BandingProperties行向隔行配色表头色、第一带色、第二带色、是否跳过行等omitemptycolumnPropertiessheets.BandingProperties列向隔行配色omitempty测试用例 TestSheetsBandingSetListAndClear 验证了 list 的 JSON 输出中同时包含bandedRangeId: 777与a1: Sheet1!A1:C5TestItemsAndIDsForSheet 则确认了标题含空格时 A1 渲染为Data Set!A1:B10这样的加引号形式。实用示例——只查某张表、取全部带状区域gog sheets banding list $spreadsheet_id --sheet Data Set --json # 或稳定文本 gog sheets banding list $spreadsheet_id -p--selectJSON 模式可进一步做字段投影例如--select bandedRangeId,a1按参考页说明更通用的投影方式是对多数命令使用--fields。实现解析最小化 fields 投影的通用列表管线从源码结构看list 并没有自己实现 API 调用而是复用了 Sheets 子系统的通用只读管线。SheetsBandingListCmd.Run 调用泛型辅助函数 runSheetsSpreadsheetList传入两个关键参数fields 掩码sheets(properties(sheetId,title),bandedRanges)JSON 键bandedRanges该辅助函数固定了四步流程normalizeGoogleID归一化 spreadsheetId支持传入带查询参数的 Drive 链接形式为空则报usage(empty spreadsheetId)经requireSheetsService取得 Sheets API 服务走当前账号凭证调用spreadsheets.Get并带上精确的Fields掩码——只拉取每个工作表的sheetId、title与完整bandedRanges不下载任何单元格数据。这是该命令高效的原因无论工作簿多大网络负载只与带状区域数量线性相关用注入的extract函数即sheetsbanding.Items把Spreadsheet转换为条目切片再按输出模式写 JSON 或表格。条目抽取逻辑在 sheetsbanding.Items遍历spreadsheet.Sheets跳过无Properties的脏数据onlySheet ! 时按标题精确匹配过滤注意是 title 而非 sheetId且大小写敏感可推断带引号的区域名需以标题原文传入对每个BandedRange组装ItemA1 文本由sheetsa1.FormatGridRange(sheetTitle, range)生成结果切片非 nil空工作簿时 JSON 输出为{bandedRanges:[]}而非null对脚本消费更友好。同一包内还有 IDsForSheet它按标题解析出该表全部BandedRangeId——这是banding clear --all的后端先用最小掩码sheets(properties(title),bandedRanges(bandedRangeId))二次读取再为每个 ID 生成DeleteBanding请求见 clear 的实现。list 与 clear 由此共享同一套数据模型。与 set / clear 配合先查后清的自动化闭环隔行变色在 Sheets 中是一等 API 实体set通过BatchUpdate发送AddBanding请求服务端在Replies中回传新分配的BandedRangeId见 set 实现 中从resp.Replies[0].AddBanding提取 ID 并回显bandedRangeId而clear必须持有这个 ID 才能定位删除。因此list 是这个命令族中唯一能发现现有带状区域的入口典型运维闭环是# 1. 列出所有隔行变色区域拿到 bandedRangeId gog sheets banding list $spreadsheet_id --json # 2. 只保留默认行向色方案地重建set 不传属性 JSON 时使用内置默认色 gog sheets banding set $spreadsheet_id Sheet1!A1:C20 --json # 3. 移除指定 ID 的带状区域破坏性操作需 --force 跳过确认 gog sheets banding clear $spreadsheet_id --id 123456 --force # 4. 或整表清除--all 必须搭配 --sheet gog sheets banding clear $spreadsheet_id --sheet Sheet1 --all --force这些示例与 Sheets Formatting 指南的 Banding 小节 一致。补充两个行为细节默认色方案set不带--row-properties-json时使用 DefaultRowProperties 内置的三档蓝白色表头0.88/0.93/1第一带白第二带0.96/0.98/1确认机制clear属于破坏性命令不带--force会要求交互确认测试 TestSheetsBandingSetListAndClear 断言了 without --force 报错路径在 CI 中请配合--force或--no-input使用--dry-run则可打印将执行的删除请求而不落地。自定义配色时--row-properties-json/--column-properties-json接收严格的 Sheets APIBandingPropertiesJSON解码器开启DisallowUnknownFields且拒绝多个 JSON 值见 DecodeProperties 及 对应测试写错字段名会以退出码 2 的用法错误快速失败而不是静默忽略。适用前提与限制需要已完成 Google 登录gog auth/gog login且具备 Sheets API 权限的账号--readonly进一步在运行时拦截写请求并收窄 OAuth 授权范围--sheet过滤按标题精确匹配标题需与工作表原始名称含大小写与空格一致list 输出不含单元格内容只含带状区域元数据若需要查看区域内的数据应配合gog sheets get等值类命令参考页声明本命令由gog schema --json生成、随make docs-commands更新本文行号引用以当前仓库快照为准。小结与延伸阅读gog sheets banding list用一次带最小 fields 掩码的spreadsheets.Get即可回答这个工作簿里有哪些隔行变色区域、分别在哪些表、覆盖什么范围、用了什么配色并以表格/TSV/JSON 三种稳定契约输出bandedRangeId这一关键句柄它是banding set/clear自动化中不可替代的只读前置步骤也天然适配--readonly、--enable-commands等 Agent 安全约束。相关文档gog sheets banding 命令族gog sheets banding setgog sheets banding clearSheets Formatting 指南命令索引【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考