# Google Slides reference / Google Slides 参考 **As a first step, before you build, rewrite or restyle any slide, in a new deck or an existing one, you must read the design rules below in full. Before you add or change a chart, also read `references/charts.md`.** After the rules come the Slides connector's tools and how to carry out the rules with them. **作为第一步，在新建、重写或重新设计任何幻灯片之前（无论演示文稿是新的还是既有的），你必须完整阅读下文的设计规则。在添加或修改图表之前，还须阅读 `references/charts.md`。** 规则之后是 Slides 连接器的工具，以及如何借助这些工具落实规则。 # Slide design / 幻灯片设计 When the user asks for something specific, such as a slide count, exact wording, a color or a layout, do that; these rules decide what the user left open. The rules for charts are in [charts.md](charts.md); the rules for the words on slides are under "Writing slide copy" below. 当用户提出具体要求时，例如幻灯片数量、确切措辞、颜色或布局，照做即可；这些规则只决定用户留白的部分。图表规则见 [charts.md](charts.md)；幻灯片文字的规则见下文"撰写幻灯片文案"（Writing slide copy）一节。 Your slides should be indistinguishable from a top strategy consultancy's deck, an investment bank's pitch book, or a front-page business story. 你制作的幻灯片应达到与顶级战略咨询公司的演示文稿、投资银行的推介材料或报纸头版商业报道难以区分的水准。 【评论】以顶级咨询与投行的交付物作为质量基准，是对模型输出风格的高标准设定，也隐含了幻灯片被当作正式商业文书的定位。 ## Deck structure / 演示文稿结构 - **One message per slide.** A deck goes theme by theme, message by message. Putting revenue next to retention on one slide, unless they are related, gives the reader two things to work out instead of one. **每张幻灯片只传递一个信息。**演示文稿按主题逐一推进、按信息逐条展开。除非营收与留存相关，否则把二者放在同一页上，会让读者要解决两个问题而不是一个。 - **The titles tell the story.** Someone reading only the slide titles should be able to follow the whole deck. **标题串起故事。**只读各页标题的人也应能跟上整份演示文稿的脉络。 - **A common structure is the pyramid:** the main message up front, an executive summary that previews the sections, the sections themselves, then a conclusion, usually with next steps that act on the findings. **常见结构是金字塔式：**开头是核心信息，随后是预览各部分的执行摘要，接着是各部分正文，最后是结论，通常附有基于发现的后续步骤。 - **Match the structure to the size of the deck.** A short deck might not need an introduction and a conclusion; a long deck might need dividers between topics. **结构要与文稿篇幅匹配。**短文稿可能不需要引言和结论；长文稿可能需要在主题之间插入分隔页。 - **Build toward what the deck is for:** a decision, consensus, a celebration, resolving a disagreement, or opening a discussion. **围绕文稿的目的来构建：**做出决策、达成共识、举办庆祝、化解分歧，或开启讨论。 - **Build for how it will be used.** A live deck gets narration and possibly discussion; a pre-read has to carry the whole narrative itself. An executive audience in a live meeting needs few words and highly visual slides. Detailed, word-heavy slides are sometimes right for subject-matter experts or for a deck read offline. Analytical reports lean on charts and tables, with the titles carrying most of the narrative. **按使用方式来构建。**现场演示的文稿配有讲解，还可能有讨论；预读材料则必须自行承载完整叙事。现场会议中的高管受众需要少文字、高视觉化的幻灯片。细节详尽、文字密集的幻灯片有时适合领域专家或供线下阅读的文稿。分析类报告依赖图表和表格，由标题承担大部分叙事。 - **Size a live deck to the talk:** about 1.5 to 2 minutes per slide, with time left for questions if there will be any. **现场文稿的篇幅与演讲时长匹配：**每页约 1.5 至 2 分钟，如有问答环节还要留出提问时间。 An example outline; the deck's own subject decides the titles: 下面是一个示例大纲；标题由文稿自身的主题决定： 1. Title slide: "Q3 Cost Review: Reducing Logistics Spend by 15%", with the presenter, date and audience when you know them. 1. 标题页："Q3 Cost Review: Reducing Logistics Spend by 15%"（第三季度成本回顾：将物流支出降低 15%），在已知时附上演示者、日期和受众。 2. Executive summary: logistics costs grew 22% year over year, driven by three controllable factors; fixing them saves $4.2M a year. Previews the deck and the recommendation. 2. 执行摘要：物流成本同比增长 22%，由三个可控因素驱动；解决它们每年可节省 $4.2M。预览整份文稿和建议。 3. "Logistics spend outpaced revenue growth 3:1 since Q1": spend against revenue, with the gap opening in Q2. 3. "Logistics spend outpaced revenue growth 3:1 since Q1"（自第一季度以来，物流支出增速达营收增速的 3 倍）：支出与营收对比，差距在第二季度拉开。 4. "Three drivers explain 80% of the increase: carrier rates, expedited shipping, and warehouse overtime": the increase broken down by driver. 4. "Three drivers explain 80% of the increase: carrier rates, expedited shipping, and warehouse overtime"（三个因素解释了 80% 的增长：承运商费率、加急运输和仓库加班）：按驱动因素分解的增长构成。 5. "Two carriers raised rates 18% while volume stayed flat": rate change by carrier against volume share. 5. "Two carriers raised rates 18% while volume stayed flat"（两家承运商提价 18%，而货量持平）：各承运商费率变化与货量占比对照。 6. "Expedited orders doubled, mostly from late order entry, not customer demand": the causes of expedited volume. 6. "Expedited orders doubled, mostly from late order entry, not customer demand"（加急订单翻倍，主因是订单录入迟滞而非客户需求）：加急货量的成因。 7. "Overtime is concentrated in two sites with outdated staffing models": overtime hours by site. 7. "Overtime is concentrated in two sites with outdated staffing models"（加班集中在人员编制模型过时的两个站点）：各站点加班时长。 8. "Three fixes, ranked by savings and effort": renegotiation, order cutoff enforcement and staffing changes compared. 8. "Three fixes, ranked by savings and effort"（三项整改，按节省额与实施难度排序）：对比重新谈判、严格执行订单截单时间与人员编制调整。 9. "Recommendation: pursue all three fixes, starting with carrier renegotiation for fastest payback": savings and payback timeline. 9. "Recommendation: pursue all three fixes, starting with carrier renegotiation for fastest payback"（建议：三项整改全部推进，从回报最快的承运商重新谈判开始）：节省额与回报时间线。 10. Next steps: owners, milestones, and the decisions needed from this audience by the end of the month. 10. 后续步骤：负责人、里程碑，以及需要在本月底前由该受众做出的决策。 ## Designing a slide / 设计一张幻灯片 Design each slide before you build it, in this order: the message, the evidence, the layout. The layout comes last because it depends on what the slide has to hold. 在构建每张幻灯片之前先做设计，顺序是：信息、论据、布局。布局放在最后，因为它取决于幻灯片要承载什么。 ### Message: the title / 信息：标题 The title carries the slide's message, and most slides need one. There are three conventions for slide titles: 标题承载幻灯片的信息，大多数幻灯片都需要标题。幻灯片标题有三种惯例： 1. **Story:** one sentence that tells the reader the main takeaway: "German revenue grew 12% in 2025, three times the US rate". Active voice, a specific subject, the number in it when there is one, at most about fifteen words and never more than two lines; on a 10-inch-wide slide, two lines at 32pt hold about twelve words. Not "German market overview", and not "We analyzed the German market". 1. **叙事式：**用一句话告诉读者核心结论："German revenue grew 12% in 2025, three times the US rate"（2025 年德国营收增长 12%，为美国增速的三倍）。主动语态，主语具体，有数字就写进去，最多约十五个词且绝不超过两行；在 10 英寸宽的幻灯片上，32pt 两行约容纳十二个词。不要写"German market overview"（德国市场概览），也不要写"We analyzed the German market"（我们分析了德国市场）。 2. **Label only:** the general theme of the slide: "German revenue in 2025". 2. **纯标签式：**幻灯片的总体主题："German revenue in 2025"（2025 年德国营收）。 3. **Label and story:** "German revenue" on the first line and "German revenue grew 12% in 2025, three times the US rate" on the second. This shows both the theme and the takeaway. 3. **标签加叙事式：**第一行写"German revenue"（德国营收），第二行写"German revenue grew 12% in 2025, three times the US rate"（2025 年德国营收增长 12%，为美国增速的三倍）。这样主题与结论同时呈现。 Write every title in the deck the same way. If the deck already has a convention, use it. Otherwise default to story titles on content slides. 整套文稿的标题写法保持统一。文稿已有惯例就沿用；否则内容页默认采用叙事式标题。 Structural slides (the title slide, agenda, executive summary, section dividers, next steps, appendix) take a label title whatever the deck's convention. They do not carry a single finding, so a story title reads as forced: "These are the four topics we will cover" is worse than "Agenda". The executive summary's takeaway goes in its body, not its title. 结构性页面（标题页、议程、执行摘要、章节分隔页、后续步骤、附录）无论文稿惯例如何都用标签式标题。它们不承载单一发现，叙事式标题会显得生硬："These are the four topics we will cover"（这是我们将讨论的四个主题）不如"Agenda"（议程）。执行摘要的结论放在正文里，而不是标题里。 ### Evidence / 论据 The content's only job is to make the reader believe the title. Before choosing a layout, decide what will do that: text, a graphic, an image, a table, a chart, footnotes, or a combination, and roughly how much of each. Most slides need one main element and a little supporting text: 内容的唯一职责是让读者相信标题。选择布局之前，先决定由什么来完成这件事：文字、图形、图片、表格、图表、脚注，或其组合，以及各自的大致比重。大多数幻灯片需要一个主元素加少量辅助文字： - If the title is a number or a comparison, the main element is a chart ([charts.md](charts.md) picks the type). 如果标题是一个数字或对比，主元素是图表（[charts.md](charts.md) 负责选择类型）。 - If it is a structure or a process, a graphic. 如果标题是结构或流程，主元素是图形。 - If it is a claim with several reasons, short text, or a row of icons with labels when the reasons are parallel. 如果标题是附有若干理由的论断，用简短文字；理由相互并列时，用一排带标签的图标。 ### Layout / 布局 Match the company's style and branding, as shown by the slide master, the finished slides already in the deck, and anything the user has said. Add new slides from the master's layouts so they inherit its fonts, sizes and positions. If no layout fits your design, start from the closest one, so the slide keeps the deck's background and fonts, and build from there. 遵循公司的风格与品牌，依据来自幻灯片母版、文稿中已有的成品页以及用户说过的要求。新幻灯片从母版版式添加，以继承其字体、字号和位置。没有合适版式时，从最接近的版式入手，让幻灯片保留文稿的背景与字体，再行构建。 With the message and the evidence decided, choose the layout that holds them. A text-heavy slide might suit a simple title-and-body layout; a highly visual slide might need no body text, only a graphic with the words built into it. Some common layouts: 信息与论据确定后，选择能容纳它们的布局。文字密集的幻灯片可能适合简单的"标题加正文"版式；高度视觉化的幻灯片可能不需要正文，只需一个把文字内置其中的图形。常见布局有： - **Big text.** One message and nothing else. Rare; right for a quote, or a big message or number that deserves its own page. **大字文本。**只有一个信息，别无其他。少见；适合一句引言，或值得独占一页的重要信息或大数字。 - **Title on top and content below, or title on one side and content on the other.** Good for an agenda, an executive summary, or a key chart that speaks for itself and needs no commentary. **标题在上、内容在下，或标题居一侧、内容居另一侧。**适合议程、执行摘要，或无需解说、自能说明问题的关键图表。 - **Title on top, a visual and commentary below.** The most common slide: a left/right split, with the visual on one side and the commentary on the other. A chart gets at least 60% of the width; another visual can take half or two-thirds. **标题在上，下方是视觉元素加解说。**最常见的版式：左右分栏，视觉元素在一侧，解说在另一侧。图表至少占宽度 60%；其他视觉元素可占一半或三分之二。 Other layouts are fine if they follow the deck's design standards. When the deck has layouts to choose from, use one with text placeholders for any slide that has text, so the text takes the master's fonts and sizes; keep the blank layout for slides that are entirely visual, such as a full-bleed image or a diagram built from shapes. Don't give three or more slides in a row the same layout unless they form a deliberate series, such as one slide per team member. 只要符合文稿的设计标准，其他布局亦可。文稿提供可选版式时，任何含文字的幻灯片都应使用带文本占位符的版式，让文字继承母版的字体和字号；完全视觉化的幻灯片（如满版图片或由形状构成的图示）才用空白版式。连续三页及以上不要用同一版式，除非它们构成有意设计的系列，例如每位团队成员一页。 ## Starting from the deck's design / 从文稿的既有设计出发 **A deck with its own template or theme.** Keep its design. New content uses the theme's colors exactly, and new slides use its layouts. If the user asks for a restyle, change the theme and the master rather than restyling slide by slide. A theme change does not reach text and shapes that carry their own fixed colors, which most real decks have, so replace those colors as well. **自带模板或主题的文稿。**保留其设计。新内容严格使用主题色，新幻灯片使用其版式。用户要求改换风格时，修改主题和母版，而不是逐页重设样式。主题变更不会波及自带固定颜色的文字和形状，而大多数实际文稿都有这类元素，因此这些颜色也要替换。 **A deck styled slide by slide on the default theme.** Someone built the deck by styling slides directly and never changed the master. The existing slides are the design system: don't create or change a master. Read a representative finished slide (background, fonts, sizes, colors, how shapes are styled) and make new slides match it, applying the styling on each slide the way the existing ones do, since the master has nothing to inherit. **在默认主题上逐页设置样式的文稿。**有人直接对幻灯片逐页设置样式构建了文稿，从未修改母版。既有幻灯片就是设计体系：不要创建或修改母版。研读一页有代表性的成品页（背景、字体、字号、颜色、形状的样式），让新幻灯片与之匹配，并像既有页面那样逐页应用样式，因为母版没有可供继承的内容。 **A new or blank deck.** Set the design up in the master before adding any slide: theme colors, a heading font and a body font, the background, the default text colors, and a bold title style. Text color is set in the master's text styles, not shape by shape. Let the slides inherit it, so the deck stays consistent and a later restyle is one edit. Anything that belongs on every slide, such as a background or a logo, goes on the master, never copied onto each slide. If the deck is for a company, match its brand; look up its brand guidelines if they are not obvious. Otherwise use what the user told you, and fill in the rest. Unless the palette you pick below says otherwise: **新建或空白文稿。**在添加任何幻灯片之前，先在母版中完成设计设定：主题色、标题字体和正文字体、背景、默认文字颜色，以及加粗的标题样式。文字颜色在母版的文本样式中设定，而不是逐个形状设置。让幻灯片继承这些设定，这样文稿保持一致，日后改换风格也只需一次编辑。凡是应出现在每一页上的元素，如背景或徽标，都放在母版上，绝不逐页复制。文稿是为某家公司制作时，与其品牌保持一致；品牌规范不明显时就去查证。否则使用用户告知的内容，其余自行补足。除非你在下面选择的配色方案另有说明： - an off-white background with no warm tint (such as #FAFAFA) and near-black text, rather than pure white and pure black; 不带暖色调的灰白背景（如 #FAFAFA）配近黑色文字，而不是纯白配纯黑； - one or two accent colors at the same brightness; 一到两个亮度一致的强调色； - a look that fits this deck: a quarterly review, a pitch and a workshop deck should not look the same, and neither should two decks you make in a row. 与这份文稿相称的外观：季度回顾、融资推介和工作坊文稿不应长得一样，你连续制作的两份文稿也不应如此。 Do not default to a dark-blue background. Pick a palette that matches the content: 不要默认使用深蓝背景。选择与内容匹配的配色方案： - **Corporate neutral:** white or light gray background, one saturated accent, generous white space. For reports and proposals. **企业中性风：**白色或浅灰背景，一个饱和强调色，留白充足。适用于报告和提案。 - **Warm editorial:** cream background with terracotta or olive accents. For case studies and narratives. **暖调编辑风：**奶油色背景，配陶土色或橄榄绿强调色。适用于案例研究和叙事类内容。 - **Bold startup:** near-white background with one high-contrast accent. For launches and pitches. **大胆创业风：**近白背景，配一个高对比强调色。适用于发布会和融资推介。 - **Academic muted:** paper-white background, steel blue and muted green, serif headings. For research and teaching. **学术淡雅风：**纸白背景，钢青色与灰绿色，衬线标题。适用于研究和教学。 - **Playful bright:** warm light background with several saturated accents. For events and creative work. **明快活泼风：**暖调浅色背景，配多个饱和强调色。适用于活动和创意作品。 A cream or beige background (such as #F5F5DC, #FAF0E6, #FAEBD7 or #FFF8E1) belongs only to the warm editorial look; never use one as a default. A dark background suits the title slide and section dividers. 奶油色或米色背景（如 #F5F5DC、#FAF0E6、#FAEBD7 或 #FFF8E1）只属于暖调编辑风；绝不将其作为默认。深色背景适合标题页和章节分隔页。 **Finished slides and rough slides.** Not every existing slide is a style reference. What makes a slide rough is unfinished formatting, not its words: text boxes left empty or added in the stock font and size rather than the deck's, a bare box standing in for a chart, fonts and colors that match nothing else in the deck. A title that is just "draft", "WIP", "TBD" or "placeholder", or a sticky note on the slide ("update numbers before Friday"), is a reason to look closer, not proof. Filler text or an unfilled placeholder on a designed template slide does not make it rough, and a title slide or divider that is meant to look different is not rough either. Take the deck's conventions from the finished slides: the ones styled deliberately, that agree with each other when there is more than one. If every slide is rough, there is no deck style to match: take fonts and colors from the master when the deck has its own rather than the default one, follow this guide for the rest, and tell the user so in one line. Rough slides are still slides to fill in or fix when asked; they are just not the style to copy. **成品页与粗糙页。**并非每一页既有幻灯片都可作为风格参考。一页幻灯片显得粗糙在于排版未完成，而不在于它的文字：留空或以默认字体字号（而非文稿字体）添加的文本框、用一个空框充当图表、与文稿其他部分毫不匹配的字体和颜色。标题只写着"draft"、"WIP"、"TBD"或"placeholder"，或页面上贴着便签（"周五前更新数字"），是值得细看的线索，而不是定论。设计好的模板页上的占位文字或未填写的占位符并不使它粗糙，本就应与众不同的标题页或分隔页也不算粗糙。从成品页中提炼文稿惯例：即那些经过刻意设计、且在多于一页时彼此一致的页面。如果每一页都粗糙，就没有可循的文稿风格：文稿拥有自己的母版（而非默认母版）时，从母版提取字体和颜色，其余遵循本指南，并用一句话告知用户。粗糙的幻灯片在被要求时仍是要填写或修复的对象；它们只是不宜模仿的风格。 ## Text / 文字 Keep slide text brief. If you have more than one sentence, use bullet points. 幻灯片文字要简短。超过一句话就使用项目符号列表。 - **Titles are bold**, in the heading font, and larger than any other text on the slide except a big number. A regular-weight title reads as body text, and the slide loses its hierarchy. **标题要加粗**，使用标题字体，且大于页面上除大数字外的任何其他文字。常规字重的标题会被当作正文，幻灯片随之失去层级。 - **Structure for readability.** Keep parallel structure (all fragments or all sentences). Bold the words a reader needs to get the message. Keep each bullet to two lines. **为可读性组织结构。**保持平行结构（要么全是短语，要么全是完整句）。对读者理解信息所需的关键词加粗。每条列表项不超过两行。 - **Be direct.** Cut filler ("in order to", "key", "very"). **直接表达。**删掉冗词（"in order to"、"key"、"very"）。 - **Use active, concrete language.** Specific nouns and plain verbs: "customers left", not "we experienced customer attrition". Name the actor in every sentence. **使用主动、具体的语言。**具体的名词和朴素的动词：写"customers left"（客户流失了），不写"we experienced customer attrition"（我们经历了客户流失）。每句话都点明行为主体。 - **Be consistent.** The title and the content must agree; if they don't, one of them is wrong. **保持一致。**标题与内容必须相符；若不相符，必有一方有误。 - **Don't describe visuals.** Bullets add what the visual cannot show. If everything in a bullet is visible in the chart, cut the bullet. **不要描述视觉元素。**列表项应补充视觉元素无法呈现的信息。某条列表项的内容在图表中全都可见时，删掉它。 - **Give data context.** Pair every standalone number with a comparison: a prior period, the plan, or a competitor. Round to the precision a decision needs ($4.2M, not $4,183,207), and use ratios or multiples ("doubled", "1 in 5") to make the size of a change clear. Keep formatting, units and abbreviations the same on every slide. **为数据提供背景。**每个孤立数字都配上对比对象：上一期、计划值或竞争对手。四舍五入到决策所需的精度（$4.2M，而不是 $4,183,207），并使用比率或倍数（"doubled"（翻倍）、"1 in 5"（每五个中有一个））来凸显变化幅度。格式、单位和缩写在每一页上保持统一。 - **Claims must be defensible.** Every assertion must trace back to a verifiable data point or a clear, logical derivation. If you cannot find a direct path to the evidence, leave the claim out. When the user asks for figures you don't have ("add our financials"), ask for them; never invent figures. **论断必须站得住脚。**每一项断言都必须能追溯到可验证的数据点或清晰、合乎逻辑的推导。找不到通往证据的直接路径时，就不要提出该论断。用户要求你没有的数据时（"加上我们的财务数据"），向其索要；绝不编造数字。 【评论】这是典型的防幻觉条款：宁可缺数据也不允许模型虚构数字，与要求向用户索取缺失数据的做法相配合。 When a slide needs a lot of text, break it up with callouts or a supporting visual. 一张幻灯片需要承载大量文字时，用标注框或辅助视觉元素将其拆分。 ## Graphics / 图形 A well-chosen graphic shows structure at a glance that a paragraph would take a while to describe: a diagram, flow chart, timeline, process map, org chart, funnel, pyramid, 2×2 matrix, Venn diagram, cycle, roadmap, before-and-after comparison, or icon-and-label layout. 一个恰当的图形能让人一眼看出结构，而用段落描述则要花不少工夫：示意图、流程图、时间线、流程映射、组织架构图、漏斗、金字塔、2×2 矩阵、维恩图、循环图、路线图、前后对比，或"图标加标签"版式。 - **Shape the graphic like the idea.** A sequence gets a flow or a timeline, a hierarchy a pyramid or an org chart, overlapping categories a Venn diagram, a tradeoff a 2×2, a recurring process a cycle. If the idea has no inherent structure, don't force it into one. **让图形的形态贴合想法。**先后顺序用流程图或时间线，层级关系用金字塔或组织架构图，类别交叠用维恩图，权衡取舍用 2×2 矩阵，循环往复的过程用循环图。想法本身没有内在结构时，不要强行套用。 - **One idea per graphic.** If a graphic needs a paragraph to explain, simplify it. Cut elements until the takeaway is visible in a few seconds; details move to supporting text or a follow-up slide. **每个图形只表达一个想法。**一个图形需要一段话来解释时，就简化它。删减元素，直到核心结论在几秒内可见；细节移入辅助文字或下一页幻灯片。 - **Label elements directly, not in a legend.** Put short labels (2–5 words) on or next to the elements themselves. Longer explanations live outside the graphic. **直接为元素加标签，不要用图例。**把简短标签（2–5 个词）放在元素上或旁边。更长的解释放在图形之外。 - **Give each color, shape and size one meaning,** the same everywhere it appears, within the graphic and across the deck. Use color to mark the element that matters, not to decorate; keep everything else neutral. **让每种颜色、形状和大小只承载一种含义**，无论出现在图形内还是整套文稿中都保持一致。用颜色标记重要的元素，而不是用于装饰；其余一切保持中性。 - **Flow left to right or top to bottom.** Arrows show a relationship (sequence, causation, dependency), never decoration, and all flow in one direction. **流向为从左到右或从上到下。**箭头表达关系（顺序、因果、依赖），绝不作装饰，且全部朝同一方向。 - **Size and space equal elements equally.** Equal-weight elements get equal sizes and even spacing, and alignment is exact, not approximate. **同权重元素等大等距。**权重相同的元素使用相同的尺寸和均匀的间距，对齐精确，不做近似处理。 ## Images / 图片 An image must carry information. A generic stock photo is worse than empty space. Use an image when it is the evidence: a product shot, a screenshot, a place, a person, a before and after. Otherwise leave it out. 图片必须承载信息。一张千篇一律的图库照片还不如留白。只有当图片本身就是论据时才使用：产品实拍、屏幕截图、地点、人物、前后对比。否则不要放图。 - Viewers look where a pictured person is looking, so a person in a photo should face the content, not the edge of the slide. 观众会顺着照片中人物的视线看去，因此照片中的人物应面向内容，而不是幻灯片边缘。 - A photograph can fill its frame and be cropped. A screenshot or a diagram is shown whole, at its own aspect ratio, with no text laid over it. 照片可以填满其画幅并被裁剪。屏幕截图或示意图必须完整展示，保持自身宽高比，且不得在其上叠加文字。 - Text on top of a photo sits on a card or a darkened band so it stays legible. 叠加在照片上的文字应置于卡片或压暗色带上，以保证清晰可读。 - An image with a transparent background needs a backdrop that contrasts with its content, so its edges read. 透明背景的图片需要与其内容形成对比的衬底，使轮廓清晰可辨。 - Never stretch or squash an image to fit a frame: crop it, or letterbox it on a neutral background. 绝不拉伸或压缩图片去适配画框：应裁剪，或在中性背景上以加边方式（letterbox）呈现。 ## Icons / 图标 A small icon beside each point gives the reader something to scan before they read, and it is the simplest way to fix a slide that would otherwise be a wall of text. Use icons when a slide has three to six parallel items (features, categories, steps, risks, teams) and nothing in the content calls for a chart or a diagram: a row of icons with labels, or a grid of icon cards, reads at a glance where four bullets do not. Icons also help a text-heavy slide whose text you cannot cut, by giving each block an anchor. 在每个要点旁放一个小图标，让读者在阅读之前先有一个可扫视的对象，这也是改造"满页文字"幻灯片最简单的办法。幻灯片有三到六个并列条目（功能、类别、步骤、风险、团队），且内容不需要图表或图示时，使用图标：一排带标签的图标或一组图标卡片可以一眼读完，四条列表项则做不到。对于文字无法删减的文字密集型幻灯片，图标也能通过为每个文字块提供锚点而发挥作用。 - One icon per point, and the icon means the point: a shield for security, a clock for timing, a chart for growth. An icon that needs its label to make sense is decoration; leave it out. 每个要点一个图标，且图标要表达该要点：安全用盾牌，计时用时钟，增长用图表。必须依赖标签才能看懂的图标只是装饰；不要使用。 - Every icon on a slide, and across the deck, is the same style (all filled or all outline), the same size (30–50pt beside text; larger only for a single hero icon), and aligned on one row or grid with even spacing, to the left of its label. 同一页乃至整个文稿中的所有图标风格一致（要么全部实心，要么全部描边）、大小一致（文字旁为 30–50pt；只有单独的主视觉图标才更大），并对齐于同一行或网格、间距均匀，位于标签左侧。 - Color icons in the deck's accent, or a neutral, with enough contrast against the background; not a different color per icon. An icon in a small filled circle of the accent color works well. 图标用文稿的强调色或中性色，与背景保持足够对比；不要每个图标一种颜色。放在强调色小实心圆中的图标效果很好。 - Put a short label (2–5 words) next to each icon; the icon does not replace the label. 每个图标旁放一个简短标签（2–5 个词）；图标不能替代标签。 - Take icons from an icon set, never emoji, which render differently on every platform. When no icon set is available, use a filled circle with one simple symbolic shape or a number on it, and keep the same rules. 图标取自图标库，绝不用 emoji——后者在各平台渲染效果不一。没有图标库时，使用实心圆内放一个简单象征性图形或数字的做法，并沿用同样的规则。 ## Tables / 表格 A table is right when the reader looks up specific values across a few dimensions, or compares a small set of items on several attributes. If one comparison is the point, that is a chart, not a table. Keep the styling light so the numbers read first. 读者需要在少数几个维度上查询具体数值，或在若干属性上比较少量条目时，表格是合适的。如果核心只是单一对比，那应该用图表而非表格。样式保持轻量，让数字优先进入视线。 - **Borders:** thin (1pt or hairline), in the deck's light border color (about #E0E0E0 on a white background), between rows only, with one border under the header row. No column borders. A full grid looks like a spreadsheet, not a slide. **边框：**细线（1pt 或发丝线），用文稿的浅色边框色（白底上约为 #E0E0E0），只用于行与行之间，表头行下方一条。不加列边框。完整网格看起来像电子表格，不像幻灯片。 - **Header row:** bold text, no fill. That is the whole treatment. A colored header bar is the default table style in most slide tools and reads as unstyled. **表头行：**文字加粗，无底色。全部处理仅此而已。彩色表头条是大多数幻灯片工具的默认表格样式，看起来像未经设计。 - **Row labels (first column):** bold and left-aligned. **行标签（第一列）：**加粗并左对齐。 - **Alignment:** text columns left, number columns right so the digits line up. Put the unit on every value ("$42M", "61%"; a plain count such as 355 needs none), not in the row or column header, the same rule as bar labels. One number format per column, or per row in a table of metrics by period. **对齐：**文字列左对齐，数字列右对齐以使数位对齐。单位写在每个数值上（"$42M"、"61%"；355 这类普通计数无需单位），而不是写在行或列表头中，与条形图标签的规则相同。每列一种数字格式；按时期罗列指标的表格则每行一种。 - **Highlighting:** the row or column that is the message gets a light tint of the deck's accent color; nothing else does. For a heat map, one hue from light to dark, never the red-yellow-green default. Bolding one cell is fine. **高亮：**承载信息的行或列用文稿强调色的浅色调；其余一概不高亮。热力图用单一色相由浅到深，绝不用默认的红黄绿。对单个单元格加粗即可。 - **Density:** at most about six columns and eight rows on a full slide; past that, split the table or move it to an appendix. A cell that needs three or more sentences, or more than about 40 words, is too dense: shorten it to one sentence, move the detail to a footnote or a text box, or split the table. **密度：**整页幻灯片上至多约六列八行；超过就拆分表格或移入附录。一个单元格若需要三句以上或约 40 个词以上，就过于密集：压缩成一句话，把细节移到脚注或文本框，或拆分表格。 - **Size:** text in a table you create is at least 14pt; in an existing dense template, keep the template's sizes. Give rows generous height, about 28–32pt for a one-line row and 48–56pt for a two-line row, and no zebra striping. Check that the whole table fits above the bottom margin before you build it; if it doesn't, split it across slides. **字号：**你创建的表格文字不小于 14pt；在既有的密集模板中，沿用模板字号。行高要宽裕，单行约 28–32pt，双行约 48–56pt，不加斑马纹。构建前检查整张表格是否位于下边距之上；放不下就拆到多页。 - Build it as a real table, never out of text boxes. 用真正的表格来构建，绝不用文本框拼凑。 People read tables and charts differently. A table is read across the rows, then down, so it suits an audience where each person looks up their own row, such as regional sales where each reader finds their region. In a live presentation a table hides the point in detail. A full table in the appendix serves pre-reads and questions. Charts make a point faster and suit executive audiences. Use charts for the message and tables for reference. 人们阅读表格和图表的方式不同。表格是横着按行读、再纵向看的，适合每个人查找自己所在行的受众，例如区域销售场景中每位读者寻找自己的区域。现场演示中，表格会把要点埋进细节里。附录中的完整表格服务于预读和答疑。图表更快地传达观点，适合高管受众。传达信息用图表，供人查阅用表格。 ## Footnotes and sources / 脚注与来源 Footnotes do two jobs. 脚注承担两项职责。 The first is citing sources. If a number came from external research or an internal data set, put a superscript number immediately after the claim ("…grew 12%¹") and a footnote at the bottom of the slide starting with the same number, specific enough that the reader can find the original. Include the publisher and the date, because a market-size figure from 2021 and one from 2025 are different claims. Put hyperlinks behind the reference text rather than pasting raw URLs. Numbering restarts on each slide; if the deck has a sources appendix, number continuously across slides instead. 第一是标注来源。某个数字来自外部研究或内部数据集时，在论断后紧跟一个上标数字（"…grew 12%¹"），并在幻灯片底部放一条以相同数字开头的脚注，具体到读者能找到原始出处。注明发布方和日期，因为 2021 年的市场规模数字与 2025 年的是不同的论断。超链接放在引用文字背后，不要粘贴裸 URL。每页重新编号；文稿设有来源附录时，则改为全稿连续编号。 The second is methodology and caveats: detail the main message doesn't need but that matters if someone challenges the analysis, such as sample sizes, exclusions, exchange rates, or how a term like "active user" is defined. Put methodology and caveats first, then the provenance, starting "Source:". 第二是方法与注意事项：即主信息不需要、但一旦有人质疑分析时就重要的细节，例如样本量、剔除项、汇率，或"active user"（活跃用户）这类术语的定义。先写方法与注意事项，再写出处，以"Source:"开头。 Keep the citation format the same across the deck. Footnotes sit at the bottom of the slide at 10–12pt in a muted color. If everything on the slide came from one report, a single "Source: [report, year]" line replaces per-item footnotes. 引用格式在整个文稿中保持一致。脚注位于幻灯片底部，10–12pt，用柔和的颜色。整页内容都来自同一份报告时，用一行"Source: [报告名, 年份]"替代逐项脚注。 Cite only sources you actually have, whether the user gave them to you or you read them yourself. Do not add a "Prepared by" line, a confidentiality notice, or a date outside the title slide unless the user asked for it. A source you did not have is a fabricated citation, and a chart of the user's own numbers needs none. 只引用你实际掌握的来源，无论是用户提供的还是你亲自查阅的。除非用户要求，不要添加"Prepared by"（编制人）行、保密声明，或标题页之外的日期。你没有掌握的来源就是伪造引用；使用用户自身数字的图表则无需引用。 【评论】该条款把"引用未掌握的来源"明确定性为伪造引用，与"绝不编造数字"共同构成对数据可信度的约束，也是对模型编造出处倾向的针对性防范。 ## Size, spacing and placement / 尺寸、间距与位置 **Visual hierarchy and size.** The reader's eye should land on the title first, then the main visual or the bold text, then the detail. Size and weight control that order. Slides are read from the back of a room, so sizes that look right on a web page are too small here. On a standard 16:9 slide: **视觉层级与字号。**读者的视线应先落在标题上，再落到主视觉或加粗文字上，最后是细节。字号和字重控制这一顺序。幻灯片是在房间后排观看的，因此在网页上合适的字号在这里都偏小。标准 16:9 幻灯片上： | Element | Size | |---|---| | Slide title | 32–40pt bold, at least about 1.75× the body | | Section header | 24–28pt | | Body text | 16–18pt | | Captions | 14pt | | Footnotes and source lines | 10–12pt, muted | | 元素 | 字号 | |---|---| | 幻灯片标题 | 32–40pt 加粗，至少约为正文的 1.75 倍 | | 章节标题 | 24–28pt | | 正文文字 | 16–18pt | | 图注说明 | 14pt | | 脚注与来源行 | 10–12pt，柔和色 | Footnotes, source lines, the second line of a chart label, a chart's year row (11pt) and chart callouts (11–12pt) are the only text you add below 14pt, with one exception: a template whose own body text is smaller, which is common in banking and consulting decks. Match the template, since consistency with it matters more than the floor, but don't go below 10pt. Set sizes explicitly instead of leaving them to defaults. 脚注、来源行、图表标签的第二行、图表年份行（11pt）和图表标注（11–12pt）是你仅可使用小于 14pt 文字的情形，唯一例外是正文本身更小的模板——这在银行和咨询文稿中很常见。与模板保持一致，因为与模板一致比字号下限更重要，但不低于 10pt。显式设定字号，不要依赖默认值。 **Fitting text.** If the content doesn't fit at these sizes, there is too much content for one slide. Don't shrink text you wrote to make it fit: resize the container, cut words, or split the slide. Text the user wrote keeps its wording; it may go modestly below its original size, and if it ends up under 10pt, tell the user. Never leave text overflowing its box or cut off. **文字适配。**内容在这些字号下放不下，说明单页内容过多。不要缩小你写的文字来硬塞：调整容器大小、删减文字或拆分幻灯片。用户写的文字保留原措辞；字号可适度低于原值，若最终低于 10pt，告知用户。绝不留下溢出文本框或被裁切的文字。 **Use the slide.** Keep a margin of about half an inch on every side. On a slide you lay out, fill most of that area (about 70% or more of it), use most of the width, and reach toward the bottom margin rather than clustering in the top half. Open space under a short list is fine; a slide that is all margin is not. When you edit an existing slide, the user's layout is intentional; don't rearrange it to fill space. **善用版面。**四周保留约半英寸的边距。在你排版的幻灯片上，填满该区域的大部分（约 70% 以上），用足宽度，内容向下边距延伸，而不是挤在上半部分。短列表下方留白无妨；整页都是边距的幻灯片不行。编辑既有幻灯片时，用户的布局是有意为之；不要为填满空间而重排。 **Spacing.** Leave 0.3–0.5 inches between content blocks, and use the same gap throughout the deck. **间距。**内容块之间留 0.3–0.5 英寸，整个文稿使用相同的间距。 **The title band.** Measure where the title ends before placing content under it, since the title's height varies by template, and start the content at least 10pt below it. **标题带。**在标题下方放置内容前，先测量标题结束的位置，因为标题高度随模板而异，内容至少从其下方 10pt 处开始。 **Insets.** Text on a shape or a card is inset 10–15pt from the shape's edges. Text touching the edge of its container is the most common small layout defect. **内边距。**形状或卡片上的文字距形状边缘内缩 10–15pt。文字贴住容器边缘是最常见的小型排版缺陷。 **Alignment.** Align body text left rather than centering it, so the slide has a clean edge. Title alignment follows the layout: centered on the title slide and section headers, left-aligned on content slides. A template's own title alignment always wins. **对齐。**正文左对齐而非居中，使幻灯片边缘整洁。标题对齐随版式而定：标题页和章节页居中，内容页左对齐。模板自身的标题对齐方式始终优先。 ## Clutter, emphasis and variety / 克制、强调与变化 **Clutter.** Every element on a slide costs the audience attention. Leave off anything that does not add more than it costs, and do not fill white space for its own sake. **杂乱。**幻灯片上的每个元素都在消耗观众的注意力。凡是收益抵不过成本的一律去掉，也不要为填白而填白。 **Highlighting when a slide has to be dense.** Sometimes a slide or a chart has to be complicated. You can still get the message across by directing attention. If something needs to stand out and no legend has already assigned the colors, use color for it. Contrast also shows a shift, such as shading where actuals turn into projections. You can circle related elements, or put a callout on the one item with a non-obvious takeaway; draw it as a plain box and line, because the stock callout shapes look bad (a callout on a chart follows Callouts in `references/charts.md` instead, with no box). On wordy slides, bold the words someone glancing at the slide needs; they can read the full sentences if they want to. **幻灯片不得不密集时的强调。**有时幻灯片或图表不得不复杂。你仍可以通过引导注意力来传达信息。某处需要突出且图例尚未分配颜色时，就用颜色来实现。对比也能呈现转变，例如在实际值转为预测值处加底纹。可以圈出相关元素，或对唯一一个结论不直观的条目加标注；把它画成朴素的框加引线，因为自带的标注形状观感不佳（图表上的标注则遵循 `references/charts.md` 中"标注"（Callouts）的规则，不加框）。文字较多的页面上，对匆匆一瞥的读者所需的词加粗；想细读的人自会读完整句子。 **Variety.** The default failure is a deck where every slide is a title and a block of bullets. Nobody in the room reads a paragraph off a screen, and twelve slides with the same shape blur together. Bullets should be the minority. If more than about a third of the deck is coming out as bullet slides, some of those slides contain a number or a comparison that should be a chart, and some are two slides squeezed into one. A slide holds one message and, if it is a bullet slide, a few short lines, usually three or four. A slide that needs a paragraph is a pre-read page, not a slide: split it, or move the detail to the appendix. Vary the rhythm on purpose: a big number after two charts, a dark divider between sections, an image slide to open a section. Use different kinds of slides, and build each kind the same way every time. **变化。**最常见的失败是整份文稿每一页都是标题加一组列表。现场没有人会逐段读屏幕上的文字，而十二页同构的幻灯片会混成一片。列表页应当是少数。文稿中超过约三分之一的页面是列表页时，其中一些页面含有本应做成图表的数字或对比，另一些则是两页内容挤成了一页。一张幻灯片承载一个信息；如果是列表页，则只有几行短句，通常三到四行。需要一整段文字的页面是预读材料，不是幻灯片：拆分它，或把细节移入附录。有意变换节奏：两张图表后接一页大数字，章节之间放深色分隔页，用图片页开启新章节。使用不同种类的页面，且每一类的构建方式保持一致。 ## Writing slide copy / 撰写幻灯片文案 These rules cover the words you put on slides: titles, bullets, labels, callouts and footnotes. 这些规则约束你放在幻灯片上的文字：标题、列表项、标签、标注和脚注。 Slide copy should read as though a person wrote it. When readers think something was written by AI, they judge it as sloppy and stop trusting it, whatever the content. They make that judgment from a set of common indicators, listed below, so take extra care to keep them out of your writing. 幻灯片文案应读起来像出自真人之手。读者一旦认为某段文字是 AI 写的，无论内容如何，都会判定它草率并不再信任。他们依据一组常见特征做出这种判断，下文逐一列出，因此要格外注意不让它们出现在你的文字里。 【评论】该段及后续条目是对 AI 生成文本典型特征的系统性规避清单，属于面向"去机器感"的风格防御设计，也反映了读者信任与文本来源感知之间的关系。 - Say what is true without first denying something else. "Revenue grew 12%, three times the US rate," not "This isn't a growth story, it's a market-share story." Do not open a title or bullet with "Here's the thing" or "The real story is". A title can be a question when the slide is there to raise it; when the slide answers it, the title is the answer. 直接陈述事实，不要先否认别的说法。写"Revenue grew 12%, three times the US rate"（营收增长 12%，为美国增速的三倍），不要写"This isn't a growth story, it's a market-share story"（这不是增长故事，而是市场份额故事）。标题或列表项不要以"Here's the thing"（问题在于）或"The real story is"（真正的情况是）开头。幻灯片旨在提出问题时，标题可以是问句；幻灯片回答问题时，标题就是答案。 - Match the number of bullets, examples, and adjectives to the content, not to a default of three. Two drivers get two bullets; five get five or a table. A list of exactly three ("fast, reliable, and scalable") usually means the third item was added for rhythm, not because there were three things to say, and readers read it as filler. 列表项、例子和形容词的数量与内容匹配，而不是默认凑成三个。两个驱动因素就写两条；五个就写五条或改用表格。恰好三条的列表（"fast, reliable, and scalable"）通常意味着第三条是为节奏感而加的，并非真有第三点可说，读者会把它视为凑数。 - Do not use a metaphor where a literal word will do. If a plain description exists ("the same construction," "the same pattern," "slowed," "fell"), use it. Metaphors are for when the literal version would be longer or less precise, which is rare in analytical writing. Test: if the metaphor can be replaced by a plain word without losing meaning, replace it. A metaphor makes the reader translate it back into the plain claim and carries meaning you did not choose. The ones that appear most are "north star", "move the needle", "double-click" (meaning look closer), "unpack", "journey", and "landscape" (meaning a market). Common ones in business writing: "moat", "headwind", "drag" (meaning a cost on results), "safety net", "clears the bar", and "land" meaning finish or total ("lands $4.4k under budget"). Examples: 能用平实字眼时就不要用比喻。存在直白表述（"the same construction"（同样的构造）、"the same pattern"（同样的模式）、"slowed"（放缓）、"fell"（下滑））时，就用它。比喻只用于直白版本会更冗长或更不精确的场合，而这在分析性写作中很少见。检验方法：比喻换成平实字眼而不损失含义，就换掉。比喻迫使读者把它翻译回平实的论断，还夹带你未曾选择的含义。最常出现的有"north star"（北极星）、"move the needle"（推动指标）、"double-click"（意为深入查看）、"unpack"（拆解）、"journey"（历程）和"landscape"（意为市场）。商务写作中常见的还有："moat"（护城河）、"headwind"（逆风）、"drag"（意为拖累业绩的成本）、"safety net"（安全网）、"clears the bar"（达到标准），以及表示完成或合计的"land"（如"lands $4.4k under budget"，即最终低于预算 4400 美元）。例如： - Bad: "The ones it has are the same species." Good: "The ones it has follow the same pattern." 差："The ones it has are the same species."（它拥有的那些属于同一物种。）好："The ones it has follow the same pattern."（它拥有的那些呈现同样的模式。） - Bad: "A coordinated digestion pause would be visible immediately." Good: "If several large customers cut capex in the same quarter, it would show up in the next guide." 差："A coordinated digestion pause would be visible immediately."（多家同步消化库存的停顿会立刻显现。）好："If several large customers cut capex in the same quarter, it would show up in the next guide."（如果多家大客户在同一季度削减资本开支，下一份业绩指引中就会体现。） - Bad: "Architecture transitions compressed margin on the way in and expanded it on the way out." Good: "Gross margin fell during the Hopper-to-Blackwell ramp and recovered once Blackwell shipped at volume." 差："Architecture transitions compressed margin on the way in and expanded it on the way out."（架构转型在进入时压缩利润率，在退出时扩大利润率。）好："Gross margin fell during the Hopper-to-Blackwell ramp and recovered once Blackwell shipped at volume."（毛利率在 Hopper 向 Blackwell 爬坡期间下滑，并在 Blackwell 规模出货后回升。） - Bad: "The lever that unlocks growth." Good: "The pricing change is what makes the target reachable." 差："The lever that unlocks growth."（解锁增长的杠杆。）好："The pricing change is what makes the target reachable."（正是定价调整使目标变得可达。） - Cut words that claim importance without giving evidence: "genuinely", "truly", "actually", "clearly", "significantly", "robust", "leverage", "delve", "actionable insights", "learnings". Where one of them stood in for a fact, put the fact there ("margins fell 4 points", not "margins fell significantly"); otherwise delete it. 删掉只宣称重要却拿不出证据的词："genuinely"、"truly"、"actually"、"clearly"、"significantly"、"robust"、"leverage"、"delve"、"actionable insights"、"learnings"。这类词顶替了某个事实时，就用事实替换（写"margins fell 4 points"（利润率下降 4 个百分点），不写"margins fell significantly"（利润率显著下降））；否则直接删除。 - Use full stops and commas, and a colon before a list. No emoji on slides. 使用句号和逗号，列表前用冒号。幻灯片上不用 emoji。 - Use em dashes sparingly: at most one in a paragraph, and none in a heading, a title, or between a bold label and the text after it. Several em dashes in one paragraph is one of the first things readers use to spot machine writing. In place of one, use a comma, a colon, parentheses, or a new sentence, not an en dash or a spaced hyphen. 慎用破折号：每段至多一个，标题、页题或加粗标签与其后文字之间不用。同一段出现多个破折号是读者识别机器写作的首要线索之一。需要替代时，用逗号、冒号、括号或另起一句，不要用短破折号或带空格的连字符。 - On content slides, write headings as findings (see "Message: the title" above), not as a description of your process: "Europe missed plan by $1.9M", not "What I changed" or "The hard part". Structural slides (agenda, executive summary, next steps, appendix) keep a plain label. 内容页上的标题写成结论（见上文"信息：标题"一节），而不是对你工作过程的描述：写"Europe missed plan by $1.9M"（欧洲落后计划 $1.9M），不写"What I changed"（我改了什么）或"The hard part"（难点所在）。结构性页面（议程、执行摘要、后续步骤、附录）保留朴素标签。 - Keep the conversation out of the deck. When the user asks for a shorter or more formal version, make it shorter or more formal; do not title it "Executive Summary (Condensed)" or open with "Updated per your feedback" or "this streamlined deck focuses on". The audience did not see the request, so those lines mean nothing to them. Say what changed in your reply, not in the deck. 不要把对话痕迹带进文稿。用户要求更精简或更正式的版本时，把它改得更精简或更正式即可；不要把标题写成"Executive Summary (Condensed)"（执行摘要（精简版）），也不要以"Updated per your feedback"（已按反馈更新）或"this streamlined deck focuses on"（本精简版文稿聚焦于）开头。受众并没有看到那些请求，这些话对他们毫无意义。改动说明写进你的回复，而不是写进文稿。 - Write in the language variety the deck already uses (US or UK English, for example), or the user's when the deck has no text yet; never mix varieties in one deck. 使用文稿已有的语言变体（例如美式或英式英语）；文稿尚无文字时用用户的变体；绝不在同一文稿中混用变体。 ## Common mistakes / 常见错误 - **Accent lines under titles.** These are a hallmark of AI-generated slides; use white space or a background color instead. **标题下的强调线。**这是 AI 生成幻灯片的标志；改用留白或背景色。 - **Decorative color bars or accent stripes:** header or footer bars across the slide, vertical stripes down one edge, thin stripes along one edge of a card, single-side borders on rectangles. They read as filler. To set a card apart, use a light background tint, a soft shadow, or an icon. **装饰性色条或饰条：**横贯页面的页眉或页脚条、沿一侧边缘的竖条纹、卡片边缘的细条纹、矩形的单侧边框。它们看起来像凑数。要区分卡片，用浅色底、柔和阴影或图标。 - **Low contrast.** Icons and text need strong contrast against their background: no light text on a light background or dark text on a dark one. **低对比。**图标和文字须与背景形成强对比：浅色背景上不放浅色文字，深色背景上不放深色文字。 - **Styling one slide and leaving the rest plain.** Apply the design to every slide, or keep every slide simple. **只美化一页而其余保持素净。**要么把设计应用到每一页，要么让每一页都保持简洁。 # Slides connector / Slides 连接器 This part covers the Slides connector: `read_presentation`, `read_slide_page`, `read_slide_page_thumbnail`, and `update_presentation`. Most of the behavior here was tested against Google's Slides API; the rest was seen through the connector, and a few rules have not been checked yet. 本部分介绍 Slides 连接器：`read_presentation`、`read_slide_page`、`read_slide_page_thumbnail` 和 `update_presentation`。此处所述行为大多已针对 Google 的 Slides API 做过测试；其余是通过连接器观察到的，还有少数规则尚未核验。 ## Applying the design rules / 应用设计规则 The design rules are above. What follows is specific to building with `update_presentation`. 设计规则见上文。以下是使用 `update_presentation` 进行构建的专属说明。 - **Building a new deck.** When you build a new deck with `update_presentation`, use two or three calls, not one call per slide. In the first call, fill the title slide's `i0` and `i1` placeholders (`insertText`, appended to `build`'s output) and add the first content slide with `build`, so the user has something to look at early; add the remaining slides in one or two more calls. Each call holds everything for its slides in one batch. Read the deck before every call, the first included, and run `build` with that read's `revisionId`, as "Read before you edit, and guard the write" in SKILL.md says; the read that checks one call's slides can supply the next call's `revisionId`. **构建新文稿。**用 `update_presentation` 构建新文稿时，使用两到三次调用，而不是每页一次调用。第一次调用中，填写标题页的 `i0` 和 `i1` 占位符（`insertText`，追加在 `build` 的输出之后），并用 `build` 添加第一张内容页，让用户尽早有内容可看；其余幻灯片在一到两次后续调用中添加。每次调用把其幻灯片所需的全部内容放进一个批次。每次调用前都先读取文稿（包括第一次），并用该次读取的 `revisionId` 运行 `build`，正如 SKILL.md 中"先读后改，守卫写入"（Read before you edit, and guard the write）所说；检查上一次调用幻灯片的那次读取可以为下一次调用提供 `revisionId`。 - **Titles on the default page.** The type sizes above apply on the default 10 in wide page too, where a title line holds fewer words than on a wider slide. By `build`'s estimate, a bold 32 pt line in a 9 in wide box holds about 38 characters, so two lines hold about 75 characters, roughly twelve words. A two-line title needs a box about 1.3 in tall at 32 pt; if it needs more than two lines, cut words rather than shrink the font. `build` warns when a title needs more lines than its box holds. **默认页面上的标题。**上述字号同样适用于默认的 10 英寸宽页面，在这里一行标题容纳的词比更宽的幻灯片少。按 `build` 的估算，9 英寸宽文本框中一行 32pt 加粗文字约容纳 38 个字符，两行约 75 个字符，约合十二个词。32pt 的两行标题需要约 1.3 英寸高的文本框；超过两行时，删减文字而不是缩小字体。标题所需行数超过文本框容量时，`build` 会给出警告。 - **Layouts.** `build` creates each new slide on the predefined layout the spec names (`BLANK` when it names none) and draws its own text boxes, without filling the layout's placeholders. For a slide with a title and text in a deck that has layouts, create the slide with the placeholder recipe in Edit recipes, so the title and body take the master's style, then add tables, cards and shapes with `build` and `"existing": true`. Use `build`'s `BLANK` slides for slides that are entirely visual, as the layout rules above say. **版式。**`build` 在规格指定的预定义版式上创建每张新幻灯片（未指定时用 `BLANK`），并自行绘制文本框，不填充版式的占位符。在有版式的文稿中创建带标题和正文的幻灯片时，先用"编辑配方"（Edit recipes）中的占位符配方创建幻灯片，使标题和正文继承母版样式，再用 `build` 加 `"existing": true` 添加表格、卡片和形状。完全视觉化的幻灯片按上文版式规则使用 `build` 的 `BLANK` 页面。 - **Masters.** This reference has no tested recipe for changing a deck's master or theme, so skip the master steps in "Starting from the deck's design". On a new deck, give the elements you add the same fonts and colors on every slide, and put a background or logo on each slide that needs it. For a restyle, change each slide directly and tell the user the master is unchanged. **母版。**本参考没有经过测试的修改母版或主题的方法，因此跳过"从文稿的既有设计出发"中涉及母版的步骤。在新文稿上，让你添加的元素在每一页使用相同的字体和颜色，并在需要的每页放置背景或徽标。改换风格时直接逐页修改，并告知用户母版未变。 - **Warnings.** `build` warns about text under 14 pt unless it is a footer line: a box at most 0.5 in tall that ends within 0.8 in of the bottom of the slide. The design rules allow some other small text: the second line of a chart label, a chart's year row and callouts, a source line that isn't a footer line, and text matched to a template's smaller size. Those warnings can stay; fix every other warning. **警告。**`build` 会对小于 14pt 的文字发出警告，除非它是页脚行：高度至多 0.5 英寸、且末端距幻灯片底部不足 0.8 英寸的文本框。设计规则还允许其他一些小字：图表标签的第二行、图表的年份行和标注、不属于页脚行的来源行，以及与模板较小字号保持一致的文字。这些警告可以保留；其余警告一律修复。 - **Fonts.** Use Google fonts, such as Arial, Roboto, Lato, Montserrat, or Merriweather. **字体。**使用 Google 字体，例如 Arial、Roboto、Lato、Montserrat 或 Merriweather。 - **Tables.** `"header": true` bolds the header row. Leave `header_fill` and `header_color` unset, because the design rules give the header row bold text and nothing else, and set `"col_align"` to `"END"` for number columns. Bold the first column with `updateTextStyle` and `cellLocation` (Tables in Edit recipes), appended after `build`'s requests, since `build` sets every cell outside the header row to not bold. This reference has no tested way to set the row-only borders the design rules ask for: `build` sets no borders, and no border request has been tested through the connector, so a new table keeps the theme's default borders. **表格。**`"header": true` 会加粗表头行。`header_fill` 和 `header_color` 保持不设，因为设计规则对表头行只有加粗文字一项要求；数字列把 `"col_align"` 设为 `"END"`。用 `updateTextStyle` 加 `cellLocation`（"编辑配方"中的"表格"部分）加粗第一列，追加在 `build` 的请求之后，因为 `build` 会把表头行之外的所有单元格设为不加粗。本参考没有经过测试的方法来设置设计规则所要求的仅行边框：`build` 不设边框，连接器上也没有测试过任何边框请求，因此新表格沿用主题默认边框。 - **Charts.** A linked Sheets chart takes its look from the chart in the Sheet, so build it there to the standard `references/charts.md` picks: the deck's chart style when its charts share one, otherwise the house standard. Under the house standard, leave the chart's title off and put its label in a text box above it on the slide. This reference has no tested way to label only chosen points in a Sheets chart, or to draw line-end names, a year row, callouts or growth arrows there, so put those on the slide as text boxes and shapes, and check their positions on the rendered slide. **图表。**关联的 Sheets 图表外观取决于表格文件中的图表本身，因此在那里按 `references/charts.md` 选定的标准构建：文稿图表有统一风格时用文稿风格，否则用内部通用标准。按内部通用标准，不设图表标题，把标签放在幻灯片上图表上方的文本框中。本参考没有经过测试的方法在 Sheets 图表中只标注选定的点，或在其中绘制线端名称、年份行、标注或增长箭头，因此把这些作为文本框和形状放在幻灯片上，并在渲染后的页面上核对位置。 ## Create / 创建 Choose a route based on the deck. 根据文稿情况选择路线。 - **A designed deck:** load the `pptx` skill, build a .pptx with it, and check it with that skill's QA steps. Then upload it with Drive `create_file` and let Drive convert it. The file's whole content goes inside the tool call, so the upload is slow and can fail for a large deck. You get the `pptx` skill's design tools and QA. Conversion can change fonts and spacing, so run the QA steps below on the result. **需要设计的文稿：**加载 `pptx` 技能，用它构建 .pptx，并按该技能的 QA 步骤检查。然后用 Drive 的 `create_file` 上传，让 Drive 完成转换。文件的全部内容都放在工具调用里，因此上传较慢，大文稿可能失败。这样可以获得 `pptx` 技能的设计工具和 QA。转换可能改变字体和间距，因此对转换结果运行下文的 QA 步骤。 - **A few slides, or slides added to an existing deck:** create a blank presentation with Drive `create_file` and `contentMimeType: "application/vnd.google-apps.presentation"` (or open the existing deck), then build with `update_presentation`, using `slides_helper.py build` below. A new deck starts with one title slide whose placeholders are `i0` (title) and `i1` (subtitle). Fill them, or delete the slide with `deleteObject`. **少量幻灯片，或向既有文稿添加页面：**用 Drive 的 `create_file` 加 `contentMimeType: "application/vnd.google-apps.presentation"` 创建空白演示文稿（或打开既有文稿），然后用 `update_presentation` 构建，借助下文的 `slides_helper.py build`。新文稿初始有一张标题页，其占位符为 `i0`（标题）和 `i1`（副标题）。填写它们，或用 `deleteObject` 删除该页。 ## How a slide is addressed / 幻灯片的寻址方式 - **Units are EMU:** 914400 per inch, 12700 per point. The default 16:9 page is 9144000 x 5143500 EMU (10 x 5.625 in). Read `pageSize` before placing anything; some decks are 4:3 or custom. **单位是 EMU：**每英寸 914400，每磅（pt）12700。默认 16:9 页面为 9144000 x 5143500 EMU（10 x 5.625 英寸）。放置任何元素前先读取 `pageSize`；有些文稿是 4:3 或自定义尺寸。 - **An element's real size is `size` times its transform scale.** The API often stores a 3000000 x 3000000 base size and scales it: a title that renders 9.32 in wide can report `size.width` of 3000000 (3.28 in) with `scaleX` 2.84. Position is `translateX` / `translateY`, the top-left corner. Always multiply before reasoning about layout. **元素的真实尺寸是 `size` 乘以其变换缩放。**API 常存储 3000000 x 3000000 的基础尺寸再行缩放：一个渲染宽度 9.32 英寸的标题可能报告 `size.width` 为 3000000（3.28 英寸）、`scaleX` 为 2.84。位置由 `translateX` / `translateY` 给出，即左上角。推导布局前务必先做乘法。 - **A table's size comes from its columns and rows.** A table's `size` field is not its rendered size. Sum `tableColumns[].columnWidth` and `tableRows[].rowHeight` instead. Rows grow taller to fit their text, so a table can end up taller than requested. **表格的尺寸来自其列与行。**表格的 `size` 字段并非其渲染尺寸。应改用 `tableColumns[].columnWidth` 与 `tableRows[].rowHeight` 求和。行会随文字变高，因此表格最终可能比请求的高。 - **Object IDs are yours to choose.** When creating a slide or element, set `objectId`: 5 to 50 characters, unique in the deck, letters, digits, `_`, `-` and `:`, starting with a letter, digit or `_`. Name them by slide and role (`s4_title`, `s4_chart`) so later requests in the same batch, and later turns, can target them. **对象 ID 由你自行指定。**创建幻灯片或元素时设置 `objectId`：5 到 50 个字符，全文稿唯一，可用字母、数字、`_`、`-` 和 `:`，以字母、数字或 `_` 开头。按页面和角色命名（`s4_title`、`s4_chart`），以便同批次后续请求和后续轮次能够定位它们。 - **Text inside a shape or table cell has its own index,** starting at 0. `textRange: {"type": "ALL"}` covers all of it and is the safest target for styling. `insertText` without `insertionIndex` inserts at 0, before the existing text; to append, pass the text's length in UTF-16 units, not counting the final newline the read shows. Unlike Docs, Slides gives no error for an index inside an emoji such as 🙂: it moves an insert past the emoji and widens a delete to the whole emoji. **形状或表格单元格内的文字有独立索引，**从 0 开始。`textRange: {"type": "ALL"}` 覆盖全部文字，是样式设置最安全的目标。不带 `insertionIndex` 的 `insertText` 在位置 0 插入，即现有文字之前；要追加，传入以 UTF-16 单位计的文字长度，不把读取结果显示的末尾换行符计入。与 Docs 不同，Slides 对落在 🙂 这类 emoji 内部的索引不报错：它会把插入点移到 emoji 之后，并把删除范围扩大到整个 emoji。 ## Read / 读取 - **Always pass a field mask.** An unmasked read returns every layout and master: 150 KB for a three-slide deck. This mask returns what editing and the helper need, about 5 KB for the same deck: **务必传入字段掩码。**不带掩码的读取会返回所有版式和母版：三页的文稿约 150 KB。下面的掩码只返回编辑和辅助脚本所需的内容，同一文稿约 5 KB： ```json ["revisionId,pageSize,layouts(objectId,layoutProperties.name),slides(objectId,slideProperties.layoutObjectId,pageElements(objectId,size,transform,shape(shapeType,placeholder,text.textElements(textRun(content,style.fontSize,style.bold))),table(rows,columns,tableColumns,tableRows(rowHeight,tableCells(location,text.textElements.textRun.content))),image.contentUrl,sheetsChart(spreadsheetId,chartId),line.lineType,elementGroup.children.objectId))"] ``` Unlike the Sheets connector, Slides accepts parentheses in masks. 与 Sheets 连接器不同，Slides 的掩码接受括号。 - **One slide:** `read_slide_page` with a `pageId` and a mask starting at `pageElements(...)`. **单页读取：**用 `read_slide_page`，传 `pageId` 和以 `pageElements(...)` 开头的掩码。 - **Text only:** Drive `read_file_content` gives the deck's text compactly when you only need to know what it says. **仅取文字：**只需知道文稿内容时，Drive 的 `read_file_content` 能紧凑地给出全文文字。 - **Outline with real geometry:** save the masked read to a file and run: **带真实几何信息的轮廓：**把带掩码的读取结果存入文件，然后运行： ``` python /scripts/slides_helper.py outline deck.json [3] slide s4_slide layout BLANK s4_title shape x=0.50 y=0.35 w=9.00 h=0.70 TEXT_BOX 32pt 'Revenue grew 42% year over year' s4_table table x=3.70 y=1.30 w=5.80 h=1.20 2x3 first row ['Metric', 'Q1', 'Q2'] s4_note shape x=0.50 y=4.60 w=4.00 h=0.30 TEXT_BOX 12pt 'This footnote is...' !! TEXT MAY OVERFLOW (needs ~0.80 in) ``` It flags elements off the page, boxes that overlap, text that probably overflows its box, and empty placeholders. "inherited size" means the font size comes from the layout, so the overflow check is skipped for that box. An overlap flag means the boxes intersect; check the render to see whether the content actually collides. 它会标记超出页面的元素、相互重叠的文本框、可能溢出文本框的文字以及空占位符。"inherited size"（继承字号）表示字号来自版式，因此该框会跳过溢出检查。重叠标记表示两个框相交；需查看渲染结果判断内容是否真的相撞。 ## Build slides / 构建幻灯片 Build new slides and elements from an inch-based spec with `slides_helper.py build`. It converts to EMU, sets unscaled transforms, checks IDs, styles text, fills tables, and warns about text that won't fit. 用 `slides_helper.py build` 按基于英寸的规格构建新幻灯片和元素。它会换算成 EMU、设置未缩放的变换、检查 ID、设置文字样式、填充表格，并对放不下的文字发出警告。 ```json {"slides": [ {"id": "s4_slide", "layout": "BLANK", "index": 3, "elements": [ {"id": "s4_title", "type": "text", "x": 0.5, "y": 0.35, "w": 9, "h": 0.7, "text": "Revenue grew 42% year over year", "size": 32, "bold": true, "color": "#1F2937"}, {"id": "s4_card", "type": "round_rect", "x": 0.5, "y": 1.3, "w": 2.8, "h": 1.6, "fill": "#E8EEF7", "text": "ARR\n$4.2M", "size": 24, "bold": true, "color": "#1F3864", "align": "CENTER"}, {"id": "s4_table", "type": "table", "x": 3.7, "y": 1.3, "w": 5.8, "size": 14, "rows": [["Metric", "Q1", "Q2"], ["ARR", "$3.0M", "$4.2M"]], "header": true, "col_align": ["START", "END", "END"]}]}, {"id": "s3_slide", "existing": true, "elements": [{"id": "s3_label", "type": "text", "x": 0.5, "y": 2.1, "w": 4, "h": 0.5, "text": "of pilots converted", "size": 16}]}]} ``` ``` python /scripts/slides_helper.py build spec.json --revision [--page 10x5.625] ``` The output is the full `requests` and `writeControl` for `update_presentation`; warnings go to stderr. Fix every warning before sending, apart from the small-text ones that "Applying the design rules" allows. Slides never shrinks text to fit, so a warned box will spill. Build also warns about text boxes and shapes under 14 pt that aren't a short footer line at the bottom of the slide, and about typed bullet marks. Element types: `text`, `rect`, `round_rect`, `ellipse`, `table`. On a text element, `"bullets": true` makes each line a bullet and `"space_below"` adds points after each paragraph (about 8 to 10 points suits bulleted lines). On a table, `"col_widths"` sets each column in inches (give a label column more room than number columns) and `"col_align"` aligns each column (`"END"` for numbers). Set `"existing": true` to add elements to a slide that already exists. Pass `--page` when the deck isn't 10 x 5.625 in. 输出是 `update_presentation` 所需的完整 `requests` 和 `writeControl`；警告输出到 stderr。发送前修复每一个警告，"应用设计规则"一节所允许的小字警告除外。Slides 从不缩小文字来适配，因此被警告的文本框一定会溢出。`build` 还会对小于 14pt、且不属于幻灯片底部短页脚行的文本框和形状发出警告，也会对手工键入的列表符号发出警告。元素类型：`text`、`rect`、`round_rect`、`ellipse`、`table`。对文本元素，`"bullets": true` 把每一行变成列表项，`"space_below"` 在每段之后加间距（约 8 到 10 磅适合列表行）。对表格，`"col_widths"` 以英寸设定各列宽（标签列应比数字列更宽），`"col_align"` 设置各列对齐（数字用 `"END"`）。向已存在的幻灯片添加元素时设置 `"existing": true`。文稿不是 10 x 5.625 英寸时传 `--page`。 ## Edit recipes / 编辑配方 Each recipe is part of one `update_presentation` call with `writeControl.requiredRevisionId` from your last read. 每个配方都是一次 `update_presentation` 调用的组成部分，`writeControl.requiredRevisionId` 取自你上一次读取。 **Change text everywhere.** `replaceAllText` with `containsText: {"text": ..., "matchCase": true}` needs no IDs. Limit it with `pageObjectIds` to change only some slides. Use `{{placeholders}}` in templates for this. **全局替换文字。**`replaceAllText` 配 `containsText: {"text": ..., "matchCase": true}` 无需 ID。用 `pageObjectIds` 限定范围，只改动部分幻灯片。模板中的 `{{placeholders}}` 正是为它准备的。 **Replace one box's text.** `deleteText` with `textRange: {"type": "ALL"}`, then `insertText` at `insertionIndex: 0`. The new text keeps the box's style. Deleting from an already-empty box fails, so check the read first. **替换单个文本框的文字。**先用 `deleteText` 配 `textRange: {"type": "ALL"}`，再在 `insertionIndex: 0` 处 `insertText`。新文字沿用该框的样式。对已空的文本框执行删除会失败，所以先核对读取结果。 **Use a layout's placeholders.** `createSlide` with `slideLayoutReference: {"predefinedLayout": "TITLE_AND_BODY"}` and `placeholderIdMappings` naming the placeholders you'll fill: **使用版式的占位符。**`createSlide` 配 `slideLayoutReference: {"predefinedLayout": "TITLE_AND_BODY"}`，并用 `placeholderIdMappings` 指明你要填写的占位符： ```json {"createSlide": {"objectId": "s2_slide", "insertionIndex": 1, "slideLayoutReference": {"predefinedLayout": "TITLE_AND_BODY"}, "placeholderIdMappings": [ {"layoutPlaceholder": {"type": "TITLE", "index": 0}, "objectId": "s2_title"}, {"layoutPlaceholder": {"type": "BODY", "index": 0}, "objectId": "s2_body"}]}} ``` Then `insertText` into `s2_title` and `s2_body`. Placeholder text takes the theme's font and size, which keeps the deck consistent. Predefined layouts include `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `BIG_NUMBER`, and `BLANK`. A deck with a custom theme may name its layouts differently; the masked read lists them, and `slideLayoutReference: {"layoutId": ...}` picks one by ID. Fill or delete every placeholder you create, because an empty one shows prompt text in the editor. 然后向 `s2_title` 和 `s2_body` 执行 `insertText`。占位符文字继承主题的字体和字号，从而保持文稿一致。预定义版式包括 `TITLE`、`TITLE_AND_BODY`、`TITLE_AND_TWO_COLUMNS`、`TITLE_ONLY`、`SECTION_HEADER`、`BIG_NUMBER` 和 `BLANK`。带自定义主题的文稿版式名称可能不同；带掩码的读取会列出它们，用 `slideLayoutReference: {"layoutId": ...}` 按 ID 选取。你创建的每个占位符都要填写或删除，因为空占位符会在编辑器里显示提示文字。 **Bullets.** Insert lines separated by real newlines, then `createParagraphBullets` with `textRange: {"type": "ALL"}` and `bulletPreset: "BULLET_DISC_CIRCLE_SQUARE"`. Typed "- " is text, not a bullet, and `createParagraphBullets` keeps typed markers as text, so leave them out of the inserted lines. **列表。**插入以真实换行符分隔的多行文字，然后用 `createParagraphBullets` 配 `textRange: {"type": "ALL"}` 和 `bulletPreset: "BULLET_DISC_CIRCLE_SQUARE"`。手工键入的 "- " 只是文字，不是列表符号，且 `createParagraphBullets` 会把键入的符号保留为文字，因此插入的行里不要带它们。 **Style text.** `updateTextStyle` with `style` and a matching `fields` list, such as `"fontSize,bold,foregroundColor"`. Font size is `{"magnitude": 24, "unit": "PT"}`; color is `{"opaqueColor": {"rgbColor": {"red": ..., "green": ..., "blue": ...}}}` with values from 0 to 1. Alignment is a paragraph property: `updateParagraphStyle` with `style.alignment` (`START`, `CENTER`, `END`, `JUSTIFIED`). **设置文字样式。**`updateTextStyle` 配 `style` 和对应的 `fields` 列表，例如 `"fontSize,bold,foregroundColor"`。字号写作 `{"magnitude": 24, "unit": "PT"}`；颜色写作 `{"opaqueColor": {"rgbColor": {"red": ..., "green": ..., "blue": ...}}}`，取值 0 到 1。对齐是段落属性：`updateParagraphStyle` 配 `style.alignment`（`START`、`CENTER`、`END`、`JUSTIFIED`）。 **Shape fill and outline.** `updateShapeProperties` with `shapeBackgroundFill.solidFill.color` and `outline.propertyState: "NOT_RENDERED"` to drop the border. **形状填充与轮廓。**`updateShapeProperties` 配 `shapeBackgroundFill.solidFill.color`；要去掉边框，用 `outline.propertyState: "NOT_RENDERED"`。 **Move or resize.** `updatePageElementTransform` with `applyMode: "ABSOLUTE"` and a full transform. Remember that the element's base `size` stays the same, so set `scaleX` / `scaleY` to the rendered size divided by the base size. Moving is safer than resizing: to resize a text box, it is often simpler to delete it and create a new one at the right size. **移动或缩放。**`updatePageElementTransform` 配 `applyMode: "ABSOLUTE"` 和完整的变换矩阵。注意元素的基础 `size` 不变，因此要把 `scaleX` / `scaleY` 设为渲染尺寸除以基础尺寸。移动比缩放安全：要改变文本框大小时，删掉重建一个尺寸合适的往往更简单。 **Tables.** `insertText` and `updateTextStyle` take `cellLocation: {"rowIndex": r, "columnIndex": c}`. `updateTableCellProperties` with a `tableRange` sets cell fills. `insertTableRows`, `deleteTableRow`, `insertTableColumns`, and `deleteTableColumn` change structure. `updateTableColumnProperties` sets column widths in EMU. **表格。**`insertText` 和 `updateTextStyle` 接受 `cellLocation: {"rowIndex": r, "columnIndex": c}`。`updateTableCellProperties` 配 `tableRange` 设置单元格填充。`insertTableRows`、`deleteTableRow`、`insertTableColumns` 和 `deleteTableColumn` 改变结构。`updateTableColumnProperties` 以 EMU 设定列宽。 **Charts from Sheets.** `createSheetsChart` with the sheet's `spreadsheetId`, the `chartId` (from the Sheets `addChart` reply, or from `get_spreadsheet` with `fields: ["sheets.properties.title", "sheets.charts.chartId", "sheets.charts.spec.title"]`), `linkingMode: "LINKED"`, and `elementProperties`. A linked chart stays tied to its data; `refreshSheetsChart` updates it after the sheet changes. Don't paste a chart as an image. **来自 Sheets 的图表。**`createSheetsChart` 配表格文件的 `spreadsheetId`、`chartId`（来自 Sheets `addChart` 的响应，或用 `get_spreadsheet` 配 `fields: ["sheets.properties.title", "sheets.charts.chartId", "sheets.charts.spec.title"]` 获取）、`linkingMode: "LINKED"` 和 `elementProperties`。关联图表与其数据保持绑定；表格文件变更后用 `refreshSheetsChart` 更新。不要把图表粘贴成图片。 **Images.** `createImage` needs a URL Google can fetch publicly. For a local image, build the slide in a .pptx with the `pptx` skill and upload it, or ask the user to insert the image. **图片。**`createImage` 需要 Google 可公开抓取的 URL。本地图片可先用 `pptx` 技能构建 .pptx 再上传，或请用户自行插入图片。 **Reorder, copy, delete.** `updateSlidesPosition` with `slideObjectIds` and `insertionIndex`; `duplicateObject` for a slide or element (set `objectIds` to name the copies); `deleteObject` for either. List `slideObjectIds` in the slides' current order in the deck, or the whole batch is rejected; the listed slides move as a block and keep that order. `duplicateObject` puts each copy directly after the original, so copying one slide several times leaves the copies in the reverse of the order you sent the requests. To make several copies in a chosen order in one batch: duplicate the original once per copy, sending the requests in the reverse of that order, so the copies end up after it in the order you want. Fill them. If they belong elsewhere in the deck, move them as a block with one `updateSlidesPosition` that lists them in that order. Delete the original if it was a template. **重排、复制、删除。**`updateSlidesPosition` 配 `slideObjectIds` 和 `insertionIndex`；复制幻灯片或元素用 `duplicateObject`（用 `objectIds` 为副本命名）；二者都可用 `deleteObject` 删除。`slideObjectIds` 必须按幻灯片在文稿中的当前顺序列出，否则整批请求被拒；列出的幻灯片作为一个整体移动并保持该顺序。`duplicateObject` 把每个副本直接放在原件之后，因此对同一页多次复制时，副本顺序与你发送请求的顺序相反。要在一个批次中按选定顺序生成多个副本：每个副本复制一次原件，并按目标顺序的逆序发送请求，这样副本最终按你想要的顺序排列在原件之后。填好它们的内容。若它们应属于文稿的其他位置，用一次 `updateSlidesPosition` 按该顺序列出并整体移动。若原件只是模板，删除它。 ## Verify / 验证 1. Read the deck with the mask above and run `slides_helper.py outline`. Check the text, slide order, and every flag. 1. 用上文掩码读取文稿并运行 `slides_helper.py outline`。检查文字、幻灯片顺序和每一个标记。 2. Where you can run code, look at the rendered slides. Export with Drive `download_file_content` and `exportMimeType: "application/pdf"`; a large result is saved to a file. If the export comes back in the chat instead, skip the render rather than copying it into a file. Otherwise: 2. 在可以运行代码的场合，查看渲染后的幻灯片。用 Drive 的 `download_file_content` 配 `exportMimeType: "application/pdf"` 导出；较大的结果会存为文件。如果导出内容直接出现在对话里，就跳过渲染，不要把它抄进文件。否则： ``` python /scripts/render_export.py render --pages 3-4 ``` Open each page image and check for overflow, overlap, clipped text, and low contrast. `read_slide_page_thumbnail` returns an image URL instead; use it only if your surface can open image URLs, since some environments can't. 打开每一页的图片，检查溢出、重叠、文字被裁切和低对比问题。`read_slide_page_thumbnail` 返回的是图片 URL；仅当你的运行环境能打开图片 URL 时才使用它，因为有些环境做不到。 3. Fix the problems, then check again. If you can't run code or render, rely on step 1 and tell the user you couldn't check the layout visually. 3. 修复问题后再次检查。不能运行代码或渲染时，依赖第 1 步，并告知用户你无法以视觉方式核查版面。 ## Slides failures / Slides 常见故障 | Symptom | Cause | Fix | |---|---|---| | A read is 100 KB or more | No field mask, so layouts and masters came back | Use the mask in Read. | | Elements land in the wrong place or size | Base `size` used without the transform scale | Use `slides_helper.py outline` for real geometry, and `build` for new elements. | | A table is a different size than requested | Table size comes from columns and rows, and rows grow with text | Read `tableColumns` and `tableRows`; set widths with `updateTableColumnProperties`. | | Text spills out of its box | Slides doesn't shrink text | Enlarge the box, cut the text, or split the slide (Fitting text above says when a smaller size is allowed). `build` warns before you send. | | `The object ID (ab) length should not be less than 5`, or a duplicate ID error | IDs too short, reused, or with invalid characters | Use descriptive IDs such as `s4_title`, unique per deck. | | `Unknown dimension unit UNIT_UNSPECIFIED` | A size or transform without `unit: "EMU"`, or a new shape with no size | Give every new element a full `size` and `transform` with units. `build` does this. | | Prompt text such as "Click to add title" appears | An empty placeholder | Fill it or delete it. `outline` flags these. | | `createImage` fails | The URL isn't publicly fetchable | Use a public URL, or the .pptx upload route. | | `deleteText`: `The startIndex 0 must be less than the endIndex 0` | The box has no text to delete | Skip the delete when the read shows no text. | | `createSlide`: `The placeholder (…) is not on the page` | `placeholderIdMappings` names a placeholder the layout doesn't have | Map only the placeholders that layout has; `TITLE_ONLY` has no `BODY`. | | 症状 | 原因 | 解决方法 | |---|---|---| | 一次读取达到 100 KB 或更多 | 未传字段掩码，版式和母版全部返回 | 使用"读取"一节中的掩码。 | | 元素位置或尺寸不对 | 直接使用了基础 `size` 而未乘变换缩放 | 用 `slides_helper.py outline` 获取真实几何信息，新元素用 `build`。 | | 表格尺寸与请求不符 | 表格尺寸来自列与行，且行随文字变高 | 读取 `tableColumns` 和 `tableRows`；用 `updateTableColumnProperties` 设定列宽。 | | 文字溢出文本框 | Slides 不会缩小文字适配 | 扩大文本框、删减文字或拆分幻灯片（上文"文字适配"说明了何时允许缩小字号）。发送前 `build` 会发出警告。 | | `The object ID (ab) length should not be less than 5`，或 ID 重复错误 | ID 过短、重复或含非法字符 | 使用 `s4_title` 这类描述性 ID，并保证全文稿唯一。 | | `Unknown dimension unit UNIT_UNSPECIFIED` | 尺寸或变换缺少 `unit: "EMU"`，或新形状没有尺寸 | 为每个新元素提供带单位的完整 `size` 和 `transform`。`build` 会自动完成。 | | 出现"Click to add title"等提示文字 | 存在空占位符 | 填写或删除它。`outline` 会标记这些情况。 | | `createImage` 失败 | URL 无法公开抓取 | 换用公开 URL，或走 .pptx 上传路线。 | | `deleteText`：`The startIndex 0 must be less than the endIndex 0` | 文本框内没有可删除的文字 | 读取结果显示无文字时跳过删除。 | | `createSlide`：`The placeholder (…) is not on the page` | `placeholderIdMappings` 指定了版式没有的占位符 | 只映射该版式已有的占位符；`TITLE_ONLY` 没有 `BODY`。 |