gogcli 幻灯片原生图形创建指南深入解析gog slides element create-shape命令【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog slides element create-shape是 gogcliGoogle Workspace in your terminal提供的 Google Slides 原生图形创建命令允许你在终端中直接向指定幻灯片添加矩形、文本框、椭圆等可编辑图形元素而无需先渲染图片。阅读本文后你将掌握该命令的完整参数体系、几何定位规则、稳定对象 ID 的使用方法以及它底层如何调用 Google Slides API 的CreateShapeRequest批量更新请求从而能够编写出可复现、可脚本化的幻灯片自动排版流程。命令概览gog slides element create-shape位于gog slides element子命令组之下gog-slides-element.md与create-line、style、transform、z-order、group、ungroup、alt-text、delete等命令共同构成一套完整的原生页面元素操作工具链。它的核心作用是在指定演示文稿的指定幻灯片上创建一个符合 Google Slides 原生格式的图形shape——这意味着创建出来的图形是原生元素后续可以直接用 style、transform 等命令继续编辑而不是一张不可再编辑的静态图片。命令语法gog slides (slide) element create-shape presentationId slideId [flags]其中presentationId目标演示文稿 ID必填位置参数slideId目标幻灯片对象 ID必填位置参数可通过gog slides list-slides presentationId获取。该命令由 internal/cmd/slides_element.go 中的SlidesElementCreateShapeCmd结构体实现其在命令树中的注册名为create-shape帮助文本为 Create a native shape on a slide源码第 17 行。完整 Flags 参数表下表完整列出该命令支持的全部 Flags源自 gog-slides-element-create-shape.mdFlag类型默认值说明--access-tokenstring直接使用提供的 access token绕过存储的 refresh tokentoken 约 1 小时过期-a--account--acctstring账户邮箱、别名或 auto用于需要认证的 Google API 命令--clientstringOAuth 客户端名称选择已存储的凭据与 token bucket--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 安全选项--heightfloat64100图形高度-h--helpkong.helpFlag显示上下文相关帮助--homestring覆盖 gogcli config/data/state/cache 根目录等价于 GOG_HOME-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本处理--no-input--non-interactive--noninteractivebool永不提示改为失败退出适用于 CI--object-idstring可选的稳定对象 ID允许 5-50 个字符-p--plain--tsvboolfalse向 stdout 输出稳定、可解析的文本TSV无颜色--quota-projectstring用于计费的 Google Cloud 项目作为 X-Goog-User-Project 发送部分 API 配合 --access-token 或 ADC 时需要--readonlyboolfalse运行时阻止修改类 API 请求auth add 也请求只读 OAuth 范围--results-onlyboolJSON 模式下仅输出主要结果丢弃 nextPageToken 等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔字段尽力而为支持点路径--typestringRECTANGLESlides 图形类型例如 RECTANGLE、TEXT_BOX、ELLIPSE--unitstringPT几何单位-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--widthfloat64100图形宽度--wrap-untrustedboolfalseJSON/raw 输出时将获取的文本字段包裹在外部不可信内容标记中--xfloat640左边位置--yfloat640顶部位置其中与图形创建直接相关的命令级 Flags 在源码 internal/cmd/slides_element.go 中定义其余为继承自gog slides element/gog slides/gog的全局 Flags。图形类型--type--type指定要创建的 Slides 图形类型默认值为RECTANGLE。官方帮助中给出三个典型示例RECTANGLE矩形、TEXT_BOX文本框、ELLIPSE椭圆。该参数在提交前会经过normalizeSlidesEnum归一化处理internal/cmd/slides_element.go先将输入转为大写再把连字符-和空格替换为下划线_。因此--type round-rectangle会被归一化为ROUND_RECTANGLE--type TEXT_BOX、--type text-box均合法且等价。归一化后若结果为空则回退到RECTANGLE若结果为TYPE_UNSPECIFIED命令会直接以用法错误退出--type must name a concrete Slides shape type因为 API 要求具体图形类型不能使用未指定占位值。几何定位与尺寸--x、--y、--width、--height、--unit图形的几何属性由五个 Flags 共同决定--x默认 0图形左上角的水平位置左侧坐标--y默认 0图形左上角的垂直位置顶部坐标--width默认 100图形宽度--height默认 100图形高度--unit默认PT以上所有数值的几何单位取值只能是PT磅或EMUEnglish Metric Units英制公制单位。单位参数在源码中通过枚举校验严格限定slidesElementEnum(c.Unit, PT, PT, EMU)internal/cmd/slides_element.go传入其他值如CM、PX会得到明确的用法错误。需要特别注意的是尺寸校验--width与--height都必须大于 0否则命令以--width and --height must be 0拒绝执行源码第 57-59 行。这与兄弟命令create-line的规则不同——线条允许某个维度为 0水平或垂直直线而图形必须同时具备有效的宽和高。从底层实现看这些参数最终被组装进slidesElementPropertiesinternal/cmd/slides_element.go--x/--y写入AffineTransform.TranslateX/TranslateY--width/--height写入Size.Width/HeightScaleX/ScaleY固定为 1初始无缩放全部使用同一--unit单位。稳定对象 ID--object-id--object-id用于为新建图形指定一个稳定、可预测的对象 ID。该命令的默认 ID 前缀为gogShape即不传该参数时由newSlidesStructuralObjectID生成类似gogShape...的唯一 ID。指定--object-id的价值在于让后续脚本化的编辑操作变得确定性例如先在脚本里创建图形并指定--object-id box1之后就可以直接对box1执行 style设置填充/描边、transform移动/缩放/旋转、alt-text无障碍文本等命令无需从 API 响应中解析返回的随机 ID。对象 ID 遵循 Google Slides API 的格式约束源码通过正则^[A-Za-z0-9_][A-Za-z0-9_:-]{4,49}$校验internal/cmd/slides_element.go总长度 5-50 个字符首字符为字母、数字或下划线其余字符只能包含字母、数字、下划线、连字符-或冒号:。不符合规则的 ID如bad!会返回用法错误object ID must be 5-50 characters and contain only letters, digits, _, -, or :对应测试见 internal/cmd/slides_element_test.go。源码实现从 Flags 到 API 请求的完整链路整个执行链路集中在SlidesElementCreateShapeCmd.Runinternal/cmd/slides_element.go可概括为五个阶段目标校验slidesElementPageTarget对两个位置参数去除首尾空格并拒绝空值源码第 610-620 行。参数归一化与校验图形类型经normalizeSlidesEnum归一化并拒绝TYPE_UNSPECIFIED宽高必须大于 0单位必须是PT或EMU对象 ID 按上述格式校验。构造请求组装slides.Request{CreateShape: slides.CreateShapeRequest{...}}将对象 ID、图形类型、页面元素属性所属幻灯片、尺寸、仿射变换填入源码第 68-72 行。Dry-run 短路runSlidesElementMutation首先调用dryRunExit——若指定了--dry-run命令只打印预期的批量更新请求包含slides.element.create-shape操作和createShape请求体并以成功状态退出不会创建 Slides 服务、不会接触 Google API。测试TestSlidesElementDryRunSkipsService专门验证了这一点dry-run 模式下若尝试创建服务会直接导致测试失败internal/cmd/slides_element_test.go。提交变更通过requireAccount解析账户slidesService创建 Slides 服务最终调用svc.Presentations.BatchUpdate(presentationID, body)源码第 464-474 行——即 Google Slides API 的presentations.batchUpdate端点将CreateShape请求原子地提交到目标演示文稿。输出格式文本模式默认输出一行Created shape objectIdJSON 模式--json输出结构化结果包含presentationId、slideObjectId、objectId、shapeType四个字段源码第 83-88 行便于脚本捕获新建图形的对象 ID 以继续后续操作。实战示例基本用法在幻灯片上添加矩形# 获取演示文稿与幻灯片 ID gog slides list-slides presentationId --json # 在指定幻灯片上创建默认矩形RECTANGLE100x100 PT位于原点 gog slides element create-shape presentationId slideId定位与调整尺寸# 创建圆角矩形位置 (24, 24)尺寸 180x80 PT gog slides element create-shape presentationId slideId \ --type ROUND_RECTANGLE --x 24 --y 24 --width 180 --height 80该组合在 docs/slides-structure.md 的 Native elements 章节中作为官方示例出现。使用 EMU 单位与稳定 ID# 以 EMU 为单位创建椭圆并指定稳定对象 ID 供后续脚本引用 gog slides element create-shape presentationId slideId \ --type ELLIPSE --unit EMU --width 914400 --height 914400 --object-id deco_circle配合 dry-run 预检# 不修改任何内容仅打印将提交的批量更新请求 gog slides element create-shape presentationId slideId \ --type TEXT_BOX --x 50 --y 60 --width 300 --height 120 --dry-run --json完整自动化链路# 1. 创建文本框并固定 ID gog slides element create-shape presentationId slideId \ --type TEXT_BOX --x 24 --y 24 --width 180 --height 80 --object-id title_box --json # 2. 插入文本insert-text 命令 gog slides insert-text presentationId title_box --text Q3 Report # 3. 设置填充色与边框 gog slides element style presentationId title_box \ --fill-color #3367d6 --outline-color #ffffff --outline-weight 2常见错误与排查错误信息原因解决方法--type must name a concrete Slides shape type传入了TYPE_UNSPECIFIED指定具体类型如RECTANGLE、TEXT_BOX、ELLIPSE、ROUND_RECTANGLE--width and --height must be 0宽度或高度 ≤ 0确保两者均为正数object ID must be 5-50 characters...对象 ID 含非法字符或长度越界遵循^[A-Za-z0-9_][A-Za-z0-9_:-]{4,49}$格式invalid value ... expected one of PT, EMU--unit传入了非 PT/EMU 值仅使用PT或EMU测试与验证仓库提供了完整的单元测试来保证该命令的行为契约internal/cmd/slides_element_test.goTestSlidesElementCreateShape第 37-64 行构造SlidesElementCreateShapeCmdround-rectangle类型、坐标 (12,24)、尺寸 200x80、单位 PT、IDshape_123通过 mock 服务捕获实际提交的CreateShape请求断言对象 ID 为shape_123、类型被归一化为ROUND_RECTANGLE、元素属于slide1、宽高为 200/80、平移坐标为 12/24、缩放为 1/1TestSlidesElementDryRunSkipsService第 215-237 行验证--dry-run时不创建 Slides 服务且输出包含op: slides.element.create-shape与createShapeTestSlidesElementValidation第 239-274 行验证宽高非正、非法对象 ID 等输入会以退出码 2 的用法错误拒绝。相关命令创建图形之后通常需要配合以下命令完成完整排版gog slides element create-line创建原生线条gog slides element style设置图形填充/描边或线条样式gog slides element transform移动、缩放、旋转或替换元素变换gog slides element z-order调整元素堆叠顺序gog slides element group / ungroup组合或取消组合元素gog slides element alt-text设置或清除无障碍文本gog slides insert-text向形状或表格插入文本gog slides element delete删除一个或多个页面元素。完整的命令索引见 docs/commands/README.md更多 Slides 原生元素工作流可参考 docs/slides-structure.md。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考