简介

您可以通过 Google Slides API 创建和修改 Google 幻灯片演示文稿。

应用可与 Google Slides API 进行集成以使用用户和系统提供的数据自动创建美观的幻灯片组。例如,您可以使用来自数据库的客户详细信息,并将该信息与预先设计的模板和选择的配置选项结合使用以创建完整的演示文稿,所需时间只是手动创建演示文稿所花时间的一个零头。

API 概览

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

您使用 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 对应于文件资源的 ID。

页面和页面元素可通过对象 ID 进行识别。

Pages

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

硕士 幻灯片母版可定义默认文本样式、背景以及使用此母版的所有幻灯片中显示的页面元素。应将所有幻灯片中必须显示的页面元素添加到母版。大多数演示文稿都有一个母版,但某些演示文稿可能有多个母版或没有母版。
布局 在使用布局的幻灯片上,布局可充当模板,指示默认情况下如何安排页面元素。每个布局都与一个母版关联。
幻灯片 这些页面包含您向受众提供的内容。 大多数幻灯片都基于母版和布局。在创建幻灯片后,您可以为每张幻灯片指定要使用的布局。
备注 这些页面包含演示文稿讲义的内容,其中包括一个含有幻灯片演讲者备注的形状。每张幻灯片都有一个对应的备注页面。只有演讲者备注形状中的文本才可以使用 Slides API 修改。
记事母版 备注母版定义所有备注页面的默认文本样式和页面元素。备注母版在 Slides API 中为只读。

页面元素

页面元素是放置在页面上的可视组件。API 会显示多种页面元素:

群组 一组作为单个单元对待的页面元素。这些元素可以一起移动、缩放和旋转。
形状 一种普通可视对象,如矩形、椭圆形和文本框。 形状可以包含文本,因此它们是最常用来构建幻灯片的页面元素。
Image 导入幻灯片的图形。
视频 导入幻灯片的视频。
折线图 可视的线条、曲线或连接器。
包含内容的网格。
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
使用图片和视频: CreateImageRequest
CreateVideoRequest
UpdateImagePropertiesRequest
UpdateVideoPropertiesRequest
ReplaceAllShapesWithImageRequest
DuplicateObjectRequest
DeleteObjectRequest
处理文本: InsertTextRequest
DeleteTextRequest
ReplaceAllTextRequest
CreateParagraphBulletsRequest
DeleteParagraphBulletsRequest
UpdateTextStyleRequest
UpdateParagraphStyleRequest

batchUpdate 方法会返回一个响应正文,其中包含对每个请求的响应。每个响应与对应的请求占用相同的索引;对于没有适用的响应的请求,该索引处的响应将为空。一般情况下,各种 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。

不过,在幻灯片界面中更改演示文稿后,您不能依赖未更改的对象 ID。例如,如果某人使用幻灯片界面复制粘贴页面元素,然后删除原始页面元素,那么,页面元素现在将有一个新的唯一 ID,您以前通过 API 提供的 ID 将丢失。因此,我们不建议您在应用的存储空间中存储对象 ID。而应根据对象的文本内容或替代文本查找演示文稿中的对象。

正常情况下,新创建的演示文稿针对默认的幻灯片、母版和文本框使用一个统一的 ID 集。这些 ID 会随着时间而发生变化,因此,我们不建议您依赖此功能。您可以使用通过调用 create()get() 返回的演示文稿对象查找您要修改的元素。