)
gogcli 的gog sheets update-note命令在终端中为 Google Sheets 单元格设置与清除批注Notes【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog sheets update-note是 gogcliGoogle Workspace in your terminal中用于**设置或清除单元格批注cell note**的核心命令。批注是附在单元格上的说明性文本不占用单元格值本身常用于数据标注、审阅意见与协作上下文。读完本文你将掌握如何通过一条 CLI 命令为单个或多个单元格批量写入/清空批注、如何从文件注入多行批注文本、如何以 JSON 输出接入脚本与 AI Agent 流程以及该命令底层基于 Google SheetsbatchUpdaterepeatCell的实现原理与测试验证。一、命令概览与定位gog sheets update-note归属于gog sheets子命令家族其别名为set-note在 internal/cmd/sheets.go 中的注册定义为UpdateNote SheetsUpdateNoteCmd cmd: name:update-note aliases:set-note help:Set or clear a cell note基本用法来自 docs/commands/gog-sheets-update-note.mdgog sheets (sheet) update-note (set-note) spreadsheetId range [flags]其中spreadsheetId目标电子表格 ID也支持传入完整 URL源码通过normalizeGoogleID自动抽取 IDrangeA1 记法表示的单元格或区域例如Sheet1!A1或Sheet1!A1:B2--note/--note-file批注文本来源两者至少提供其一。与同家族的读取命令gog sheets notesgog sheets notes配套使用可以构成读取批注 → 修改/清空批注的完整闭环。二、核心参数与批注文本来源命令的 Go 结构体定义在 internal/cmd/sheets_update_note.gotype SheetsUpdateNoteCmd struct { SpreadsheetID string arg: name:spreadsheetId help:Spreadsheet ID Range string arg: name:range help:A1 cell or range (eg. Sheet1!A1 or Sheet1!A1:B2) Note *string name:note help:Note text to set (use --note to clear notes) NoteFile string name:note-file help:Path to file containing note text type:existingfile }2.1--note直接指定批注文本gog sheets update-note 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms Sheet1!A1 --note 这是单元格 A1 的批注类型为*string指针因此空字符串是合法输入--note 表示清除该区域的批注。若既不提供--note也不提供--note-file命令会直接报错退出见下文参数校验。2.2--note-file从文件注入批注gog sheets update-note spreadsheetId Sheet1!A1 --note-file ./note.txt该参数类型标注为existingfileCLI 框架kong会先校验文件必须存在文件内容会原样作为批注文本支持多行内容含换行符优先级规则源码中--note-file优先于--note即同时给出两者时以文件内容为准if c.NoteFile ! { data, err : os.ReadFile(c.NoteFile) ... noteText string(data) hasNote true } else if c.Note ! nil { noteText *c.Note hasNote true }这一设计非常适合注入多行模板、Markdown 说明或由上游工具生成的批注文本。2.3 位置参数预处理命令在进入 API 调用前会对参数做两处标准化见 internal/cmd/sheets_update_note.gonormalizeGoogleID对spreadsheetId做归一化传入完整 Google Sheets 分享链接也能正确抽取 ID实现见 internal/cmd/googleid.gocleanRange将\!还原为!。因为 bash 等 shell 会对!做历史展开用户往往需要转义为\!该函数在 internal/cmd/sheets.go 中实现func cleanRange(r string) string { return strings.ReplaceAll(r, \!, !) }三、完整 Flags 参考表以下 Flags 继承自根命令并适用于本命令来源文档 gog-sheets-update-note.mdFlag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过存储的 refresh token令牌约 1 小时过期-a--account--acctstring账户邮箱、别名或auto用于所有需要认证的 Google API 命令--clientstringOAuth 客户端名称选择存储的凭据 token 桶--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最适合脚本化--no-input--non-interactive--noninteractivebool永不提示遇到需要输入时直接失败适合 CI--note*string要设置的批注文本使用--note 清除批注--note-filestring包含批注文本的文件路径-p--plain--tsvboolfalse输出稳定可解析的文本到 stdoutTSV无颜色--quota-projectstring用于计费的 Google Cloud 项目以X-Goog-User-Project发送部分 API 在配合--access-token或 ADC 时需要--readonlyboolfalse运行时阻止一切变更类 API 请求auth add同时只申请只读 OAuth scope--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等信封字段--select--pick--projectstringJSON 模式下按逗号分隔选择字段尽力而为支持点路径多数命令更推荐使用--fields-v--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出时将获取的文本字段包裹在外部不可信内容标记中其中与写操作直接相关的安全 Flags 包括--dry-run预演、--readonly拦截变更请求、--no-inputCI 场景与-y/--force跳过确认。四、实战示例4.1 为单个单元格设置批注gog sheets update-note 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms Sheet1!A1 \ --note 该列为 2026 财年营收预估值请以财报为准文本模式输出Set note on Sheet1!A14.2 为整个区域批量写入同一批注gog sheets update-note spreadsheetId Sheet1!A1:B2 --note 待财务复核命令会将该批注应用到区域内全部单元格输出Set note on 4 cells in Sheet1!A1:B24.3 清除批注gog sheets update-note spreadsheetId Sheet1!A1:B2 --note 输出Cleared note on 4 cells in Sheet1!A1:B2注意清除是通过写入空字符串实现的并且源码特意使用ForceSendFields []string{Note}强制发送空字段确保 API 能够把批注真正置空而非因省略字段被忽略。4.4 从文件注入多行批注cat approval-note.txt EOF 待审批 负责人aliceexample.com 截止时间本周五 EOF gog sheets update-note spreadsheetId Sheet1!C5 --note-file approval-note.txt4.5 JSON 输出脚本与 Agent 友好gog sheets update-note spreadsheetId Sheet1!A1 --note Hello --json输出示例结构来自源码 internal/cmd/sheets_update_note.go{ spreadsheetId: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms, range: Sheet1!A1, cellsUpdated: 1, note: Hello }该结构非常适合被 CI 脚本、自定义流水线或 LLM Agent 直接解析配合--results-only可进一步只保留主结果字段。4.6 预演模式gog sheets update-note spreadsheetId Sheet1!A1 --note 测试 --dry-run--dry-run会调用dryRunExit实现见 internal/cmd/dryrun.go以操作标识sheets.update-note输出预期的请求负载spreadsheet_id、range、note不会真正向 Google API 发送变更请求适合在自动化前验证参数正确性。五、底层原理一次repeatCell批量更新命令核心逻辑位于 internal/cmd/sheets_update_note.go调用的是 Google Sheets API 的Spreadsheets.BatchUpdate并构造RepeatCellRequestgridRange, err : gridRangeFromMap(parsed, sheetIDs, note) ... cellData : sheets.CellData{ Note: noteText } if noteText { cellData.ForceSendFields []string{Note} } batchReq : sheets.BatchUpdateSpreadsheetRequest{ Requests: []*sheets.Request{ { RepeatCell: sheets.RepeatCellRequest{ Range: gridRange, Cell: cellData, Fields: note, }, }, }, }关键设计点Fields: note字段掩码repeatCell只更新批注字段绝不会误伤单元格的值、格式、公式等其他属性Sheet 名称 → Sheet ID 解析gridRangeFromMap依赖fetchSheetIDMap见 internal/cmd/sheets_validation.go先把Sheet1这类标题映射为数字sheetId再构造GridRange。toGridRange对第一个 sheetsheetId 0也通过ForceSendFields强制发送避免 0 值被 Go API 客户端省略区域展开cellsUpdated通过(EndRow-StartRow1) * (EndCol-StartCol1)计算与 API 返回的实际更新单元格数一致A1 解析要求parseSheetRange见 internal/cmd/sheets_validation.go强制要求范围必须包含 sheet 名因此A1这类缺表名写法会被拒绝提示range must include a sheet name。参数校验清单源码确认场景行为spreadsheetId为空报错empty spreadsheetIdrange为空报错empty range既无--note也无--note-file报错provide --note or --note-filerange 缺少 sheet 名报错range must include a sheet namerange 中引用了不存在的 sheet报错unknown sheet ... in note range六、与gog sheets notes组合批注读写闭环写入批注后可用 gog sheets notes 命令读回验证gog sheets notes spreadsheetId Sheet1!A1:B2该命令源码见 internal/cmd/sheets_notes.go通过Spreadsheets.GetIncludeGridData(true)拉取网格数据仅请求note与formattedValue字段随后把批注单元格输出为表格文本模式或 JSON 数组--json模式字段包含sheet、a1、row、col、value、note。读取时对表格/TSV 输出做了换行转义处理\n与\t保证多行批注在纯文本输出中保持可解析。典型工作流# 1. 写入/更新批注 gog sheets update-note spreadsheetId Sheet1!A1 --note 已复核 # 2. 读回并确认 gog sheets notes spreadsheetId Sheet1!A1:B10 --json # 3. 复核后清除 gog sheets update-note spreadsheetId Sheet1!A1 --note 七、行为验证测试用例如何保证正确性命令的单元测试位于 internal/cmd/sheets_update_note_test.go通过httptest模拟 Sheets API并用expectRepeatCellRequest断言发出的repeatCell请求细节fields note、cell.note内容、GridRange的起止行列测试用例验证点TestSheetsUpdateNoteCmd_SingleCell_JSON单单元格写入Hello worldcellsUpdated 1请求范围A1endRow1, endCol1TestSheetsUpdateNoteCmd_Range_JSON区域Sheet1!A1:B2写入同一批注cellsUpdated 4endRow2, endCol2TestSheetsUpdateNoteCmd_ClearNote_Text--note 时输出包含Cleared note且空串批注被发送TestSheetsUpdateNoteCmd_NoteFile三行文件内容Line 1\nLine 2\nLine 3被完整写入批注TestSheetsUpdateNoteCmd_MissingNote缺--note时返回provide --note or --note-fileTestSheetsUpdateNoteCmd_MissingSheetNameA1缺表名返回range must include a sheet name这些用例同时覆盖了参数校验、多行文本、范围展开与空值清除四条关键路径可作为扩展该命令时的行为基准。八、前置条件与安全提示认证命令依赖已配置的 Google 账户凭据请先完成gog auth add或gog auth setup参见 快速开始 与 gog auth 文档。多账户场景通过-a/--account指定或使用--access-token直接注入临时令牌权限范围设置批注属于写操作账户的 OAuth 授权需包含 Sheets 写入相关 scope使用--readonly时该命令的变更请求会在运行时被拦截批量写入语义update-note会把同一段批注应用到整个 A1 区域的所有单元格若只想标注个别单元格请精确给出单元格地址或拆分为多次调用批注 ≠ 评论本命令处理的是单元格note批注与 Google Sheets 的线程化评论comments不同后者由gog docs comments等命令族管理配额计费在需要计费归属的云项目环境中可通过--quota-project指定用于 API 配额的项目。相关文档gog sheets ——gog sheets命令族总览含全部子命令与共享 Flagsgog sheets notes —— 读取单元格批注的配套命令Command index —— 完整命令索引源码internal/cmd/sheets_update_note.go、internal/cmd/sheets_update_note_test.go、internal/cmd/sheets_notes.go、internal/cmd/sheets.go【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考