gogcligog docs named-range完全指南在终端中管理 Google Docs 命名区域【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读本文围绕 gogcliGoogle Workspace in your terminal的gog docs named-range命令组讲解如何在终端中完整管理 Google Docs 命名区域Named Ranges创建、列出、删除以及用纯文本替换其内容。读完本文你将掌握命名区域在 Docs API 中的数据结构、四种子命令的完整用法与全部参数语义、基于文本锚点定位--at与基于 UTF-16 索引定位--start/--end两种建区方式以及 JSON / TSV 两种可脚本化输出与--dry-run等安全机制。文中所有参数、命令与实现细节均以当前仓库源码为准。什么是命名区域Named Range在 Google Docs 中命名区域是一组为特定文本范围附加的标签给文档内某段文本起一个唯一的名字之后就可以通过名字引用这块区域而无需记住它在文档中的具体位置。即使文档内容前后编辑导致位置偏移只要命名区域仍然存在就能稳定地定位和更新它。典型的应用场景包括把文档中的签名区占位符模板变量等标记为命名区域之后用replace命令批量刷新内容在长文档中为需要反复定位的段落打上标签配合list快速查看所有区域及其坐标在自动化流水线中把命名区域当作可寻址的写入点避免依赖脆弱的固定文本匹配。在 gogcli 中该能力由命令组gog docs named-range提供它封装了 Google Docs API 的CreateNamedRangeRequest、DeleteNamedRangeRequest与ReplaceNamedRangeContentRequest三类请求。命令组的完整定义位于 internal/cmd/docs_named_ranges.go文档说明由gog schema --json自动生成运行make docs-commands可重新生成。命令概览与完整用法父命令与别名gog docs named-range是gog docs的一个子命令本身又包含四个子命令gog docs (doc) named-range (named-ranges,namedranges,nr) command从源码结构看internal/cmd/docs_named_ranges.go命令组支持多个别名父命令可用named-ranges、namedranges、nr简写create另有add、new别名delete有rm、remove、del别名replace有set、update别名。四个子命令如下子命令功能必选参数gog docs named-range list docId列出文档中的命名区域docIdgog docs named-range create docId创建一个命名区域docId、--name以及--at或--start/--end二选一gog docs named-range delete docId nameOrId删除一个命名区域docId、nameOrIdgog docs named-range replace docId nameOrId用纯文本替换命名区域内容docId、nameOrId、--text或--file二选一docId是 Google Doc 的 ID 或完整 URL——源码中通过normalizeGoogleID对输入做规范化处理因此直接粘贴文档分享链接也可以。创建命名区域create两种定位方式创建命名区域时必须先用--name指定唯一的名字然后选择以下两种定位方式之一方式一基于文本锚点--atgog docs named-range create docId --name signature --at Best regards在文档中查找字面文本Best regards把命名区域恰好覆盖在匹配到的文本上。相关参数--at要匹配的字面文本非正则--occurrence N当--at匹配到多处时指定使用第 N 处匹配从 1 开始计数--match-case开启区分大小写的匹配。从定位规划器 internal/docsedit/placement.go 可以看到--at与--start/--end互斥同时给出会直接报错--occurrence与--match-case必须搭配--at使用。校验规则还包括--occurrence必须大于 0--at为空字符串时报empty --at。方式二基于 UTF-16 索引--start/--endgog docs named-range create docId --name slot --start 10 --end 25直接用字节偏移指定范围--start为起始索引含--end为结束索引不含两者都是UTF-16 编码单元的下标这是 Google Docs API 的文本索引约定。规则上--start必须 ≥ 1--end必须大于--start且只提供其中一个会被拒绝——源码强制要求要么给--at要么同时给--start和--endinternal/docsedit/placement.go。提示想知道某段文本对应的 UTF-16 索引可先用gog docs find-range命令定位文本并打印索引范围。名字约束与重复检查--name不能为空且长度最多 256 个 UTF-16 编码单元源码中通过utf16Len(name) 256校验并报错见 internal/cmd/docs_named_ranges.go。创建前命令会先加载文档、按名字查重如果同名命名区域已存在会直接报named range name already exists: name并不会发起任何 API 写请求。这一点有测试覆盖TestDocsNamedRangesCreateIndexAndRejectDuplicate验证了重复名字时错误信息包含already exists且捕获到的 BatchUpdate 请求数保持不变internal/cmd/docs_named_ranges_test.go。底层 API 调用链创建流程最终组装一个docs.BatchUpdateDocumentRequest请求体包含CreateNamedRange其中写入Name与Range{StartIndex, EndIndex, TabId}internal/cmd/docs_named_ranges.go。值得注意的工程细节请求携带WriteControl.RequiredRevisionId即乐观锁写入前必须持有最新文档修订号若期间文档被他人修改则写入失败避免覆盖他人编辑。测试TestDocsNamedRangesCreateAtUsesUTF16TabAndRevision专门断言了RequiredRevisionId与 UTF-16 索引、TabId 的传递internal/cmd/docs_named_ranges_test.go。响应从resp.Replies[0].CreateNamedRange.NamedRangeId中取回新区域 ID若缺失则报错response missing namedRangeId。列出命名区域listgog docs named-range list docId不带参数时列出文档内所有命名区域可用--name 名字做精确过滤源码中按名字精确匹配见 internal/cmd/docs_named_ranges.go。文本模式输出默认文本输出是一张 TSV 表格列头为NAME ID START END TAB_ID SEGMENT_ID每个命名区域可能覆盖多个不连续的范围span每个 span 单独占一行。若区域不含任何 span则只有名字与 ID。测试中一个典型输出行形如stable nr-stable 7 13 t.workinternal/cmd/docs_named_ranges_test.goJSON 模式输出加-j/--json后输出结构化 JSON包含三个字段documentId、tabId、namedRanges数组。每个数组元素形如{ name: stable, namedRangeId: nr-stable, ranges: [ { startIndex: 7, endIndex: 13, tabId: t.work } ] }排序是确定的区域按名称排序、同名按 ID 排序每个区域内的 span 按tabId → segmentId → startIndex → endIndex排序见 internal/cmd/docs_named_ranges.go这保证了脚本消费结果的稳定性。空结果与过滤当文档没有任何命名区域时文本模式会输出提示No named ranges并以成功状态退出可编程判断JSON 模式下namedRanges为空数组。删除命名区域deletegog docs named-range delete docId nameOrId第二个位置参数nameOrId既可以是精确的名字也可以是区域的 ID。解析规则resolveDocsNamedRangeinternal/cmd/docs_named_ranges.go优先按 ID 精确匹配匹配不到时按名字精确匹配恰有一个匹配则命中若名字匹配到多个不同 ID报歧义错误ambiguous named range name; use ID: id1, id2提示改用 ID 消除歧义完全没有匹配时报named range not found: nameOrId。删除操作同样通过 BatchUpdate 的DeleteNamedRange请求完成并携带RequiredRevisionId乐观锁。测试TestDocsNamedRangesDeleteAndReplaceByExactID验证了删除请求只携带NamedRangeId不传名字且写控制字段正确internal/cmd/docs_named_ranges_test.go。由于删除是破坏性操作文本模式输出后还会追加一行deleted true便于脚本断言结果。替换命名区域内容replacegog docs named-range replace docId nameOrId --text 新的内容 # 或从文件/标准输入读取内容 gog docs named-range replace docId nameOrId --file content.txt echo new text | gog docs named-range replace docId nameOrId --file -replace用纯文本替换整个命名区域的内容--text别名--content直接给替换文本--file从纯文本文件读取-表示标准输入支持管道二者必须提供其一否则报required: --text or --file传空字符串--text 可以清空该区域的内容。底层使用 Docs API 的ReplaceNamedRangeContentRequest。源码中有一个细节当文本为空时会通过ForceSendFields [Text]强制把空字符串序列化到请求体确保清空语义被 API 正确识别internal/cmd/docs_named_ranges.go。对应测试断言请求体中确实包含text:internal/cmd/docs_named_ranges_test.go。替换完成后命令会重新加载文档并校验区域仍在随后输出结果JSON 模式返回documentId、namedRange、replaced: true、textLength文本模式输出区域信息外加replaced true与textLength N两行。多标签Tabs文档的处理现代 Google Docs 支持一个文档包含多个标签页Tabs。gogcli 的命名区域命令对多标签文档做了完整支持--tab 标题或ID显式指定要操作的标签页。所有四个子命令都支持该参数未指定--tab时list默认列出文档根级别的命名区域对于delete/replace如果区域实际属于某个标签页源码会调用scopeDocsNamedRangeToOwningTab自动把请求限定到该区域所属的标签internal/cmd/docs_named_ranges.go通过IncludeTabsContent(true)拉取全部标签内容后逐个查找区域所在标签若同一 ID 出现在多个标签中则要求用户显式传入--tab请求体中的TabsCriteria{TabIds: [...]}字段会把删除/替换操作限定在特定标签内。测试TestDocsNamedRangesReplaceDefaultTabScopesMultiTabRequest验证了未传--tab时请求自动携带TabIds: [t.main]internal/cmd/docs_named_ranges_test.go区域 span 中的tabId、segmentId字段会在 list 输出中如实呈现便于区分区域位于哪个标签、哪个段落segment。全局 Flags所有子命令通用以下全局 flags 对所有四个子命令均可用摘自各子命令文档与 gog-docs-named-range.mdFlag类型默认值说明--access-tokenstring—直接使用提供的访问令牌绕过存储的刷新令牌令牌约 1 小时过期-a/--account/--acctstring—账号邮箱、别名或auto用于需要认证的 Google API 命令--clientstring—OAuth 客户端名选择存储的凭据与令牌桶--colorstringauto颜色输出auto/always/never--disable-commandsstring—逗号分隔的禁用命令列表支持点路径--enable-commandsstring—逗号分隔的启用命令前缀点路径可限制 CLI--enable-commands-exactstring—逗号分隔的精确启用命令父命令不会启用其子命令-n/--dry-run/--dryrun/--noop/--previewbool—不做任何修改打印将要执行的动作并以成功状态退出-y/--force/--assume-yes/--yesbool—跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全用-h/--help——显示上下文相关的帮助信息--homestring—覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse向 stdout 输出 JSON最适合脚本--no-input/--non-interactive/--noninteractivebool—永不提示直接失败适合 CI-p/--plain/--tsvboolfalse输出稳定、可解析的 TSV 纯文本无颜色--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 模式下选择逗号分隔的字段尽力而为支持点路径-v/--verbosebool—开启详细日志--version——打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中用外部不可信内容标记包裹抓取的文本字段脚本化三件套与 gogcli 其他命令一致命名区域命令在脚本化时推荐组合使用-j/--json结构化的机器可读输出-p/--plain稳定的 TSV 输出list的 TSV 行格式固定见上文-n/--dry-run先在干跑模式下预览动作再真正执行。例如批量替换前先预览gog docs named-range replace docId signature --text new --dry-run干跑不会发送任何写请求而是打印将要执行的动作docs.named-range.replace及参数字段见 internal/cmd/docs_named_ranges.go。配合--readonly还能在运行时从机制上杜绝误写。实战把命名区域串成模板刷新流程结合四个子命令可以搭建一个占位符模板刷新流水线# 1. 查看文档里现有哪些命名区域确认占位符名字 gog docs named-range list docId -j # 2. 新建一个占位区域覆盖在 {{name}} 这个字面文本上 gog docs named-range create docId --name customer --at {{name}} # 3. 替换客户名称从文件读取避免命令行转义问题 printf Acme Corp | gog docs named-range replace docId customer --file - --dry-run # 先预览 printf Acme Corp | gog docs named-range replace docId customer --file - # 4. 用完清理 gog docs named-range delete docId customer注意第 3 步的两个关键点--file -支持从 stdin 读取适合内容来自管道或包含特殊字符的场景--dry-run与真实执行之间应确认预览结果再移除--dry-run正式执行。数据模型与边界约束小结最后把命名区域的底层数据模型与约束汇总如下依据 internal/cmd/docs_named_ranges.go 与 internal/docsedit/placement.go维度约束 / 说明名字非空唯一同文档内重复创建被拒绝≤ 256 个 UTF-16 编码单元索引UTF-16 编码单元--start含、--end不含--start ≥ 1--end --start定位方式--at字面文本 可选--occurrence/--match-case与--start/--end互斥区域覆盖一个命名区域可包含多个 span不连续范围list 输出中每个 span 一行/一项多标签支持--tab指定标签delete/replace 自动限定到区域所属标签跨标签歧义时要求显式--tab并发安全所有写操作携带WriteControl.RequiredRevisionId防止覆盖他人编辑输出文本 TSV含TAB_ID、SEGMENT_ID或 JSONdocumentId/tabId/namedRanges排序确定安全--dry-run预览、--readonly全局禁止写、--no-input供 CI 使用相关命令参考父命令 gog docs、子命令 create、delete、list、replace以及完整命令索引 docs/commands/README.md。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gogcli `gog docs named-range` 完全指南：在终端中管理 Google Docs 命名区域
gogcligog docs named-range完全指南在终端中管理 Google Docs 命名区域【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读本文围绕 gogcliGoogle Workspace in your terminal的gog docs named-range命令组讲解如何在终端中完整管理 Google Docs 命名区域Named Ranges创建、列出、删除以及用纯文本替换其内容。读完本文你将掌握命名区域在 Docs API 中的数据结构、四种子命令的完整用法与全部参数语义、基于文本锚点定位--at与基于 UTF-16 索引定位--start/--end两种建区方式以及 JSON / TSV 两种可脚本化输出与--dry-run等安全机制。文中所有参数、命令与实现细节均以当前仓库源码为准。什么是命名区域Named Range在 Google Docs 中命名区域是一组为特定文本范围附加的标签给文档内某段文本起一个唯一的名字之后就可以通过名字引用这块区域而无需记住它在文档中的具体位置。即使文档内容前后编辑导致位置偏移只要命名区域仍然存在就能稳定地定位和更新它。典型的应用场景包括把文档中的签名区占位符模板变量等标记为命名区域之后用replace命令批量刷新内容在长文档中为需要反复定位的段落打上标签配合list快速查看所有区域及其坐标在自动化流水线中把命名区域当作可寻址的写入点避免依赖脆弱的固定文本匹配。在 gogcli 中该能力由命令组gog docs named-range提供它封装了 Google Docs API 的CreateNamedRangeRequest、DeleteNamedRangeRequest与ReplaceNamedRangeContentRequest三类请求。命令组的完整定义位于 internal/cmd/docs_named_ranges.go文档说明由gog schema --json自动生成运行make docs-commands可重新生成。命令概览与完整用法父命令与别名gog docs named-range是gog docs的一个子命令本身又包含四个子命令gog docs (doc) named-range (named-ranges,namedranges,nr) command从源码结构看internal/cmd/docs_named_ranges.go命令组支持多个别名父命令可用named-ranges、namedranges、nr简写create另有add、new别名delete有rm、remove、del别名replace有set、update别名。四个子命令如下子命令功能必选参数gog docs named-range list docId列出文档中的命名区域docIdgog docs named-range create docId创建一个命名区域docId、--name以及--at或--start/--end二选一gog docs named-range delete docId nameOrId删除一个命名区域docId、nameOrIdgog docs named-range replace docId nameOrId用纯文本替换命名区域内容docId、nameOrId、--text或--file二选一docId是 Google Doc 的 ID 或完整 URL——源码中通过normalizeGoogleID对输入做规范化处理因此直接粘贴文档分享链接也可以。创建命名区域create两种定位方式创建命名区域时必须先用--name指定唯一的名字然后选择以下两种定位方式之一方式一基于文本锚点--atgog docs named-range create docId --name signature --at Best regards在文档中查找字面文本Best regards把命名区域恰好覆盖在匹配到的文本上。相关参数--at要匹配的字面文本非正则--occurrence N当--at匹配到多处时指定使用第 N 处匹配从 1 开始计数--match-case开启区分大小写的匹配。从定位规划器 internal/docsedit/placement.go 可以看到--at与--start/--end互斥同时给出会直接报错--occurrence与--match-case必须搭配--at使用。校验规则还包括--occurrence必须大于 0--at为空字符串时报empty --at。方式二基于 UTF-16 索引--start/--endgog docs named-range create docId --name slot --start 10 --end 25直接用字节偏移指定范围--start为起始索引含--end为结束索引不含两者都是UTF-16 编码单元的下标这是 Google Docs API 的文本索引约定。规则上--start必须 ≥ 1--end必须大于--start且只提供其中一个会被拒绝——源码强制要求要么给--at要么同时给--start和--endinternal/docsedit/placement.go。提示想知道某段文本对应的 UTF-16 索引可先用gog docs find-range命令定位文本并打印索引范围。名字约束与重复检查--name不能为空且长度最多 256 个 UTF-16 编码单元源码中通过utf16Len(name) 256校验并报错见 internal/cmd/docs_named_ranges.go。创建前命令会先加载文档、按名字查重如果同名命名区域已存在会直接报named range name already exists: name并不会发起任何 API 写请求。这一点有测试覆盖TestDocsNamedRangesCreateIndexAndRejectDuplicate验证了重复名字时错误信息包含already exists且捕获到的 BatchUpdate 请求数保持不变internal/cmd/docs_named_ranges_test.go。底层 API 调用链创建流程最终组装一个docs.BatchUpdateDocumentRequest请求体包含CreateNamedRange其中写入Name与Range{StartIndex, EndIndex, TabId}internal/cmd/docs_named_ranges.go。值得注意的工程细节请求携带WriteControl.RequiredRevisionId即乐观锁写入前必须持有最新文档修订号若期间文档被他人修改则写入失败避免覆盖他人编辑。测试TestDocsNamedRangesCreateAtUsesUTF16TabAndRevision专门断言了RequiredRevisionId与 UTF-16 索引、TabId 的传递internal/cmd/docs_named_ranges_test.go。响应从resp.Replies[0].CreateNamedRange.NamedRangeId中取回新区域 ID若缺失则报错response missing namedRangeId。列出命名区域listgog docs named-range list docId不带参数时列出文档内所有命名区域可用--name 名字做精确过滤源码中按名字精确匹配见 internal/cmd/docs_named_ranges.go。文本模式输出默认文本输出是一张 TSV 表格列头为NAME ID START END TAB_ID SEGMENT_ID每个命名区域可能覆盖多个不连续的范围span每个 span 单独占一行。若区域不含任何 span则只有名字与 ID。测试中一个典型输出行形如stable nr-stable 7 13 t.workinternal/cmd/docs_named_ranges_test.goJSON 模式输出加-j/--json后输出结构化 JSON包含三个字段documentId、tabId、namedRanges数组。每个数组元素形如{ name: stable, namedRangeId: nr-stable, ranges: [ { startIndex: 7, endIndex: 13, tabId: t.work } ] }排序是确定的区域按名称排序、同名按 ID 排序每个区域内的 span 按tabId → segmentId → startIndex → endIndex排序见 internal/cmd/docs_named_ranges.go这保证了脚本消费结果的稳定性。空结果与过滤当文档没有任何命名区域时文本模式会输出提示No named ranges并以成功状态退出可编程判断JSON 模式下namedRanges为空数组。删除命名区域deletegog docs named-range delete docId nameOrId第二个位置参数nameOrId既可以是精确的名字也可以是区域的 ID。解析规则resolveDocsNamedRangeinternal/cmd/docs_named_ranges.go优先按 ID 精确匹配匹配不到时按名字精确匹配恰有一个匹配则命中若名字匹配到多个不同 ID报歧义错误ambiguous named range name; use ID: id1, id2提示改用 ID 消除歧义完全没有匹配时报named range not found: nameOrId。删除操作同样通过 BatchUpdate 的DeleteNamedRange请求完成并携带RequiredRevisionId乐观锁。测试TestDocsNamedRangesDeleteAndReplaceByExactID验证了删除请求只携带NamedRangeId不传名字且写控制字段正确internal/cmd/docs_named_ranges_test.go。由于删除是破坏性操作文本模式输出后还会追加一行deleted true便于脚本断言结果。替换命名区域内容replacegog docs named-range replace docId nameOrId --text 新的内容 # 或从文件/标准输入读取内容 gog docs named-range replace docId nameOrId --file content.txt echo new text | gog docs named-range replace docId nameOrId --file -replace用纯文本替换整个命名区域的内容--text别名--content直接给替换文本--file从纯文本文件读取-表示标准输入支持管道二者必须提供其一否则报required: --text or --file传空字符串--text 可以清空该区域的内容。底层使用 Docs API 的ReplaceNamedRangeContentRequest。源码中有一个细节当文本为空时会通过ForceSendFields [Text]强制把空字符串序列化到请求体确保清空语义被 API 正确识别internal/cmd/docs_named_ranges.go。对应测试断言请求体中确实包含text:internal/cmd/docs_named_ranges_test.go。替换完成后命令会重新加载文档并校验区域仍在随后输出结果JSON 模式返回documentId、namedRange、replaced: true、textLength文本模式输出区域信息外加replaced true与textLength N两行。多标签Tabs文档的处理现代 Google Docs 支持一个文档包含多个标签页Tabs。gogcli 的命名区域命令对多标签文档做了完整支持--tab 标题或ID显式指定要操作的标签页。所有四个子命令都支持该参数未指定--tab时list默认列出文档根级别的命名区域对于delete/replace如果区域实际属于某个标签页源码会调用scopeDocsNamedRangeToOwningTab自动把请求限定到该区域所属的标签internal/cmd/docs_named_ranges.go通过IncludeTabsContent(true)拉取全部标签内容后逐个查找区域所在标签若同一 ID 出现在多个标签中则要求用户显式传入--tab请求体中的TabsCriteria{TabIds: [...]}字段会把删除/替换操作限定在特定标签内。测试TestDocsNamedRangesReplaceDefaultTabScopesMultiTabRequest验证了未传--tab时请求自动携带TabIds: [t.main]internal/cmd/docs_named_ranges_test.go区域 span 中的tabId、segmentId字段会在 list 输出中如实呈现便于区分区域位于哪个标签、哪个段落segment。全局 Flags所有子命令通用以下全局 flags 对所有四个子命令均可用摘自各子命令文档与 gog-docs-named-range.mdFlag类型默认值说明--access-tokenstring—直接使用提供的访问令牌绕过存储的刷新令牌令牌约 1 小时过期-a/--account/--acctstring—账号邮箱、别名或auto用于需要认证的 Google API 命令--clientstring—OAuth 客户端名选择存储的凭据与令牌桶--colorstringauto颜色输出auto/always/never--disable-commandsstring—逗号分隔的禁用命令列表支持点路径--enable-commandsstring—逗号分隔的启用命令前缀点路径可限制 CLI--enable-commands-exactstring—逗号分隔的精确启用命令父命令不会启用其子命令-n/--dry-run/--dryrun/--noop/--previewbool—不做任何修改打印将要执行的动作并以成功状态退出-y/--force/--assume-yes/--yesbool—跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全用-h/--help——显示上下文相关的帮助信息--homestring—覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse向 stdout 输出 JSON最适合脚本--no-input/--non-interactive/--noninteractivebool—永不提示直接失败适合 CI-p/--plain/--tsvboolfalse输出稳定、可解析的 TSV 纯文本无颜色--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 模式下选择逗号分隔的字段尽力而为支持点路径-v/--verbosebool—开启详细日志--version——打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中用外部不可信内容标记包裹抓取的文本字段脚本化三件套与 gogcli 其他命令一致命名区域命令在脚本化时推荐组合使用-j/--json结构化的机器可读输出-p/--plain稳定的 TSV 输出list的 TSV 行格式固定见上文-n/--dry-run先在干跑模式下预览动作再真正执行。例如批量替换前先预览gog docs named-range replace docId signature --text new --dry-run干跑不会发送任何写请求而是打印将要执行的动作docs.named-range.replace及参数字段见 internal/cmd/docs_named_ranges.go。配合--readonly还能在运行时从机制上杜绝误写。实战把命名区域串成模板刷新流程结合四个子命令可以搭建一个占位符模板刷新流水线# 1. 查看文档里现有哪些命名区域确认占位符名字 gog docs named-range list docId -j # 2. 新建一个占位区域覆盖在 {{name}} 这个字面文本上 gog docs named-range create docId --name customer --at {{name}} # 3. 替换客户名称从文件读取避免命令行转义问题 printf Acme Corp | gog docs named-range replace docId customer --file - --dry-run # 先预览 printf Acme Corp | gog docs named-range replace docId customer --file - # 4. 用完清理 gog docs named-range delete docId customer注意第 3 步的两个关键点--file -支持从 stdin 读取适合内容来自管道或包含特殊字符的场景--dry-run与真实执行之间应确认预览结果再移除--dry-run正式执行。数据模型与边界约束小结最后把命名区域的底层数据模型与约束汇总如下依据 internal/cmd/docs_named_ranges.go 与 internal/docsedit/placement.go维度约束 / 说明名字非空唯一同文档内重复创建被拒绝≤ 256 个 UTF-16 编码单元索引UTF-16 编码单元--start含、--end不含--start ≥ 1--end --start定位方式--at字面文本 可选--occurrence/--match-case与--start/--end互斥区域覆盖一个命名区域可包含多个 span不连续范围list 输出中每个 span 一行/一项多标签支持--tab指定标签delete/replace 自动限定到区域所属标签跨标签歧义时要求显式--tab并发安全所有写操作携带WriteControl.RequiredRevisionId防止覆盖他人编辑输出文本 TSV含TAB_ID、SEGMENT_ID或 JSONdocumentId/tabId/namedRanges排序确定安全--dry-run预览、--readonly全局禁止写、--no-input供 CI 使用相关命令参考父命令 gog docs、子命令 create、delete、list、replace以及完整命令索引 docs/commands/README.md。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考