简介

借助 Google Slides API,您可以创建和修改 Google 幻灯片演示文稿。

应用可以与 Google 幻灯片 API 集成,以便根据用户和系统提供的数据自动创建精美的演示文稿。例如,您可以使用数据库中的客户详细信息,并将其与预先设计的模板和选定的配置选项相结合,在手动创建演示文稿所需的时间内创建完成的演示文稿。

API 概览

演示文稿集合提供 了一些方法,可让您获取和更新演示文稿中的元素。

您使用 Slides API 时,大部分工作可能都是创建和更新演示文稿。您可以使用 batchUpdate方法来完成此操作; 此方法会接受 Request 对象列表,让您执行以下操作:

  • 创建幻灯片
  • 向幻灯片添加形状或表格等元素
  • 插入、更改和移除文本
  • 对元素应用转换
  • 更改幻灯片的顺序

如需了解详情,请参阅批量更新。如需查看如何使用此 API 的简单端到端示例,请参阅入门指南。

演示文稿的结构

Slides API 中的演示文稿由页面组成,页面包含页面 元素。

演示文稿的 ID 可从网址中派生:

https://docs.google.com/presentation/d/presentationId/edit

演示文稿 ID 是一个字符串,其中包含字母、数字和一些特殊字符。您可以使用以下正则表达式从 Google 表格网址中提取演示文稿 ID:

/presentation/d/([a-zA-Z0-9-_]+)

如果您熟悉 Drive API,则 presentationId 对应于 File 资源的 ID。

页面和页面元素由对象 ID 标识。

页面

Google 幻灯片具有以下几种页面:

母版 幻灯片母版定义了使用此母版的所有幻灯片中显示的默认文本样式、背景和页面元素。必须显示在所有幻灯片上的页面 元素应添加到母版中。大多数 演示文稿都有一个母版,但有些演示文稿可能有多个母版,也可能没有母版。
版式 版式充当模板,用于确定使用版式的幻灯片上的页面元素的默认排列方式。每个版式都与一个 母版相关联。
幻灯片 这些页面包含您向观众展示的内容。 大多数幻灯片都基于母版和版式。您可以在创建幻灯片时指定要为每张幻灯片使用的 版式。
备注 这些页面包含演示文稿讲义的内容,包括一个 包含幻灯片演讲者备注的形状。每张幻灯片都有一个 对应的备注页面。只有演讲者备注形状中的文本可以使用 Slides API 进行修改。
备注母版 备注母版定义了所有 备注页面的默认文本样式和页面元素。备注母版在 Slides API 中是只读的。

页面元素

页面元素是放置在页面上的视觉组件。此 API 公开了几种页面元素:

群组 一组页面元素,被视为一个单独的单元。它们可以 一起移动、缩放和旋转。
形状 简单的视觉对象,例如矩形、椭圆形和文本框。 形状可以包含文本,因此它们是构建幻灯片最常见的页面元素。
图片 导入到幻灯片中的图形。
视频 导入到幻灯片中的视频。
折线图 视觉线条、曲线或连接线。
内容网格。
WordArt 一种视觉文本元素,其行为更像是一种形状。
SheetsChart 从 Google 表格导入到幻灯片中的图表。

批量更新

借助 batchUpdate 方法 ,您可以更新演示文稿的许多方面。更改会分组到批次中,这样,如果一个请求失败,则不会写入任何其他(可能依赖于该请求的)更改。

batchUpdate 方法的工作方式是接受一个或多个 Request 对象,每个对象都指定要执行的单个请求类型。请求类型有很多种。下面按不同类别细分了请求类型。

使用幻灯片: CreateSlideRequest
UpdateSlidesPositionRequest
DuplicateObjectRequest
UpdatePagePropertiesRequest
DeleteObjectRequest
使用页面元素: CreateShapeRequest
CreateLineRequest
UpdatePageElementTransformRequest
UpdateShapePropertiesRequest
DuplicateObjectRequest
DeleteObjectRequest
使用表格: CreateTableRequest
InsertTableRowsRequest
InsertTableColumnsRequest
DeleteTableRowRequest
DeleteTableColumnRequest
UpdateTableRowPropertiesRequest
UpdateTableColumnPropertiesRequest
UpdateTableBorderPropertiesRequest
UpdateTableCellPropertiesRequest
MergeTableCellsRequest
UnmergeTableCellsRequest
DeleteObjectRequest
使用图表: CreateSheetsChartRequest
RefreshSheetsChartRequest
ReplaceAllShapesWithSheetsChartRequest
DeleteObjectRequest
使用 Google 图片和视频: CreateImageRequest
CreateVideoRequest
UpdateImagePropertiesRequest
UpdateVideoPropertiesRequest
ReplaceAllShapesWithImageRequest
DuplicateObjectRequest
DeleteObjectRequest
使用文本: InsertTextRequest
DeleteTextRequest
ReplaceAllTextRequest
CreateParagraphBulletsRequest
DeleteParagraphBulletsRequest
UpdateTextStyleRequest
UpdateParagraphStyleRequest

batchUpdate 方法会返回一个 响应正文, 其中包含 Response ,对应于每个请求。每个响应都占据与相应请求相同的索引;对于没有适用响应的请求,该索引处的响应将为空。各种 Create 请求通常都有响应,以便您了解新添加对象的 ID。

使用对象 ID

Slides API 中的演示文稿由页面和页面元素组成。 这些对象包含一个对象 ID 字符串,该字符串在演示文稿中是唯一的。

在创建时指定对象 ID

使用 batchUpdate 方法创建页面或页面元素时,您可以选择为新对象指定对象 ID。这样,您就可以在同一个 batchUpdate 请求中创建对象并对其进行修改,从而最大限度地减少对 Slides API 的调用次数并减少
配额使用量

在大多数情况下,我们建议您生成随机对象 ID。例如,如果您使用的是 Java,则 java.util.UUID.randomUUID().toString() 应该可以正常运行。

如果您的应用希望在较长的时间内跟踪对象,请不要依赖对象 ID,因为它可能会发生变化。如需了解详情,请参阅下一部分。

在不使用对象 ID 的情况下跟踪对象

当您发出 Slides API 请求时,对象 ID 通常会保留。(任何例外情况都会在方法的参考文档中说明。) 使用 Drive API 复制整个演示文稿也会保留对象 ID。

不过,您不能依赖于在 Slides 界面中更改演示文稿后对象 ID 保持不变。例如,如果有人使用 Slides 界面复制粘贴页面元素,然后删除原始页面元素,则该页面元素现在将具有新的唯一 ID,并且您之前通过 API 提供的 ID 将丢失。因此,我们不建议您将对象 ID 存储在应用的存储空间中。相反,您应该通过演示文稿的文本内容或替代文本查找演示文稿中的对象。

新创建的演示文稿通常会为默认幻灯片、母版和文本框使用一组一致的 ID。这些 ID 可能会随时间变化,因此我们不建议您依赖此功能。相反,请使用对 create() 或 get() 的调用返回的演示文稿对象查找要修改的元素 。