google-slides

Google Slides 创作

坐标单位为点，原点在幻灯片左上角；标准幻灯片尺寸为 720x405 （read_slide_layout 会报告实际尺寸）。所有对象均通过 read_presentation 返回的 objectId 寻址。请传入最新一次读取或写入返回的 requiredRevisionId，这样发生并发编辑时，写入会失败，而不是破坏内容。

创建新演示文稿：先排版，再查看

将每张幻灯片编排成布局，而不是逐个设置坐标。compose_slide 接受树结构（堆叠、网格、卡片、文本、图片）或 HTML/CSS 子集，并在一次调用中完成整张幻灯片的布局：同级元素尺寸相同、间距均匀、垂直居中，并自动确保对比度配对；文本可以设置 fit: "shrink"，返回结果包含每个元素的框以及布局检查结果。每张幻灯片：

1. 添加布局为 BLANK 的幻灯片（或对演示文稿的第一张幻灯片设置 clear: true），然后调用 compose_slide，每次都使用相同的 theme（调色板角色 background/surface/primary/textSecondary 和字体系列）。树中的颜色是角色，而不是十六进制色值，因此修改一次主题即可重新设置整套演示文稿的样式。
2. 查看返回结果中的 issues。text_overflow 表示需要缩短文本、设置 fit: "shrink"，或增大节点的 size；overlap 表示两个节点占用了重叠的框（通常是需要添加 gap 的行）。
3. 每张幻灯片调用一次 get_slide_thumbnail（LARGE）并查看缩略图：注意是否拥挤、角落是否留白过多、标题是否像正文、图片是否与调色板冲突。通过重新编排幻灯片进行修正（先删除旧元素，或在新的 BLANK 幻灯片上编排，再用 delete_object 删除旧元素）。

树结构示例（列式根节点；根节点的框为幻灯片尺寸减去 48 pt 边距）：

• 标题页：使用 stack column justify:center，包含一个 display 文本和一个 h2 副标题；副标题使用 textSecondary，两者均设置 align:center。
• KPI 卡片：先放置 h1，然后放置由多个 card 组成的 stack row size:150 gap:24；每个卡片包含一个 caption 标签（textSecondary）和其下方的 kpi 数值。
• 文本 + 图片：使用 stack row gap:32，包含一个 body 文本（bullets:true、size:{flex:1}）和一张图片（size:{flex:1}）；图片会按纵横比适配。
• 议程：使用一个包含换行分隔条目且设置了 bullets:true 的 body 文本。

HTML 形式的结果相同：<section style="background:#0B2A4A; padding:48pt; gap:24pt">，其中包含 <h1>、由 <article class="card"><span class="caption">…</span><span class="kpi">…</span></article> 组成的 <div style="display:flex; gap:24pt; height:150pt">、<ul><li> 项目符号列表，以及 <img style="flex:1">。 只有文档说明的标签和属性可以编译；其他内容都会按名称拒绝，不会被忽略。

编辑现有演示文稿：放置、检查、修正、查看

对于已有内容的演示文稿，或树结构无法表示的元素：

1. 对任何卡片、文本或图片的行、列或网格使用 insert_grid（一次调用即可对齐并设置相同尺寸）；单个元素使用 insert_text_box / insert_shape / insert_image。
2. 使用 read_slide_layout 查看每个元素的框、z 顺序、文本样式、估算的换行高度（textFit.fits）和 issues。修正所有 error 和 warn（text_overflow、overlap、off_slide、low_contrast；其中会指出实际位于文本后方的填充色）；如果修正成本较低，也应处理 info 项（near_miss_alignment、unequal_peers、tight_margin、empty_placeholder）。
3. 布局检查通过后，调用一次 get_slide_thumbnail 并查看缩略图。

网格规范（手动放置时）

