企业官网建设流程全解析

gogcli 实战指南：用gog slides element group在终端组合 Google Slides 元素

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli

本篇技术指南讲解 gogcli（Google Workspace in your terminal 命令行工具）中gog slides element group子命令的完整用法：它用于把同一页幻灯片上的两个或更多原生页面元素（形状、线条、文本框等）组合成一个可整体移动、缩放与排版的元素组。读完本文，你将掌握该命令的参数格式、--group-id的自动生成与校验规则、底层 Slides API 调用原理（GroupObjectsRequest）、以及如何结合--dry-run、--json等全局安全开关进行可复现的批量编排。

命令概览

gog slides element group是 gog slides element 家族下的一个子命令，其职责是“Group two or more elements”（组合两个或更多元素），对应的命令入口定义在 internal/cmd/slides_element.go 的SlidesElementGroupCmd结构体中：

Group SlidesElementGroupCmd `cmd:"" name:"group" help:"Group two or more elements"`

用法

gog slides (slide) element group <presentationId> <objectId> ... [flags]

从源码看，该命令的结构体声明如下（slides_element.go）：

type SlidesElementGroupCmd struct { PresentationID string `arg:"" name:"presentationId" help:"Presentation ID"` ObjectIDs []string `arg:"" name:"objectId" help:"Two or more page element object IDs"` GroupID string `name:"group-id" help:"Optional stable group object ID"` }

典型示例

把两个元素组合为一个组，并显式指定稳定的组 ID：

gog slides element group 1ABCDEfGhIjKlMnOpQrStUv 2wXyZ3aBcD4eFg5hI6jK7lM --group-id my_chart_group

不指定--group-id时，gogcli 会自动生成一个组 ID（见下文“对象 ID 规则”）：

gog slides element group 1ABCDEfGhIjKlMnOpQrStUv shape_101 shape_102

docs/slides-structure.md中给出的组合配套示例（含后续解组）：

gog slides element group <presentationId> <objectId> <objectId>... --group-id <groupId> gog slides element ungroup <presentationId> <groupId>...

--group-id参数：稳定对象 ID 与自动生成规则

--group-id是gog slides element group独有的核心参数，帮助信息为Optional stable group object ID（可选的稳定组对象 ID）。

自动生成

当不传--group-id时，源码调用slidesElementObjectID(c.GroupID, "gogGroup")（slides_element.go）：

func slidesElementObjectID(value, prefix string) (string, error) { value = strings.TrimSpace(value) if value == "" { return newSlidesStructuralObjectID(prefix), nil } ... }

自动生成的 ID 形如gogGroup<UnixNano 时间戳>，例如gogGroup1700000000123456789。其实现位于 internal/cmd/slides_structural.go：

func newSlidesStructuralObjectID(prefix string) string { return fmt.Sprintf("%s%d", prefix, time.Now().UnixNano()) }

显式指定时的校验

若手动传入--group-id，会校验正则^[A-Za-z0-9_][A-Za-z0-9_:-]{4,49}$（slides_element.go），即：

• 长度必须为 5～50 个字符；
• 仅允许字母、数字、下划线_、连字符-、冒号:，且首字符不能是-或:。

不合法时返回 usage 错误object ID must be 5-50 characters and contain only letters, digits, _, -, or :，测试用例TestSlidesElementValidation中的{"object ID", ... ObjectID: "bad!"}验证了这一点（slides_element_test.go）。

建议：在需要后续引用该组的场景（例如接着用gog slides element ungroup、gog slides element transform对组做整体变换），使用稳定的--group-id，避免依赖自动生成的随机 ID。

输入校验：至少两个元素、去重与同页约束

Run方法首先调用slidesElementTargets(c.PresentationID, c.ObjectIDs, 2)（slides_element.go），第三个参数2表示最少需要两个 object ID。该校验函数（slides_element.go）会执行以下检查：

1. presentationId不能为空；
2. 每个objectId不能为空（会被 trim 后校验）；
3. 拒绝重复 ID：出现重复时返回duplicate objectId %q；
4. 数量下限：少于 2 个时报错at least 2 objectId value(s) required。

测试用例对应（slides_element_test.go）：

{"group count", &SlidesElementGroupCmd{PresentationID: "p", ObjectIDs: []string{"one"}}, "at least 2"},

此外，docs/slides-structure.md明确提醒（slides-structure.md）：

