網頁、網頁元素和屬性

如要有效使用 Slides API，您必須瞭解簡報及其元件的架構，以及這些元件之間的互動。本頁面詳細說明下列主題：

  • 簡報元件的概念模型
  • API 如何表示這些元件
  • 設定元件的樣式屬性

閱讀這份和其他概念總覽後，您就能更輕鬆地瞭解及使用操作指南、參考說明文件和範例程式碼。

簡報、頁面和頁面元素

Google 簡報中最外層的容器元素是「簡報」。這是可儲存在 Google 雲端硬碟、與其他使用者共用的單位。

每份簡報都包含各種頁面。其中一種頁面是投影片，也就是簡報在螢幕上顯示時，使用者會看到並切換的頁面。

每個網頁都包含許多網頁元素，這些元素共同組成網頁內容，如下圖所示：

簡報架構圖

除了投影片，還有其他類型的頁面可讓您將設計套用至多張投影片，打造一致的外觀。這些其他頁面類型包括母片和版面配置，其屬性會決定投影片的算繪方式，如下圖所示：

主題架構圖

主版：主版有兩個用途。母片上的預留位置包含簡報中使用的文字樣式預設值。主投影片上的背景和其他形狀，會構成以該主投影片為基礎的所有投影片的預設背景。如果想在簡報的每張投影片上顯示公司標誌，請將標誌放在母片上。

版面配置：版面配置範本會決定各類投影片的內容排列方式。如要讓所有標題投影片都採用特定樣式，可以編輯標題版面配置範本。

還有兩種頁面 (備註頁面和備註母片) 主要與演講者備註相關。

API 表示法類型和結構

本節說明 Slides API 如何表示上述 Google 簡報概念模型。

下圖說明簡報、頁面和頁面元素之間的關係，這些都是 Google 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 簡報的圖片。
影片 匯入簡報的影片。
折線圖 視覺線條、曲線或連接器。
資料表 內容格線。
WordArt 視覺文字元素，行為更像形狀。
SheetsChart 從 Google 試算表匯入簡報的圖表。

網頁和網頁元素屬性

透過 Slides API，您可以讀取及更新簡報中網頁和網頁元素的樣式。不同網頁元素支援不同的屬性，可控制網頁元素的顯示方式。

每個網頁元素種類都有對應的屬性元素和屬性更新訊息，例如：

每個網頁元素類型都有相同的元素/屬性/更新要求集：Image/imageProperties/UpdateImageProperties 等等。

您可以在讀取元素時讀取屬性屬性；如要變更其中的值，請將屬性屬性與相符的要求類型搭配使用，做為 batchUpdate 方法的酬載，即可變更簡報中的這些值。

資源種類

在 Google 簡報 API 中，有幾種物件共用某些屬性：

屬性 說明
顏色 Slides API 中的顏色可以是 RGB 值，也可以是主題顏色的參照。主題顏色會以名稱 (例如「DARK1」) 參照，並可使用網頁的色彩配置對應至 RGB 值。在 Google 簡報編輯器中變更簡報主題時，這個色彩配置通常會隨之更新。
填滿 填滿代表物件內空白空間的算繪結果。在 Google 簡報中，最常支援的填滿方式是實心填滿，也就是以單一實心顏色填滿物件內部。填滿功能也可用於頁面的背景。
外框 外框代表圍繞頁面元素的線條組合。線條顏色由「填滿」控制。通話者也可以調整輪廓的寬度和虛線樣式。
陰影 陰影代表的視覺效果，是為了模擬物件投射的實體陰影。目前 Slides API 中的陰影為唯讀。

正在更新屬性

如要更新屬性，請在 batchUpdate 呼叫中使用適當的 Update...Properties 要求，例如 Shapes 的 UpdateShapeProperties。這些要求會接受完整的屬性訊息，並可使用欄位遮罩，判斷應更新屬性訊息中的哪些欄位。

資源繼承

網頁或網頁元素可以沿用父項物件的屬性。物件的屬性 (包括定義和繼承的屬性)，會決定最終的視覺外觀。

  • 頁面屬性：頁面會繼承未定義的屬性，但這些屬性是在頁面所依據的版面配置或母版中定義。
  • 形狀屬性：形狀可以標示為「預留位置」，讓您明確參照另一個預留位置形狀 (位於頁面的父項版面配置或母版上)，並從中沿用屬性。

以下段落將進一步說明這些概念。

頁面屬性繼承

投影片、版面配置和母片的結構會定義簡報中的繼承階層：投影片繼承自版面配置，而版面配置繼承自母片。投影片的父項版面配置和母片是在投影片的slideProperties 欄位中指定。

頁面可以從父項頁面繼承屬性，例如背景和色彩配置。如要沿用屬性，子網頁只要不在 PageProperties 訊息中為該屬性設定值即可。網頁「不會覆寫」父項定義的值，而是接受沿用的值。

下圖顯示從版面配置繼承屬性的投影片，而版面配置則從母片繼承屬性：

沿用投影片屬性

用於顯示投影片的屬性是其定義和繼承的屬性組合。在本範例中，用於算繪投影片 1 的已解析值如下：

  • PropertyA 為「Red」。
  • PropertyB 為「Orange」。

形狀屬性的繼承

形狀可以從其他形狀繼承屬性，例如填滿、外框或陰影。如果設定了形狀的 Shape.placeholder 欄位，該形狀就是預留位置。子項預留位置的 Shape.placeholder.parentObjectId 欄位會識別其父項預留位置。根據版面配置建立新投影片時，該版面配置中的所有預留位置都會在新投影片中顯示為子圖案。同樣地，母版頁面上的預留位置可以做為版面配置預留位置的父項。

定義這個繼承階層後，子網頁只要不在 ShapeProperties 訊息中設定該值，就會繼承屬性。如果未覆寫父項定義的值，子項形狀就會接受沿用的值。

下圖顯示投影片、版面配置和母片中三個預留位置之間的屬性繼承關係：

形狀屬性繼承

用於算繪預留位置形狀的屬性，是其定義和繼承的屬性組合。在本範例中，這些形狀的已解析值如下所示：

  • Placeholder1：屬性 A 會顯示為「黃色」，屬性 B 則顯示為「綠色」。
  • Placeholder2：propertyA 會算繪為「Yellow」，propertyB 則為「Purple」。
  • Placeholder3：propertyA 會算繪為「黃色」，propertyB 則為「紫色」。

只有形狀可以設為頁面元素的父項。其他類型 (例如圖片、表格和圖表) 無法做為預留位置，也無法有父項。

使用 PropertyState「隱藏」屬性

PropertyState 列舉會控管形狀的屬性是否實際用於算繪，或值是否僅供子項形狀沿用。在頁面上算繪形狀時，系統不會使用屬性狀態為 NOT_RENDERED 的屬性，但具有相應屬性狀態 RENDERED 的子項仍可繼承此屬性。

下圖顯示三個預留位置之間的屬性繼承關係，這些預留位置會操控 PropertyState 欄位：

資源狀態和繼承

形狀屬性的算繪作業可能會受到 PropertyState 欄位影響。 在本範例中，這些形狀的已解析值如下所示：

  • Placeholder1：propertyA 會算繪為「Red」。
  • Placeholder2：系統未算繪 propertyA。如果是輪廓屬性，Placeholder2 就沒有輪廓。
  • Placeholder3：propertyA 未算繪。

「The PropertyState」列舉還有一個可能的值：INHERIT 屬性狀態表示屬性狀態本身會沿用，且應使用父項的值。沒有父項的形狀不得具有 INHERIT 屬性狀態。