标题位于 x 40、y 32，宽 640，高 60-70，适用于一行 28-34 pt 的标题（两行需要约 110）；副标题置于标题下方，字号为 16-18 pt。内容区域位于 x 40、y 130，尺寸为 640 x 235（insert_grid 的默认值）。页脚位于 y 370，字号为 12 pt。除非元素有意设置为满版，否则左右边距保持 40 pt。流程图： 使用 insert_grid 放置步骤形状（列数 = 步骤数），然后在相邻形状之间调用 connect_shapes；移动形状时，连接线会随之移动。

在 600 pt 宽的文本框中，34 pt 的粗体标题超过约 32 个字符就会换行，并溢出到下方的任何内容上方（API 不会自动增大文本框）。布局读取结果中的 textFit 和 compose 返回结果中的 issues 会预测此问题；长标题可改为 24-28 pt、设置 fit: "shrink"，或分成两行并将副标题下移。

配色与对比度

先选定一套配色，并在每张幻灯片上重复使用（作为 compose_slide 的 theme.palette）：背景色、一种卡片/表面颜色、一种强调色，以及一种 次要文本颜色；文字颜色会自动推导。用户指定模板或品牌时，使用其配色；否则，以下配色组合本身符合 WCAG AA：

• 深色：背景 #0B2A4A，卡片 #1E4976，强调色 #4FC3F7，标题/文本 #FFFFFF，次要文本 #B8CCE0。
• 浅色：背景 #FFFFFF，卡片 #F1F3F4，强调色 #0B57D0（强调色上使用白色文本）， 文本 #202124，次要文本 #444746。

彩色填充上的文本颜色不会自动设置为合适值：每次添加文本时，都要根据文本 背后的填充（卡片的填充，而不是幻灯片的填充）选择文本颜色。不要在中间色 背景上使用中灰色；白色背景上的次要文本应为 #444746 或更深（#5F6368 勉强 达标，更浅则不合格）。对于模板或品牌配色，在编写之前，对打算使用的每一组 文本/填充颜色调用 check_contrast（对于不合格的颜色组合，它会返回通过检查 的色调或明暗度）；之后可通过布局读取结果中的 low_contrast 进行检查。

彩色幻灯片上的表格会因主题填充而呈现深色文字配深色背景： 对每个单元格调用 set_table_cell_fill（使用浅色填充和深色文本，或使用强调色 填充和白色文本），然后用 set_text_style（cellRow/cellColumn）重新设置样式。 标题页和摘要页优先使用统计卡片，而非数字网格；只有真正的表格数据才使用表格， 并将标题行填充为强调色，且行数控制在少量以内。

幻灯片与重复内容

• create_presentation 会以一张空白幻灯片开始（删除其 占位符，或用 set_shape_text 填充）；它无法指定目标文件夹，因此创建后 使用 google-drive google_drive_move_or_rename 移动它。
• 使用预定义版式调用 add_slide 时，会在同一次调用中填充标题/正文占位符 （这是最快的主题一致幻灯片创建方式）；使用 move_slide 重新排序。
• 重复版式（一种模板，N 个变体）：先完整构建第一张幻灯片，然后对每个变体， 在幻灯片 ID 上调用 duplicate_object（副本会紧接在原幻灯片之后），并使用 pageObjectIds 将 replace_text 限定在副本范围内；使用 {{TITLE}} 等不同的占位符， 可确保替换目标明确。
• set_shape_text 会替换整个形状或单元格的文本（单元格 = {rowIndex, columnIndex}）；set_text_style 会重新设置某个形状或单元格的全部文本样式，而非某个范围的样式。update_element_position 只会移动元素，不会调整大小： 应删除元素并按正确尺寸重新创建。
• 演讲者备注：调用 set_shape_text，将 pageObjectId 设为幻灯片的 notesPageId，并将 objectId 设为从 read_presentation 获取的 speakerNotesObjectId。
• 渲染整套幻灯片：使用 google-drive google_drive_export_file（pdf）。