为了有效地使用幻灯片 API,您需要了解演示文稿及其组件的架构,以及这些组件之间的交互。本页面详细介绍了以下主题:
- 演示文稿组件的概念模型
- API 如何表示这些组件
- 组件的样式属性
阅读本概念概览和其他概念概览,将有助于您更轻松地理解和使用方法指南、参考文档和食谱示例。
演示文稿、页面和页面元素
Google 幻灯片中最外层的容器元素是演示文稿。此类单元是指可以保存在 Google 云端硬盘中、与其他用户共享以及执行其他操作的单元。
每个演示文稿都包含不同类型的页面。其中一种页面类型是幻灯片,即演示文稿呈现在屏幕上时用户查看和切换的页面。
每个页面都包含若干页面元素,这些元素共同构成了页面的内容,如下图所示:
除了幻灯片之外,还有其他类型的页面可让您将设计应用于许多不同的幻灯片,从而呈现一致的外观。这些其他页面类型是“母版”和“布局”,其属性决定了幻灯片的呈现方式,如下图所示:
母版 - 主页有以下两种用途。母版上的占位符包含整个演示文稿使用的文本样式的默认值。幻灯片母版上的背景和任何其他形状构成了基于该母版的所有幻灯片的默认背景。如果您希望在演示文稿的每张幻灯片上都显示公司徽标,请将其放在母版上。
布局 - 布局模板决定了各类幻灯片上内容的排列方式。例如,如果您想让所有标题幻灯片都有特定的外观,可以修改标题布局模板。
另外还有两种页面,即备注页面和备注母版,它们最适用于使用演讲者备注。
API 表示法类型和结构
本部分介绍了 Slides API 如何表示上述 Google 幻灯片概念模型。
下图描述了幻灯片 API 中演示文稿、页面和页面元素这些类型之间的关系:
以下部分介绍了这些类型在 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 表格导入幻灯片的图表。 |
页面和页面元素属性
借助幻灯片 API,您可以读取和更新演示文稿中页面和页面元素的外观。不同的页面元素支持不同的属性,用于控制页面元素的呈现方式。
每个页面元素种类都有一个相应的属性元素和属性更新消息,例如:
- 有一个页面元素类型为 Shape
- 其属性字段为 shapeProperties
- 更新这些属性的请求为 UpdateShapePropertiesRequest
每种页面元素类型都存在相同的一组元素/属性/更新请求:Image/imageProperties/UpdateImageProperties,等等。
读取元素时,只要遇到属性属性,就可以读取该属性;要更改其中的值,请将其与匹配的请求类型一起使用,作为 batchUpdate 方法的载荷,从而更改呈现中的这些值。
属性的类型
有一些属性是幻灯片 API 中多种对象通用的:
媒体资源 | 说明 |
---|---|
颜色 | 幻灯片 API 中的颜色可以是 RGB 值,也可以是对主题颜色的引用。主题颜色通过名称(例如“DARK1”)进行引用,并可使用页面的配色方案映射到 RGB 值。在幻灯片编辑器中更改演示文稿主题时,通常会更新此配色方案。 |
填充 | 填充表示对象内部的空白区域的渲染。幻灯片中最常支持的填充是纯色填充,即以单一纯色填充对象的内部。填充也可以用作页面的背景。 |
轮廓 | outline 表示围绕页面元素的一组线条。线条的颜色通过 Fill 控制。调用方还可以调整轮廓的宽度和短划线样式。 |
Shadow | 阴影表示一种旨在模拟物体投射的物理阴影的视觉效果。目前,Slides API 中的阴影为只读状态。 |
更新属性
如需更新属性,请在 batchUpdate 调用中使用相应的 Update...Properties
请求,例如使用 UpdateShapeProperties
表示形状。这些请求接受完整的属性消息,并且可以使用字段掩码来确定应更新属性消息中的哪些字段。
继承自媒体资源的权限
页面或页面元素可以从其父对象继承属性。对象的属性(包括其定义的属性以及其继承的属性)决定了其最终的视觉外观。
- 页面属性 - 页面会继承其自己不定义但在其所基于的布局或母版中定义的所有属性。
- 形状属性 - 您可以将形状标记为占位符,以便明确引用要从中继承属性的其他占位符形状(在页面的父布局或母版上)。
以下段落将进一步介绍这些概念。
页面属性的继承
幻灯片、布局和母版的结构定义了演示文稿中的继承层次结构:幻灯片从布局继承,布局从母版继承。幻灯片的父布局和母版在幻灯片的 slideProperties 字段中指定。
页面可以从父页面继承属性,例如背景和配色方案。若要继承属性,子页面只是不在其 PageProperties 消息中设置该属性的值。通过不“替换”父页面定义的值,页面会接受继承的值。
下图展示了幻灯片从布局继承属性的示意图,后者从母版继承:
用于渲染幻灯片的属性是幻灯片所定义属性以及幻灯片所继承属性的组合。在此示例中,用于呈现幻灯片 1 的解析值如下:
- 属性 A 为“红色”。
- PropertyB 为“Orange”。
形状属性的继承
形状可以从其他形状继承 fill、outline 或 shadow 等属性。如果设置了 Shape.placeholder 字段,形状就是占位符。子占位符的 Shape.placeholder.parentObjectId
字段会标识其父占位符。当您根据布局创建新幻灯片时,该布局中的任何占位符都会在新幻灯片中显示为子形状。同样,主页面上的占位符可充当布局占位符的父级。
定义此继承层次结构后,子页面通过不在其 ShapeProperties 消息中设置该属性来继承该属性。通过不替换父形状定义的值,子形状会接受继承的值。
下图显示了幻灯片、布局和母版中包含的三个占位符之间的属性继承:
用于渲染占位符形状的属性是形状所定义属性和其继承的属性的组合。在此示例中,这些形状的解析值如下所示:
- 占位符 1:propertyA 渲染为“Yellow”,propertyB 渲染为“Green”。
- 占位符 2:propertyA 渲染为“Yellow”,propertyB 渲染为“Purple”。
- 占位符 3:propertyA 渲染为“Yellow”,propertyB 渲染为“Purple”。
形状是唯一可以拥有父项的页面元素类型。其他类型(例如图片、表格和图表)不能是占位符,也不能有父级。
使用 PropertyState“隐藏”属性
PropertyState 枚举用于控制某个形状的属性是否实际用于渲染,或者该值是否仅用于子形状继承。在其页面上渲染形状时,系统不会使用属性状态为 NOT_RENDERED
的属性,但具有相应属性状态 RENDERED
的子项仍然可以继承此属性。
下图显示了三个操纵 PropertyState 字段的占位符之间的属性继承:
形状属性的渲染可能会受到 PropertyState 字段的影响。在此示例中,这些形状的解析值如下所示:
- 占位符 1:propertyA 渲染为“Red”。
- 占位符 2:propertyA 未渲染。如果这是 outline 属性,Placeholder2 将没有轮廓。
- 占位符 3:propertyA 未渲染。
PropertyState 枚举还有一个可能的值:INHERIT
属性状态表示属性状态本身是继承的,应使用父项的值。没有父项的形状的属性状态不能为 INHERIT
。