google-slides

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Slides authoring

Google Slides 编写指南

Coordinates are POINTS from the slide's top-left; a standard slide is 720x405 (read_slide_layout reports the real size). Everything is addressed by objectId from

read_presentation

. Pass

requiredRevisionId

from the latest read or write so a concurrent edit fails the write instead of corrupting it.

坐标以幻灯片左上角为原点的 POINTS（磅）为单位；标准幻灯片为 720x405（

read_slide_layout

会报告实际尺寸）。所有元素都通过

read_presentation

返回的

objectId

来引用。请传递最新读取或写入操作获得的

requiredRevisionId

，这样并发编辑时写入会失败，而不会损坏幻灯片。

Building a new deck: compose, then look

构建新演示文稿：先编排，再查看

Write each slide as a layout, not as coordinates.

compose_slide

takes a tree (stacks, grids, cards, text, images) or an HTML/CSS subset and lays the whole slide out in one call: equal peer sizes, even gutters, vertical centering, and contrast pairs hold by construction, text can

fit: "shrink"

, and the reply carries every element's box plus lints on the plan. Per slide:

```
add_slide
```
layout BLANK (or the deck's first slide with
```
clear: true
```
), then
```
compose_slide
```
with the SAME
```
theme
```
every time (palette roles background/surface/primary/textSecondary and the font family). Colors in the tree are roles, not hexes, so one theme change restyles a deck.
Read the reply's
```
issues
```
.
```
text_overflow
```
means shorten,
```
fit: "shrink"
```
, or give the node more
```
size
```
; an
```
overlap
```
means two nodes share a box (usually a row that needs
```
gap
```
).
```
get_slide_thumbnail
```
(LARGE) once per slide and LOOK at it: crowding, dead corners, a title that reads as body text, an image fighting the palette. Fix by re-composing the slide (delete the old elements first, or compose onto a fresh BLANK slide and
```
delete_object
```
the old one).

Tree recipes (column root; the root box is the slide minus a 48 pt margin):

Title slide:

stack column justify:center

with a

display

text and an

h2

subtitle in

textSecondary

, both

align:center

KPI cards:
```
h1
```
, then a
```
stack row size:150 gap:24
```
of
```
card
```
s, each with a
```
caption
```
label (
```
textSecondary
```
) over a
```
kpi
```
value.

Text + image:

stack row gap:32

of a

body

text (

bullets:true

size:{flex:1}

) and an

image

(

size:{flex:1}

); the image aspect-fits.

Agenda: one
```
body
```
text with newline-separated items and
```
bullets:true
```
.

HTML form, same result:

<section style="background:#0B2A4A; padding:48pt; gap:24pt">

with

<h1>

<div style="display:flex; gap:24pt; height:150pt">

<article class="card"><span class="caption">…</span><span class="kpi">…</span></article>

<ul><li>

bullets,

<img style="flex:1">

. Only the documented tags and properties compile; anything else is refused by name, never dropped.

将每张幻灯片编写为布局，而不是坐标。

compose_slide

接受一个树（堆栈、网格、卡片、文本、图片）或 HTML/CSS 子集，并在一次调用中完成整张幻灯片的布局：同级元素等大、间距均匀、垂直居中、对比度配对由构造保证，文本可以使用

fit:"shrink"

，响应会返回每个元素的盒子（box）以及对布局的检查（lint）。每张幻灯片：

使用
```
add_slide
```
添加一个 BLANK 布局（或对演示文稿的第一张幻灯片使用
```
clear: true
```
），然后每次都用相同的
```
theme
```
调用
```
compose_slide
```
（调色板角色：background/surface/primary/textSecondary 以及字体族）。树中的颜色是角色（role），不是十六进制值，因此一次主题更改即可为整个演示文稿重新设置样式。
阅读响应中的
```
issues
```
。
```
text_overflow
```
表示需要缩短文本、使用
```
fit:"shrink"
```
，或给节点更大的
```
size
```
；
```
overlap
```
表示两个节点共用一个盒子（通常是需要
```
gap
```
的行）。
对每张幻灯片调用一次
```
get_slide_thumbnail
```
（LARGE）并查看：是否有拥挤、死角、标题看起来像正文、图片与配色冲突。通过重新编排幻灯片来修复（先删除旧元素，或先在一张新的 BLANK 幻灯片上编排，然后
```
delete_object
```
删除旧的）。

树形配方（以列作为根；根盒子是幻灯片除去 48 pt 边距后的区域）：

标题幻灯片：
```
stack column justify:center
```
，包含一个
```
display
```
文本和一个使用
```
textSecondary
```
颜色的
```
h2
```
副标题，两者都
```
align:center
```
。
KPI 卡片：
```
h1
```
，然后是一个包含
```
card
```
的
```
stack row size:150 gap:24
```
，每张卡片有一个
```
caption
```
标签（
```
textSecondary
```
）在
```
kpi
```
值上方。
文本+图片：
```
stack row gap:32
```
，包含一个
```
body
```
文本（
```
bullets:true
```
，
```
size:{flex:1}
```
）和一个
```
image
```
（
```
size:{flex:1}
```
）；图片按宽高比适配。
议程：一个
```
body
```
文本，包含换行分隔的项目并设置
```
bullets:true
```
。

HTML 形式，结果相同：

<section style="background:#0B2A4A; padding:48pt; gap:24pt">

包含

<h1>

、

<div style="display:flex; gap:24pt; height:150pt">

内的