z-ordertargets must share one slide and must not be grouped.groupneeds at least two ungrouped elements on one slide; Slides does not permit every element kind to be grouped.

即：被组合的元素必须位于同一页且本身未被组合过，同时 Slides 不允许所有元素类型都能被组合（例如某些特殊类型元素无法入组）。

底层实现：GroupObjectsRequest 与批处理提交

校验通过后，gogcli 构造一个GroupObjectsRequest并放入BatchUpdatePresentationRequest批量请求（slides_element.go）：

request := &slides.Request{GroupObjects: &slides.GroupObjectsRequest{ ChildrenObjectIds: objectIDs, GroupObjectId: groupID, }}

随后交由runSlidesElementMutation→runSlidesElementBatchMutation（slides_element.go）执行：

1. 将请求封装为BatchUpdatePresentationRequest；
2. 若非破坏性操作，先走dryRunExit（支持--dry-run）；
3. 通过requireAccount(flags)解析账号；
4. 调用slidesService(...)获取 Slides API 服务；
5. 执行svc.Presentations.BatchUpdate(presentationID, body).Context(ctx).Do()提交到 Google Slides API；
6. 输出结果：JSON 模式下输出presentationId、objectIds、groupObjectId；文本模式输出Created group <groupID>。

命令的操作元数据（用于审计与 dry-run 展示）：

Op: "slides.element.group", Action: "group elements", Output: map[string]any{"presentationId": presentationID, "objectIds": objectIDs, "groupObjectId": groupID}, Text: fmt.Sprintf("Created group %s", groupID),

注意：group被归类为非破坏性操作（未设置Destructive字段），因此不需要--force确认；而删除类命令（如gog slides element delete）才需要确认或--force。

测试验证

单元测试 TestSlidesElementStructuralRequests 通过 mock 服务器捕获请求，验证了组合请求的结构：

t.Run("group", func(t *testing.T) { request := captureSlidesElementRequest(t, &SlidesElementGroupCmd{ PresentationID: "pres1", ObjectIDs: []string{"shape1", "line1"}, GroupID: "group_123", }, &RootFlags{Account: "a@b.com"}) if request.GroupObjects == nil || request.GroupObjects.GroupObjectId != "group_123" || len(request.GroupObjects.ChildrenObjectIds) != 2 { t.Fatalf("unexpected group request: %+v", request) } })

同时 TestSlidesElementDryRunSkipsService 验证了 dry-run 模式不会真正创建 Slides 服务、不会发起网络请求，而是在 stdout 输出"op": "slides.element.group"与"groupObjects"意图载荷。

组合后的后续操作

组合完成后，返回的groupObjectId可作为新对象 ID 参与其他元素操作：

• 整体变换：gog slides element transform <presentationId> <groupObjectId> --rotate 45，对整个组统一旋转/缩放/平移；
• 解除组合：gog slides element ungroup <presentationId> <groupId>...，底层使用UngroupObjectsRequest（slides_element.go）；
• 删除：gog slides element delete <presentationId> <groupObjectId> --force（破坏性操作，需确认或--force）。

全局 Flags 一览

gog slides element group继承 gogcli 全命令共用的全局 Flags（与本命令专属的--group-id并列使用）：

常用组合示例

安全预演 + 脚本化输出：

# 先 dry-run 查看将要提交的 batch update 载荷（不会调用 API） gog slides element group 1ABCDEfGhIjKlMnOpQrStUv shape_101 shape_102 --dry-run --json # CI 中静默执行，输出 JSON 以便提取 groupObjectId gog slides element group 1ABCDEfGhIjKlMnOpQrStUv shape_101 shape_102 \ --group-id revenue_group --json --no-input -a auto # 用 jq 提取返回的组 ID 供后续 transform / ungroup 使用 GID=$(gog slides element group ... --json | jq -r '.groupObjectId')

相关命令与文档

• 父命令：gog slides element（创建形状/线条、变换、样式、z-order、分组、alt-text、删除）
• 逆操作：gog slides element ungroup
• 场景指南：docs/slides-structure.md（元素堆叠、分组、标注与删除的配套用法）
• 完整命令索引：docs/commands/README.md
• 源码入口：internal/cmd/slides_element.go（命令定义与实现）、internal/cmd/slides_element_test.go（请求捕获与校验测试）

提示：本文所描述的命令参考页由gog schema --json自动生成（见 docs/commands/gog-slides-element-group.md），若需在本地查看最新命令说明，可运行make docs-commands重新生成命令文档。

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli