页面、页面元素和属性

为了有效使用 Slides API，您需要了解演示的架构及其组件，以及这些组件之间的互动。本页详细介绍了以下主题：

  • 演示组件的概念模型
  • API 如何表示这些组件
  • 组件的样式属性

阅读本文和其他概念概览有助于您更轻松地理解和使用操作指南、参考文档和配方示例。

演示文稿、页面和页面元素

Google 幻灯片中最外层的容器元素是演示文稿。这是可以保存到 Google 云端硬盘、与其他用户共享等的单位。

每个演示文稿都包含各种类型的页面。一种类型的页面是幻灯片，当演示文稿呈现在屏幕上时，用户会看到这些页面并可在这些页面之间切换。

每个页面都包含若干页面元素，这些元素共同构成了页面的内容，如下图所示：

幻灯片架构图

除了幻灯片之外，还有其他类型的页面可让您将设计应用于许多不同的幻灯片，从而打造一致的外观。其他页面类型包括母版和布局，它们的属性决定了幻灯片的呈现方式，如下面的图表所示：

主题架构图

主页 - 主页有两个用途。母版上的占位符包含整个演示文稿中使用的文本样式的默认值。母版幻灯片上的背景和任何其他形状构成了基于该母版的所有幻灯片的默认背景。如果您希望公司徽标显示在演示文稿中的每张幻灯片上，请将其放置在母版中。

布局 - 布局模板决定了内容在每种类型的幻灯片上的排列方式。如果您希望所有标题幻灯片都采用某种特定外观，可以修改标题布局模板。

还有两种类型的页面（备注页和备注母版）主要用于处理演讲者备注。

API 表示类型和结构

本部分介绍了上述 Google 幻灯片概念模型在 Slides API 中的表示方式。

下图展示了 Slides API 中演示文稿、页面和页面元素之间的关系：

ERD 风格的图表

以下部分展示了这些类型在 JSON 中的表示方式。

演示文稿

演示文稿包含许多属性，并包含其中的页面：

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { object(Page) } ],
  "notesMaster": object(Page),
  "locale": string,
}

页面

网页包含一组属性，并包含其中的网页元素：

{
  "objectId": string,
  "pageType": enum(PageType),
  "pageElements": [ { object(PageElement) } ],
  "pageProperties": { object(PageProperties) },

  // Union field properties can be only one of the following:
  "slideProperties": { object(SlideProperties) },
  "layoutProperties": { object(LayoutProperties) },
  "notesProperties": { object(NotesProperties) },
  // End of list of possible types for union field properties.
}

页面元素

页面元素是放置在页面上的视觉组件。API 中的页面元素包含许多属性，其中包括一个因页面元素种类而异的字段：

{
  "objectId": string,
  "size": { object(Size) },
  "transform": { object(AffineTransform) },
  "title": string,
  "description": string,

  // Union field element_kind can be only one of the following:
  "elementGroup": { object(Group) },
  "shape": { object(Shape) },
  "image": { object(Image) },
  "video": { object(Video) },
  "line": { object(Line) },
  "table": { object(Table) },
  "wordArt": { object(WordArt) },
  "sheetsChart": { object(SheetsChart) },
  // End of list of possible types for union field element_kind.
}

如上定义中的联合字段 element_kind 所定义，网页元素有多种类型。下表介绍了这些类型的网页元素：

元素种类 说明
群组 一组被视为单个单元的网页元素。您可以同时移动、缩放和旋转它们。
形状 纯视觉对象，例如矩形、椭圆和文本框。形状可以包含文字，因此是制作幻灯片最常用的页面元素。
图片 导入到 Google 幻灯片中的图形。
视频 导入到 Google 幻灯片中的视频。
折线图 视觉线条、曲线或连接器。
表 内容网格。
WordArt 一种行为更像形状的视觉文本元素。
SheetsChart 从 Google 表格导入到 Google 幻灯片中的图表。

网页和页面元素属性

借助 Slides API，您可以读取和更新演示文稿中页面和页面元素的外观。不同的页面元素支持不同的属性，这些属性用于控制页面元素的呈现方式。

每种页面元素类型都有对应的属性元素和属性更新消息，例如：

每种页面元素类型都有一组相同的元素/属性/更新请求：Image/imageProperties/UpdateImageProperties，依此类推。

您可以在读取元素时随时读取属性特性；如需更改其中的值，请将其与匹配的请求类型一起用作 batchUpdate 方法的载荷，以便您在演示文稿中更改这些值。

媒体资源类型

Slides API 中有几种对象的属性是通用的：

属性 说明
颜色 Slides API 中的颜色可以是 RGB 值，也可以是对主题颜色的引用。主题颜色按名称（例如“DARK1”）引用，可以使用网页的配色方案映射到 RGB 值。在 Google 幻灯片编辑器中更改演示文稿的主题时，此配色方案通常会更新。
填充 填充表示对象内部空白空间的渲染效果。在 Google 幻灯片中，最常支持的填充是纯色填充，即使用单一纯色填充对象的内部。填充还可用于页面的背景。
轮廓 轮廓表示围绕页面元素的一组线条。线条的颜色由填充控制。通话者还可以调整轮廓的宽度和虚线样式。
Shadow 阴影是一种视觉效果，旨在模拟对象投射的物理阴影。目前，Slides API 中的阴影是只读的。

更新属性

如需更新属性，请在 batchUpdate 调用中使用相应的 Update...Properties 请求，例如，对于形状，请使用 UpdateShapeProperties。这些请求接受完整的房源消息，并可以使用字段掩码来确定应更新房源消息中的哪些字段。

媒体资源继承

网页或页面元素可以从其父对象继承属性。对象的属性（包括其定义的属性和继承的属性）决定了其最终的视觉外观。

  • 页面属性 - 页面会继承其未定义但在所基于的布局或母版中定义的任何属性。
  • 形状属性 - 形状可以标记为占位符，让您可以明确引用另一个占位符形状（位于页面的父布局或母版上），从中继承属性。

以下段落将进一步说明这些想法。

网页属性的继承

幻灯片、布局和母版的结构定义了演示文稿中的继承层次结构：幻灯片继承自布局，而布局继承自母版。幻灯片的父布局和母版在幻灯片的 slideProperties 字段中指定。

网页可以从父网页继承属性，例如背景和配色方案。如需继承某个属性，子网页只需不在其 PageProperties 消息中为该属性设置值即可。通过不“替换”父级定义的值，网页接受继承的值。

下图展示了从布局继承属性的幻灯片，而布局又从母版继承属性：

幻灯片属性继承

用于呈现幻灯片的属性是其定义的属性和继承的属性的组合。在此示例中，用于呈现幻灯片 1 的已解析值如下所示：

  • PropertyA 为“Red”。
  • PropertyB 为“Orange”。

形状属性的继承

形状可以从其他形状继承属性，例如填充、轮廓或阴影。如果形状的 Shape.placeholder 字段已设置，则该形状为占位符。子占位符的 Shape.placeholder.parentObjectId 字段用于标识其父占位符。当您基于布局创建新幻灯片时，该布局中的所有占位符都会在新幻灯片中显示为子形状。同样，母版页上的占位符可以充当布局占位符的父级。

定义此继承层次结构后，子网页通过不在其 ShapeProperties 消息中设置相应值来继承属性。如果不替换父级定义的值，子形状会接受继承的值。

下图显示了幻灯片、布局和母版中包含的三个占位符之间的属性继承关系：

形状属性继承

用于渲染占位形状的属性是其定义和继承的属性的组合。在此示例中，这些形状的解析值如下：

  • Placeholder1：propertyA 呈现为“黄色”，propertyB 呈现为“绿色”。
  • Placeholder2：propertyA 呈现为“黄色”，propertyB 呈现为“紫色”。
  • Placeholder3：propertyA 呈现为“黄色”，propertyB 呈现为“紫色”。

只有形状类型的页面元素可以有父级。其他类型（例如图片、表格和图表）不能是占位符，也不能有父级。

使用 PropertyState“隐藏”属性

PropertyState 枚举用于控制形状的属性是否实际用于渲染，或者该值是否仅用于子形状的继承。在呈现具有属性状态 NOT_RENDERED 的属性时，系统不会使用该属性，但具有相应属性状态 RENDERED 的子项仍可继承该属性。

下图显示了三个操纵 PropertyState 字段的占位符之间的属性继承关系：

媒体资源状态和继承

形状属性的呈现可能会受到 PropertyState 字段的影响。在此示例中，这些形状的解析值如下所示：

  • Placeholder1：propertyA 呈现为“红色”。
  • Placeholder2：propertyA 未呈现。如果这是轮廓属性，则 Placeholder2 将没有轮廓。
  • Placeholder3：propertyA 未呈现。

PropertyState 枚举还有一个可能的值：INHERIT 属性状态表示属性状态本身是继承的，应使用父级的值。没有父级的形状不能具有 INHERIT 的属性状态。