gogcligog sheets copy-paste完全指南跨区域复制值/公式/格式与平铺填充fill down/across【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog sheets copy-paste是 gogcliGoogle Workspace in your terminal为 Google Sheets 提供的一键复制命令它可以将指定源区域的值、公式、格式、边框、数据验证规则或条件格式复制到目标区域并且当目标区域大于源区域时会自动把源内容平铺tile填充到整个目标范围——这是快速填充公式列、跨列扩展格式的利器。本文以 docs/commands/gog-sheets-copy-paste.md 为主线结合 internal/cmd/sheets_copy_paste.go、internal/cmd/sheets_copy_paste_test.go 与 internal/sheetsvalidation/copy.go 等源码完整讲解命令用法、每种粘贴类型的语义、平铺与转置行为、安全约束及底层实现原理读完即可在终端中可靠地完成复杂表格复制任务。一、命令概览与定位gog sheets copy-paste归属于gog sheets子命令族见 gog sheets注册于 internal/cmd/sheets.go#L48CopyPaste SheetsCopyPasteCmd cmd: name:copy-paste aliases:fill,copy-range help:Copy a ranges values/formulas/format to another range (tiles to fill down/across)除copy-paste外它还提供两个便捷别名fill与copy-range。因此下面三种写法等价gog sheets copy-paste spreadsheetId source dest gog sheets fill spreadsheetId source dest gog sheets copy-range spreadsheetId source dest与同族命令的区分gog sheets copy别名cp/duplicate是复制整个电子表格通过 Drive API而copy-paste只复制表格内的一个区域作用范围完全不同。完整用法gog sheets (sheet) copy-paste (fill,copy-range) spreadsheetId source dest [flags]三个位置参数参数说明示例spreadsheetId电子表格 ID支持normalizeGoogleID归一化见下文1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upmssource源区域A1 表示法必须包含工作表名Sheet1!A2:H71dest目标区域A1 表示法目标大于源时会平铺填充源以铺满目标Sheet1!A2:H120参数校验位于 internal/cmd/sheets_copy_paste.go#L29-L37空spreadsheetId、空source、空dest均会直接报 usage 错误。二、核心参数--type粘贴类型--type决定复制时携带哪些内容默认值为NORMAL取值范围与说明--type取值对应 Google Sheets API 常量复制内容NORMAL默认PASTE_NORMAL值 公式 格式 数据验证等价于界面里普通粘贴VALUESPASTE_VALUES仅粘贴值公式求值结果不携带格式FORMATPASTE_FORMAT仅粘贴格式颜色、边框、字体等不改动数据FORMULAPASTE_FORMULA仅粘贴公式且相对引用会按目标位置自动调整NO_BORDERSPASTE_NO_BORDERS类似 NORMAL 但不携带边框DATA_VALIDATIONPASTE_DATA_VALIDATION仅粘贴数据验证规则下拉、数字范围等CONDITIONAL_FORMATTINGPASTE_CONDITIONAL_FORMATTING仅粘贴条件格式规则源码 internal/cmd/sheets_copy_paste.go#L143-L155 中的normalizePasteType做了三项归一化输入先strings.ToUpperTrimSpace所以--type values、--type VALUES等价自动剥掉可选的PASTE_前缀--type PASTE_FORMAT合法白名单之外的值直接报错invalid --type BOGUS (expected NORMAL, VALUES, FORMAT, FORMULA, NO_BORDERS, DATA_VALIDATION, or CONDITIONAL_FORMATTING)。测试 internal/cmd/sheets_copy_paste_test.go#L76-L92 验证了非法类型返回退出码 2 且不会发出任何 API 请求capture.Last nil保证错误输入零副作用。三、平铺填充Tiling——fill down / across的原理命令描述中的 (tiles to fill down/across) 是它的招牌能力当dest尺寸大于source时Google Sheets 的CopyPasteRequest会自动把源区域平铺重复平铺以填满目标区域。典型场景# 把 Sheet1!A2:H71 中的公式向下填充到 A2:H120补全剩余 49 行 gog sheets copy-paste 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms \ Sheet1!A2:H71 Sheet1!A2:H120 --type FORMULAdest中的!在部分 shell如 bash 的历史展开下可能被转义为\!命令内部通过cleanRangeinternal/cmd/sheets.go#L29-L31统一把\!还原为!所以带不带转义均可安全使用。测试 internal/cmd/sheets_copy_paste_test.go#L18-L46 对该场景做了逐字段断言PasteType PASTE_FORMULA、PasteOrientation NORMAL源与目标在同一工作表SheetId均为 9源区域解析为行[1,71)即 A2:H71目标解析为行[1,120)即 A2:H120——目标更高即fill-down。由此可以确认只要目标的行/列数超过源Google Sheets API 就会把源内容按行列平铺重复填充这是实现整列公式填充、整行格式扩展最直接的手段无需循环逐格复制。四、--transpose转置粘贴--transpose是布尔开关默认false开启后行列互换后粘贴# 把 3 行 2 列A1:B3转置为 2 行 3 列D1:F2 gog sheets copy-paste spreadsheetId Sheet1!A1:B3 Sheet1!D1:F2 --transpose源码 internal/cmd/sheets_copy_paste.go#L43-L46 中转置与否只影响PasteOrientation字段默认为NORMAL转置时为TRANSPOSE该字段随CopyPasteRequest一并发送给 API。测试 internal/cmd/sheets_copy_paste_test.go#L62-L74 断言了PasteOrientation TRANSPOSE。注意转置 平铺的组合目标尺寸既不等于源也不等于转置尺寸行为由 API 端决定请确保目标区域尺寸与转置后的源尺寸匹配避免产生意料之外的平铺结果。五、数据验证规则的特殊处理表格感知复制这是copy-paste比裸调 Sheets API 更聪明的地方。当粘贴类型携带数据验证时pasteCarriesDataValidation判断见 internal/cmd/sheets_copy_paste.go#L134-L141覆盖PASTE_NORMAL、PASTE_FORMAT、PASTE_NO_BORDERS、PASTE_DATA_VALIDATION四种命令会额外执行表格感知的验证规则复制fetchTableValidationSpans拉取工作表中**表格Table列的验证规则区间resolveTableValidationCopyOptions计算复制选项internal/cmd/sheets_validation.go#L503-L519 等sheetsvalidation.BuildCopyRequests在 internal/sheetsvalidation/copy.go#L32-L91 中规划补充请求把源区的普通验证单元与目标区表格列验证做差分处理追加进同一批BatchUpdateSpreadsheetRequest与主CopyPaste请求一次性原子提交internal/cmd/sheets_copy_paste.go#L78-L123。实现层面使用 internal/sheetsvalidation 包提供的EffectiveCopyDestinationcopy.go#L751转置感知地计算有效目标区、FirstIntersectingSpancopy.go#L180、RelevantSourceSpanscopy.go#L300与SubtractSpansplanner.go#L327。这带来两个可预期的行为普通单元验证复制到表格列时要求源必须是表格列源否则报错copying validation into table column N in table ... requires a table-column sourcecopy.go#L54-L61普通单元格验证复制进表格列被显式拒绝copying ordinary cell validation into table column N in table ... is not supportedcopy.go#L63-L79。结果返回中新增tableManagedValidationRequests字段报告追加了多少个表格验证补充请求同时最终的 API 提交统一走runSheetsMutationinternal/cmd/sheets_mutation_helpers.go#L15-L45因此复制操作天然继承该辅助函数提供的能力dry-run 预检、账户选择、JSON 输出、人类可读结果行如Copied Sheet1!A2:H71 → Sheet1!A2:H120 (PASTE_FORMULA)。六、区域解析与越界裁剪在发起请求前命令会做两轮区域处理parseSheetRange解析 A1 表示法为结构化行列internal/cmd/sheets_validation.go#L666gridRangeFromMap结合fetchSpreadsheetRangeCatalog拉取的工作表目录SheetIDsByTitle见 internal/cmd/sheets_range_resolve.go#L23-L73把 A1 中的表名解析为数字SheetIdboundGridRangeToSheetinternal/cmd/sheets_validation.go#L422-L440负责越界裁剪当范围未显式指定结束行/列时自动用该工作表GridProperties的RowCount/ColumnCount补全避免 API 报超出网格范围。其中normalizeGoogleIDinternal/cmd/googleid.go#L10会清理用户粘贴的 spreadsheetId支持带协议/路径的完整 URL 形式方便直接复制浏览器地址栏中的表格链接作为第一个参数。七、完整 Flags 参考所有全局 flags 均适用于本命令以下为高价值项完整表格见 docs/commands/gog-sheets-copy-paste.mdFlag类型默认说明--typestringNORMAL粘贴类型NORMAL、VALUES、FORMAT、FORMULA、NO_BORDERS、DATA_VALIDATION、CONDITIONAL_FORMATTING命令专属--transposeboolfalse转置粘贴命令专属-n/--dry-run/--noop/--previewbool不真正修改表格打印预期操作并成功退出见runSheetsMutation中的dryRunExit-a/--account/--acctstring指定账户邮箱、别名或auto--clientstringOAuth client 名称选择对应凭证与 token 桶-j/--json/--machineboolfalseJSON 输出到 stdout脚本友好-p/--plain/--tsvboolfalse稳定的 TSV 文本输出无颜色--results-onlyboolJSON 模式只输出主结果丢弃nextPageToken等信封字段--select/--pick/--projectstringJSON 模式下选择逗号分隔字段支持点路径-y/--force/--assume-yesbool跳过破坏性命令确认--readonlyboolfalse运行时拦截一切变更 API 请求本命令会直接失败--no-input/--non-interactivebool永不提示改为失败CI 场景--quota-projectstring计费项目作为X-Goog-User-Project头发送--access-tokenstring直接使用传入的 access token绕过存储的 refresh token约 1 小时过期--disable-commands/--enable-commands/--enable-commands-exactstring逗号分隔的命令启用/禁用支持点路径可用来在受限环境中精确放行sheets.copy-paste--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-v/--verbosebool打开详细日志-h/--help上下文相关帮助--version打印版本并退出八、实际使用场景与组合示例1. 向下填充公式fill down——最典型用法公式相对引用自动随行调整gog sheets copy-paste 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms \ Sheet1!A2:H71 Sheet1!A2:H120 --type FORMULA2. 复制纯值去公式化——把计算区域固化为数值gog sheets copy-paste spreadsheetId Sheet1!B2:B100 Sheet1!C2:C100 --type VALUES3. 仅搬格式到更大的目标区格式平铺扩展gog sheets copy-paste spreadsheetId Sheet1!A1:H1 Sheet1!A1:H50 --type FORMAT4. 行列转置gog sheets copy-paste spreadsheetId Sheet1!A1:C10 Sheet1!E1:M3 --transpose5. 带数据验证的下拉规则复制gog sheets copy-paste spreadsheetId Sheet1!B2:B30 Sheet1!D2:D60 --type DATA_VALIDATION6. 脚本安全预演——配合--dry-run与--json先看将要发生的变更再真正执行gog sheets copy-paste spreadsheetId Sheet1!A1:A10 Sheet1!A1:A100 --type FORMULA --dry-run --json九、底层调用链速览一次copy-paste的完整数据流对应 internal/cmd/sheets_copy_paste.go#L25-L132gog sheets copy-paste └─ normalizePasteType / cleanRange / parseSheetRange 参数清洗与 A1 解析 └─ runSheetsMutation (dry-run → 选账户 → sheetsService) └─ fetchSpreadsheetRangeCatalog 拉取表 ID 目录含 grid 尺寸 └─ gridRangeFromMap boundGridRangeToSheet 解析 SheetId、越界裁剪 └─ sheets.CopyPasteRequest{Source, Destination, PasteType, PasteOrientation} └─ (携带验证时) sheetsvalidation.BuildCopyRequests 追加表格验证复制请求 └─ Spreadsheets.BatchUpdate 单批原子提交 └─ 输出文本行 Copied src → dest (TYPE) 或 JSON 载荷结果文本Copied Sheet1!A2:H71 → Sheet1!A2:H120 (PASTE_FORMULA)JSON 载荷字段source、dest、typePASTE_*形式、orientationNORMAL/TRANSPOSE、tableManagedValidationRequests补充的表格验证请求数。十、常见错误与排查错误信息原因与处理empty spreadsheetId/empty source range/empty dest range必填参数为空检查位置参数是否传全源码 sheets_copy_paste.go#L29-L37invalid --type X (...)--type不在白名单内大小写不敏感、PASTE_前缀可选sheets_copy_paste.go#L143-L155退出码 2 且不发请求copying validation into table column ... requires a table-column source把普通验证复制进表格列但源不是表格列copy.go#L54-L61copying ordinary cell validation into table column ... is not supported普通单元格验证复制进表格列属显式不支持copy.go#L63-L79未知工作表名source/dest的表名不存在于目录映射检查表名拼写与引号越界报错使用boundGridRangeToSheet自动补全未指定行列若仍越界检查目标尺寸与源/转置尺寸是否匹配结语gog sheets copy-paste用一个命令把 Google Sheets API 的CopyPaste能力封装成了可脚本化的终端工具支持 7 种粘贴类型、目标区自动平铺填充fill down/across、一键转置并针对表格列的数据验证做了源码级的边界保护配合--dry-run、--json、--plain等输出控制可以无缝嵌入自动化流水线。如需查看同族命令可继续阅读 gog sheets 与 命令索引。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考