<article class="card"><span class="caption">…</span><span class="kpi">…</span></article>

、

<ul><li>

项目符号、

<img style="flex:1">

。只有文档中描述的标签和属性会被编译；其他任何内容都会按名称被拒绝，而不会被静默丢弃。

Editing an existing deck: place, inspect, fix, look

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

For decks that already have content, or elements the tree does not model:

```
insert_grid
```
for any row, column, or grid of cards/text/images (one call, aligned, equal sizes);
```
insert_text_box
```
/
```
insert_shape
```
/
```
insert_image
```
for singletons.
```
read_slide_layout
```
: every element's box, z-order, text style, estimated wrapped height (
```
textFit.fits
```
), and
```
issues
```
. Fix every
```
error
```
and
```
warn
```
(
```
text_overflow
```
,
```
overlap
```
,
```
off_slide
```
,
```
low_contrast
```
with the fill actually behind the text named) and the
```
info
```
items when cheap (
```
near_miss_alignment
```
,
```
unequal_peers
```
,
```
tight_margin
```
,
```
empty_placeholder
```
).
```
get_slide_thumbnail
```
once the lints are clean, and look.

对于已有内容或树无法涵盖的元素：

对于任何行、列或卡片/文本/图片的网格，使用
```
insert_grid
```
（一次调用，对齐，等尺寸）；对于单个元素，使用
```
insert_text_box
```
/
```
insert_shape
```
/
```
insert_image
```
。
```
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
```
）。
检查（lint）通过后，调用
```
get_slide_thumbnail
```
并查看。

Grid conventions (when placing by hand)

网格约定（手动放置时）

Title at x 40, y 32, 640 wide, height 60-70 for one line of 28-34 pt (two lines need ~110); subtitle under it at 16-18 pt. Content region x 40, y 130, 640 x 235 (insert_grid's default). Footer at y 370, 12 pt. Keep 40 pt side margins unless an element is deliberately full-bleed. Process flows:

insert_grid

the step shapes (columns = steps), then

connect_shapes

between neighbors; connectors follow shapes when moved.

A 34 pt bold title wraps past ~32 characters in a 600 pt box and spills over whatever sits below (the API does not grow boxes).

textFit

in the layout read and

issues

in the compose reply predict this; long titles go to 24-28 pt,

fit: "shrink"

, or two lines with the subtitle pushed down.

标题：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

连接相邻形状；连接线会随形状移动。

34 pt 粗体标题在 600 pt 的盒子中超过约 32 个字符就会换行，并溢出到下方内容（API 不会自动扩展盒子）。布局读取中的

textFit

和编排回复中的

issues

可以预测这一点；长标题请使用 24-28 pt、

fit: "shrink"

，或分两行并将副标题下移。

Palette and contrast

调色板与对比度

Pick a palette FIRST and reuse it on every slide (as

compose_slide

theme.palette

): background, one card/surface color, one accent, and a secondary text color; on-colors derive automatically. When the user names a template or brand, take its colors; otherwise these pairs pass WCAG AA as-is:

Dark: background #0B2A4A, cards #1E4976, accent #4FC3F7, titles/text #FFFFFF, secondary #B8CCE0.
Light: background #FFFFFF, cards #F1F3F4, accent #0B57D0 (white text on it), text #202124, secondary #444746.

Text color never defaults sensibly on a colored fill: every text-bearing call picks its color against the fill BEHIND the text (the card's, not the slide's). No mid-gray on mid-anything; on white, secondary text is #444746 or darker (#5F6368 is borderline, lighter fails). For a template or brand palette, run

check_contrast

on every text/fill pair you intend to use before writing (it returns a passing tint or shade for each failing pair);

low_contrast

in the layout read is the check afterwards.

Tables on colored slides render dark-on-dark from theme fills:

set_table_cell_fill

every cell (light fill + dark text, or accent + white) and restyle with

set_text_style

(cellRow/cellColumn). Prefer stat cards over a grid of numbers on title and summary slides; a table only for genuinely tabular data, with the header row filled in the accent and kept to a handful of rows.

首先选择调色板，并在每张幻灯片上重复使用（作为

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）重新设置样式。在标题和摘要幻灯片上，优先使用统计卡片而不是数字网格；表格仅用于真正需要表格化的数据，标题行使用强调色填充，并保持少量行数。

Slides and repetition

幻灯片与重复

```
create_presentation
```
starts with one blank slide (delete its placeholders, or fill them with
```
set_shape_text
```
); it cannot target a folder, so move it after with google-drive
```
google_drive_move_or_rename
```
.
```
add_slide
```
with a predefined layout fills title/body placeholders in the same call (fastest theme-consistent slide);
```
move_slide
```
reorders.
Repeated layouts (one template, N variants): build the first slide fully, then per variant
```
duplicate_object
```
on the slide id (the copy lands right after) and
```
replace_text
```
scoped by
```
pageObjectIds
```
to the copy; distinct placeholders like {{TITLE}} keep the replaces unambiguous.
```
set_shape_text
```
REPLACES a shape's or cell's whole text (cell = {rowIndex, columnIndex});
```
set_text_style
```
restyles all of one shape or cell, not a range.
```
update_element_position
```
moves but does not resize: delete and re-create at the right size instead.
Speaker notes:
```
set_shape_text
```
with pageObjectId = the slide's notesPageId and objectId = speakerNotesObjectId from
```
read_presentation
```
.
Whole-deck render: google-drive
```
google_drive_export_file
```
(pdf).

```
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）。