ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

gogcli 文档命名区域管理:`gog docs named-range list` 命令完整指南

gogcli 文档命名区域管理:`gog docs named-range list` 命令完整指南 gogcli 文档命名区域管理gog docs named-range list命令完整指南【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文基于 gogcli 仓库的docs/commands/gog-docs-named-range-list.md官方命令参考展开并结合源码internal/cmd/docs_named_ranges.go与其单元测试深入讲解如何在终端中列出 Google Docs 文档的命名区域Named Range、按名称精确过滤、按标签页Tab定位以及如何以表格、JSON、TSV 三种模式输出结果。读完本文你将能熟练使用gog docs named-range list完成文档命名区域的查询与脚本化集成并理解其底层的 Docs API 调用机制。命令概览与定位gog docs named-range list是 gogcli 中docs子命令体系下用于列出命名区域的命令。命名区域Named Range是 Google Docs 中为一段连续文本区域赋予唯一名称的机制常用于文档模板、内容占位符与程序化定位文本。该命令位于命令树的以下层级命令定义gog docs └── named-range (别名: named-ranges, namedranges, nr) ├── list (别名: ls) ← 本文主题 ├── create (别名: add, new) ├── delete (别名: rm, remove, del) └── replace(别名: set, update)命令组named-range在源码中注册了四个子命令list被标记为default:withargs即不带子命令名直接跟 docId 时会默认进入 list 分支见 internal/cmd/docs_named_ranges.go#L17-L22。基本用法gog docs (doc) named-range (named-ranges,namedranges,nr) list docId [flags]参数与别名说明docId必填位置参数可以是 Google Docs 文档 ID 或文档 URL。源码中通过normalizeGoogleID(strings.TrimSpace(c.DocID))进行规范化若解析后为空则直接报错empty docIdinternal/cmd/docs_named_ranges.go#L33-L36。命令别名named-range、named-ranges、namedranges、nr四者等价list亦可写作ls。docdocs命令组同样有doc别名因此gog docs named-range list与gog doc nr list完全等价。典型调用示例# 列出文档所有命名区域表格输出 gog docs named-range list 1abc123def456 # 使用短别名 URL 形式 gog doc nr list https://docs.google.com/document/d/1abc123def456/edit # 按名称精确过滤 指定标签页 gog docs named-range list 1abc123def456 --name stable --tab Work # JSON 输出便于脚本解析 gog docs named-range list 1abc123def456 -j # TSV 输出便于 grep/cut 处理 gog docs named-range list 1abc123def456 -pFlags 全量参考该命令继承了 gogcli 的全局命令框架基于 Kong 构建所有 flags 均定义于根命令层其中与列表查询直接相关的是--name、--tab、--tab-id、-j/--json、-p/--plain、--results-only与--select。Flag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过已存储的刷新令牌令牌约 1 小时过期-a--account--acctstring账户邮箱、别名或 auto用于已认证的 Google API 命令--clientstringOAuth 客户端名称选择已存储的凭据与令牌桶--colorstringauto颜色输出auto|always|never--disable-commandsstring逗号分隔的禁用命令列表支持点路径-n--dry-run--dryrun--noop--previewbool不实际修改仅打印预期操作并以成功状态退出--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI--enable-commands-exactstring逗号分隔的精确启用命令列表支持点路径父命令不会启用子命令-y--force--assume-yes--yesbool对破坏性命令跳过确认--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全-h--helpkong.helpFlag显示上下文相关的帮助信息--homestring覆盖 gogcli 的 config/data/state/cache 根目录等价于 GOG_HOME-j--json--machineboolfalse以 JSON 输出到 stdout最适合脚本--namestring按精确的命名区域名称过滤--no-input--non-interactive--noninteractivebool永不提示改为失败退出适合 CI-p--plain--tsvboolfalse输出稳定、可解析的纯文本到 stdoutTSV无颜色--quota-projectstring用于 API 用量计费的 Google Cloud 项目作为 X-Goog-User-Project 发送部分 API 在使用 --access-token 或 ADC 时需要--readonlyboolfalse在运行时阻止变更类 API 请求auth add 也会请求只读 OAuth 作用域--results-onlybool在 JSON 模式下仅输出主结果丢弃 nextPageToken 等信封字段--select--pick--projectstring在 JSON 模式下选择逗号分隔的字段尽力而为支持点路径。更推荐使用 --fields--tabstring按标题或 ID 定位特定标签页参见 gog docs list-tabs-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalse在 JSON/raw 输出中用外部不可信内容标记包裹抓取的文本字段与查询直接相关的参数详解--name按命名区域名称做精确匹配过滤非子串、非正则。实现位于filterDocsNamedRangesByName只保留item.Name name的条目internal/cmd/docs_named_ranges.go#L554-L562。需要说明的是命令参数结构体中也声明了--tab-id隐藏、已弃用源码resolveTabArg明确禁止--tab与--tab-id同时使用并在使用--tab-id时输出弃用警告internal/cmd/docs_edit.go#L13-L25。--tab按标题或 ID 定位标签页。列表输出时若指定该参数命令只读取该标签页的命名区域见下文多标签处理。-j/--json与-p/--plain切换三种输出模式默认表格 / JSON / TSV是脚本集成的关键。三种输出模式与列字段含义默认表格模式不指定-j或-p时输出为带表头的表格共 6 列internal/cmd/docs_named_ranges.go#L74-L92列含义NAME命名区域名称ID命名区域 IDnamedRangeId全局唯一START区域起始 UTF-16 索引含END区域结束 UTF-16 索引不含TAB_ID所在标签页 IDSEGMENT_ID所在段 ID页眉、页脚、脚注等区域才有值正文段为空若文档或当前标签页没有任何命名区域且非--plain模式则打印No named rangesinternal/cmd/docs_named_ranges.go#L65-L70。这一行为在空结果场景下便于人眼快速确认。JSON 模式-jJSON 输出采用信封结构internal/cmd/docs_named_ranges.go#L58-L64{ documentId: 1abc123def456, tabId: t.work, namedRanges: [ { name: alpha, namedRangeId: nr-alpha, ranges: [ { startIndex: 1, endIndex: 6, tabId: t.work, segmentId: header-1 } ] } ] }字段说明documentId规范化后的文档 IDtabId若通过--tab指定了标签页则为该标签页 ID否则为空字符串namedRanges命名区域数组。每个元素包含name、namedRangeId与ranges数组ranges中每个 span 携带startIndex、endIndex、tabId、segmentId后两者在为空时被omitempty省略。配合--results-only可以只保留namedRanges主结果丢弃信封字段配合--select name,namedRangeId可仅挑选所需字段适合下游流水线消费。TSV 模式-p-p/--plain/--tsv输出稳定的制表符分隔文本无表头、无颜色直接对应表格模式的 6 列alpha nr-alpha 1 6 t.work header-1 stable nr-stable 7 13 t.workTSV 转义规则在docsNamedRangeTSV中实现字段内的制表符\t、回车\r、换行\n分别转义为字面量\t、\r、\n保证单行可解析其他字符含 Unicode 与非 ASCII原样保留internal/cmd/docs_named_ranges.go#L586-L592。测试用例TestDocsNamedRangeTSVPreservesUnicodeAndLiteralCharacters验证了Résumé quoted C:\path\tline\nnext这类输入在转义后仍可单行还原internal/cmd/docs_named_ranges_test.go#L305-L312。多标签页Tabs语义现代 Google Docs 支持一个文档内多个标签页。gog docs named-range list对标签页的处理如下不带--tab列出文档根层级doc.NamedRanges的全部命名区域其中每个 span 自带tabId因此你仍能看到每个区域所属的标签页带--tab Work将loaded.tabID置为该标签页 ID随后docsNamedRangeItemsForLoaded会改从tab.DocumentTab.NamedRanges读取该标签页的命名区域internal/cmd/docs_named_ranges.go#L484-L498JSON 输出的tabId字段也会带上该标签页 ID。在源码中加载文档时会对带标签页参数的情形设置IncludeTabsContent(true)测试TestDocsNamedRangesListTabJSONAndPlain断言了请求查询参数为includeTabsContenttrue见 internal/cmd/docs_named_ranges_test.go#L86-L88。排序规则为便于阅读与比对docsNamedRangeItemsForLoaded对输出做了两层确定性排序internal/cmd/docs_named_ranges.go#L519-L551区域内 spans先按tabId升序再按segmentId升序然后按startIndex升序最后按endIndex升序命名区域条目先按name字典序升序名称相同时再按namedRangeId升序。测试TestDocsNamedRangesListTabJSONAndPlain断言了 JSON 数组中条目顺序为alpha、stable按名称字典序证实该排序对用户是稳定可见的行为internal/cmd/docs_named_ranges_test.go#L100-L102。源码调用链与实现细节list子命令的完整执行链路如下internal/cmd/docs_named_ranges.go#L31-L94DocsNamedRangesListCmd.Run ├─ normalizeGoogleID(docId) # 规范化文档 ID / URL空值报错 ├─ resolveTabArg(--tab, --tab-id) # 解析标签页参数拒绝同时使用 ├─ requireDocsService() # 建立已认证的 Google Docs API 服务 ├─ loadDocsTargetDocument() # 拉取文档含标签页内容 ├─ docsNamedRangeItemsForLoaded() # 从响应中提取并排序命名区域 ├─ filterDocsNamedRangesByName() # 若指定 --name按精确名称过滤 └─ 输出JSON 信封 / 表格 6 列 / TSV 三选一几个值得注意的实现要点名称为空时的兜底Google Docs API 的命名区域组NamedRangesmap以名称为键个别情况下条目自身的Name字段可能为空源码会用 map 键或组名兜底填充groupName、group.Name回退逻辑见 internal/cmd/docs_named_ranges.go#L500-L517跨标签页唯一性虽然list本身只做查询但同一命名区域 ID 若存在于多个标签页后续delete/replace命令会要求显式指定--tabscopeDocsNamedRangeToOwningTab中会返回 named range ID ... exists in multiple tabs; pass --tab。理解这一约束有助于在 list 输出时即养成带上--tab的习惯空结果退出码本命令与其它查询类命令共享emptyResultsExitCode 3internal/cmd/paging.go#L8脚本可通过退出码区分“查询成功但无结果”与“命令出错”。实战脚本化查询与模板校验场景一确认文档中的占位符命名区域gog docs named-range list 1abc123def456 --name order_id --plain输出一行 TSV包含该命名区域的名称、ID 与起止索引可直接用于awk -F\t提取gog docs named-range list 1abc123def456 -p | awk -F\t $1order_id {print $3, $4}场景二CI 中校验模板完整性if ! gog docs named-range list 1abc123def456 -p --no-input | grep -q ^signature_block; then echo 模板缺少 signature_block 命名区域 2 exit 3 fi这里--no-input保证在 CI 无交互环境下直接失败而非挂起等待输入。场景三JSON 流水线对接gog docs named-range list 1abc123def456 -j --results-only \ | jq -r .[].ranges[0].startIndex--results-only会剥掉documentId/tabId信封让jq直接作用于命名区域数组适合在脚本中批量统计每个命名区域的起始偏移。单元测试对行为的验证仓库在 internal/cmd/docs_named_ranges_test.go 中提供了针对本命令的测试夹具与断言TestDocsNamedRangesListTabJSONAndPlain同时验证 JSON 与 TSV 两种模式。JSON 断言documentId、tabId与两个命名区域alpha、stable的顺序TSV 断言--name stable过滤后输出精确为stable\tnr-stable\t7\t13\tt.work\t\n含末尾空 segmentId 列并验证了页眉区域携带segmentIdheader-1的行为internal/cmd/docs_named_ranges_test.go#L76-L119TestDocsNamedRangeTSVPreservesUnicodeAndLiteralCharacters验证 TSV 转义对 Unicode 与字面字符的保留TestWriteDocsNamedRangeTextResultIsStableTSV验证 create/delete/replace 结果输出使用稳定 TSV 键值格式。相关命令与延伸阅读父命令gog docs named-range — 命名区域管理命令组同级子命令create创建、delete删除、replace替换内容标签页定位gog docs list-tabs完整命令索引Command index源码入口internal/cmd/docs_named_ranges.go 与 internal/cmd/docs.go需要注意的是本文所述 flags 与命令层级以当前仓库生成文档docs/commands/gog-docs-named-range-list.md由gog schema --json自动生成为准。该文档页头部注明“Do not edit this page by hand; runmake docs-commands”即命令参考文档由 schema 自动维护若后续版本命令有调整以重新生成后的文档为准。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表