ページ、ページ要素、プロパティ

Slides API を効果的に使用するには、プレゼンテーションとそのコンポーネントのアーキテクチャと、これらのコンポーネント間のインタラクションを理解する必要があります。このページでは、次のトピックについて詳しく説明します。

プレゼンテーションコンポーネントの概念モデル
API がこれらのコンポーネントをどのように表現するか
コンポーネントのスタイルプロパティ

この概要と他のコンセプトの概要を読むことで、ハウツーガイド、リファレンスドキュメント、レシピのサンプルを理解して使用しやすくなります。

プレゼンテーション、ページ、ページ要素

Google スライドの最も外側のコンテナ要素は、プレゼンテーションです。これは、Google ドライブに保存したり、他のユーザーと共有したりできる単位です。

各プレゼンテーションには、さまざまな種類のページが含まれています。ページの 1 つのタイプはスライドです。これは、プレゼンテーションが画面にレンダリングされたときにユーザーが閲覧し、切り替えるページです。

次の図に示すように、各ページには複数のページ要素が含まれており、それらが組み合わさってページのコンテンツを構成しています。

スライドのアーキテクチャ図

スライド以外にも、さまざまなスライドにデザインを適用して一貫した外観を作成できるページの種類があります。その他のページタイプは、マスターとレイアウトです。次の図に示すように、これらのプロパティによってスライドのレンダリング方法が決まります。

テーマのアーキテクチャ図

マスター - マスターページには 2 つの目的があります。マスターのプレースホルダには、プレゼンテーション全体で使用されるテキストスタイルのデフォルトが含まれています。マスタースライドの背景やその他の図形は、そのマスターに基づくすべてのスライドのデフォルトの背景になります。プレゼンテーションのすべてのスライドに表示したい会社のロゴがある場合は、マスターに配置します。

レイアウト - レイアウトテンプレートは、各種類のスライドでコンテンツをどのように配置するかを決定します。すべてのタイトルスライドを特定の方法で表示したい場合は、タイトルレイアウトテンプレートを編集します。

ノートページとノートマスターという 2 種類のページもありますが、これらは主に発表者ノートを使用する場合に関連します。

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 で定義されているように、ページ要素にはいくつかの種類があります。これらの種類のページ要素については、次の表をご覧ください。

要素の種類	説明
グループ	個々のユニットとして扱われるページ要素のセット。これらは一緒に移動、拡大縮小、回転できます。
図形	長方形、楕円、テキストボックスなどのシンプルな視覚オブジェクト。図形にはテキストを含めることができるため、スライドを作成する際に最もよく使用されるページ要素です。
画像	スライドにインポートされたグラフィック。
動画	スライドにインポートされた動画。
線	視覚的な線、曲線、コネクタ。
テーブル	コンテンツのグリッド。
WordArt	図形のように動作する視覚的なテキスト要素。
SheetsChart	Google スプレッドシートからスライドにインポートされたグラフ。

ページとページ要素のプロパティ

Slides API を使用すると、プレゼンテーションのページとページ要素の外観を読み取って更新できます。ページ要素ごとに、ページ要素のレンダリング方法を制御するさまざまなプロパティがサポートされています。

各ページ要素の種類には、対応するプロパティ要素とプロパティ更新メッセージがあります。次に例を示します。

ページ要素のタイプ Shape があります
プロパティフィールドは shapeProperties です。
これらのプロパティを更新するリクエストは UpdateShapePropertiesRequest です。

各ページ要素タイプ（Image/imageProperties/UpdateImageProperties など）にも、同じ要素/プロパティ/更新リクエストのセットが存在します。

要素の読み取り時にプロパティ属性が見つかった場合は、その属性を読み取ることができます。属性の値を変更するには、一致するリクエストタイプとともに batchUpdate メソッドのペイロードとして使用します。これにより、プレゼンテーションでこれらの値を変更できます。

プロパティの種類

Slides API の複数の種類のオブジェクトに共通するプロパティがいくつかあります。

プロパティ	説明
色	スライド API の色は、RGB 値またはテーマカラーへの参照のいずれかになります。テーマカラーは名前（「DARK1」など）で参照され、ページのカラースキームを使用して RGB 値にマッピングできます。この配色パターンは、スライドエディタでプレゼンテーションのテーマを変更するときに更新されることが一般的です。
塗りつぶし	塗りつぶしは、オブジェクト内の空白スペースのレンダリングを表します。スライドで最も一般的にサポートされている塗りつぶしは、オブジェクトの内部が単一の単色で塗りつぶされる単色塗りつぶしです。塗りつぶしは、ページの背景にも使用できます。
アウトライン	アウトラインは、ページ要素を囲む一連の線を表します。線の色は塗りつぶしで制御されます。発信者はアウトラインの幅と破線スタイルを調整することもできます。
シャドウ	シャドウは、オブジェクトによってできる物理的な影を模倣するための視覚効果を表します。現在、スライド API の影は読み取り専用です。

プロパティの更新

プロパティを更新するには、batchUpdate 呼び出しで適切な Update...Properties リクエストを使用します（例: 図形の場合は UpdateShapeProperties）。これらのリクエストは完全なプロパティメッセージを受け入れ、フィールドマスクを使用して、プロパティメッセージのどのフィールドを更新するかを決定できます。

* のフィールドマスクはワイルドカードとして扱われ、メッセージ内のすべてのフィールドを指定する短縮形です。ワイルドカード構文を使用すると、API が将来更新されたときに望ましくない結果が生じる可能性があります。読み取り専用フィールドと新しく追加されたフィールドが原因でエラーが発生する可能性があるためです。本番環境のアプリケーションでは、更新する特定のフィールドを常にフィールドマスクにリストし、* ワイルドカードの使用は避けてください。

プロパティからの継承

ページまたはページ要素は、親オブジェクトからプロパティを継承できます。オブジェクトのプロパティ（定義されたプロパティと継承されたプロパティを含む）によって、最終的な外観が決まります。

ページのプロパティ - ページは、定義されていないが、ベースとなるレイアウトまたはマスターで定義されているプロパティを継承します。
シェイププロパティ - シェイプをプレースホルダとしてマークし、プロパティを継承する別のプレースホルダシェイプ（ページの親レイアウトまたはマスター）を明示的に参照できます。

これらのアイデアについては、以降の段落で詳しく説明します。

ページプロパティの継承

スライド、レイアウト、マスターの構造は、プレゼンテーション内の継承階層を定義します。スライドはレイアウトから継承し、レイアウトはマスターから継承します。スライドの親レイアウトとマスターは、スライドの slideProperties フィールドで指定されます。

ページは、親ページから背景や配色などのプロパティを継承できます。プロパティを継承するには、子ページで PageProperties メッセージのプロパティの値を設定しないだけです。親で定義された値をオーバーライドしないことで、ページは継承された値を受け入れます。

次の図は、マスターから継承されたレイアウトからプロパティを継承するスライドを示しています。

スライドプロパティの継承

スライドのレンダリングに使用されるプロパティは、定義されたプロパティと継承されたプロパティの組み合わせです。この例では、スライド 1 のレンダリングに使用される解決済みの値は次のとおりです。

PropertyA は「Red」です。
PropertyB は「Orange」です。

形状プロパティの継承

図形は、塗りつぶし、枠線、影などのプロパティを他の図形から継承できます。Shape.placeholder フィールドが設定されている場合、シェイプはプレースホルダです。子プレースホルダの Shape.placeholder.parentObjectId フィールドは、親プレースホルダを識別します。レイアウトに基づいて新しいスライドを作成すると、そのレイアウトのプレースホルダは新しいスライドの子図形として表示されます。同様に、マスターページのプレースホルダは、レイアウトのプレースホルダの親として機能します。

この継承階層が定義されている場合、子ページは ShapeProperties メッセージで値を設定しないことでプロパティを継承します。親で定義された値をオーバーライドしないことで、子シェイプは継承された値を受け入れます。

次の図は、スライド、レイアウト、マスターに含まれる 3 つのプレースホルダ間のプロパティの継承を示しています。

プレースホルダの形状のレンダリングに使用されるプロパティは、定義されたプロパティと継承されたプロパティの組み合わせです。この例では、これらのシェイプの解決された値は次のようになります。

Placeholder1: propertyA は「Yellow」、propertyB は「Green」としてレンダリングされます。
Placeholder2: propertyA は「Yellow」、propertyB は「Purple」としてレンダリングされます。
Placeholder3: propertyA は「黄色」、propertyB は「紫」としてレンダリングされます。

親を持つことができるページ要素は、図形のみです。画像、表、グラフなどの他のタイプはプレースホルダにできず、親を持つこともできません。

PropertyState を使用してプロパティを「非表示」にする

PropertyState 列挙型は、シェイプのプロパティが実際にレンダリングに使用されるかどうか、または値が子シェイプによる継承にのみ使用されるかどうかを制御します。プロパティ状態が NOT_RENDERED のプロパティは、そのページのシェイプをレンダリングする際に使用されませんが、対応するプロパティ状態が RENDERED の子要素は、このプロパティを継承できます。

次の図は、PropertyState フィールドを操作する 3 つのプレースホルダ間のプロパティの継承を示しています。

プロパティの状態と継承

シェイププロパティのレンダリングは、PropertyState フィールドの影響を受ける可能性があります。この例では、これらのシェイプの解決された値は次のようになります。

Placeholder1: propertyA は「Red」としてレンダリングされます。
Placeholder2: propertyA はレンダリングされません。これが outline プロパティの場合、Placeholder2 にはアウトラインがありません。
Placeholder3: propertyA はレンダリングされません。

PropertyState 列挙型には、もう 1 つの値があります。INHERIT プロパティの状態は、プロパティの状態自体が継承され、親の値が使用されることを意味します。親のないシェイプは、プロパティの状態を INHERIT にできません。