スライド API を効果的に使用するには、プレゼンテーションとそのコンポーネントのアーキテクチャ、およびコンポーネント間の相互作用について理解する必要があります。このページでは、これらのトピックについて詳しく説明します。
- プレゼンテーション コンポーネントの概念モデル
- API でこれらのコンポーネントを表す方法
- コンポーネントのスタイル設定のプロパティ
この記事とその他のコンセプトの概要を読んで、入門ガイド、リファレンス ドキュメント、レシピサンプルを理解して使用できるようにします。
プレゼンテーション、ページ、ページ要素
Google スライドの最も外側のコンテナ要素はプレゼンテーションです。これは、Google ドライブに保存したり、他のユーザーと共有したりできる単位です。
各プレゼンテーションには、さまざまな種類のページが含まれています。ページの種類の一つにスライドがあります。スライドは、プレゼンテーションが画面にレンダリングされるときに、ユーザーに表示され、切り替えられるページです。
次の図に示すように、各ページには、複数のページ要素が含まれ、それらが組み合わされてページのコンテンツが構成されます。
スライド以外にも、さまざまなスライドにデザインを適用して、一貫した外観を実現できるページタイプがあります。これら以外のページタイプは「マスター」と「レイアウト」で、そのプロパティによってスライドのレンダリング方法が決まります（次の図を参照）。
マスター - マスターページには 2 つの役割があります。マスターのプレースホルダには、プレゼンテーション全体で使用されるテキスト スタイルのデフォルトが含まれています。マスター スライドの背景やその他のシェイプは、そのマスターに基づくすべてのスライドのデフォルトの背景になります。会社のロゴをプレゼンテーションのすべてのスライドに表示したい場合は、マスターロゴに配置します。
レイアウト - レイアウト テンプレートでは、各タイプのスライドでコンテンツをどのように配置するかを指定します。たとえば、すべてのタイトル スライドの外観を指定したい場合は、タイトル レイアウト テンプレートを編集します。
他にもノートページとノートマスターという 2 種類のページがあります。これらは主にスピーカー ノートの操作に関連するものです。
API の表現タイプと構造
このセクションでは、前述の Google スライドの概念モデルが Slides API でどのように表現されるかについて説明します。
次の図は、Slides 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 で定義されるとおり、ページ要素にはいくつかの種類があります。次の表に、これらの種類のページ要素を示します。
| 要素の種類 | 説明 |
|---|---|
| グループ | 個々の単位として処理されるページ要素のセット。これらは一緒に移動、スケーリング、回転できます。 |
| 形 | 長方形、楕円、テキスト ボックスなどのシンプルな視覚的オブジェクト。シェイプにはテキストを含めることができるため、シェイプはスライドの作成で最もよく使用されるページ要素です。 |
| 画像 | スライドにインポートされたグラフィック。 |
| 動画 | スライドにインポートされた動画。 |
| 線 | 視覚的な直線、曲線、コネクタ。 |
| テーブル | コンテンツのグリッド。 |
| WordArt | シェイプに近い動作をする視覚的テキスト要素。 |
| SheetsChart | Google スプレッドシートからスライドにインポートされたグラフ。 |
ページとページ要素のプロパティ
Slides API を使用すると、プレゼンテーション内のページやページ要素の外観を読み取り、更新できます。ページ要素ごとに、そのレンダリング方法を制御するプロパティは異なります。
それぞれのページ要素の種類には、次のように、対応するプロパティ要素とプロパティ更新メッセージがあります。
- ページ要素タイプに Shape がある
- そのプロパティ フィールドは shapeProperties です。
- これらのプロパティを更新するリクエストは、UpdateShapePropertiesRequest です。
各ページ要素タイプ（Image / imageProperties / UpdateImageProperties など）には、同じ要素、プロパティ、更新リクエストのセットが存在します。
プロパティ属性は、要素の読み取り時にどこででも読み取ることができます。その値を変更するには、batchUpdate メソッドのペイロードとして一致するリクエスト タイプとともに使用すると、プレゼンテーションでこれらの値を変更できます。
プロパティの種類
スライド API のいくつかの種類のオブジェクトに共通するプロパティがいくつかあります。
| プロパティ | 説明 |
|---|---|
| 色 | Slide API の色には、RGB 値またはテーマカラーへの参照のいずれかを指定できます。テーマの色は名前（「DARK1」など）で参照され、ページのカラーパターンを使用して RGB 値にマッピングできます。このカラーパターンは、スライド エディタでプレゼンテーションのテーマを変更すると一般的に更新されます。 |
| 塗りつぶし | 塗りつぶしは、オブジェクト内の空白スペースのレンダリングを表します。スライドで最もよくサポートされている塗りつぶしは、オブジェクトの内部が単色の単色で塗りつぶされる塗りつぶしです。塗りつぶしはページの背景にも使用できます。 |
| 枠線 | 枠線は、ページ要素を囲む線のセットを表します。線の色は塗りつぶしで制御します。呼び出し元は、枠線の幅と破線のスタイルも調整できます。 |
| シャドウ | シャドウは、オブジェクトによって適用される物理的な影を再現するための視覚効果です。現在、Slides API のシャドウは読み取り専用です。 |
プロパティの更新
プロパティを更新するには、batchUpdate 呼び出しで適切な Update...Properties リクエストを使用します（Shapes の場合は UpdateShapeProperties など）。これらのリクエストは、完全なプロパティ メッセージを受け入れます。また、フィールド マスクを使用して、プロパティ メッセージのどのフィールドを更新するかを決定できます。
プロパティから継承
ページまたはページ要素は、親オブジェクトのプロパティを継承できます。最終的な外観は、オブジェクトのプロパティ（定義するもの、継承するものを含む）によって決まります。
- ページ プロパティ - ページは、そのページで定義されていないがレイアウトまたはマスターで定義されているプロパティを継承します。
- シェイプ プロパティ - シェイプをプレースホルダとしてマークすることで、別のプレースホルダ シェイプ（ページの親レイアウトまたはマスター上）を明示的に参照し、そこからプロパティを継承できます。
これらの考え方については、以降の段落で詳しく説明します。
ページ プロパティの継承
スライド、レイアウト、マスターの構造により、プレゼンテーション内の継承階層が定義されます。つまり、スライドはレイアウトを継承し、レイアウトはマスターから継承されます。スライドの親レイアウトとマスターは、スライドの slideProperties フィールドで指定されます。
ページは親ページから背景やカラーパターンなどのプロパティを継承できます。プロパティを継承する場合、子ページの PageProperties メッセージでそのプロパティの値を設定していないだけです。親が定義した値を「オーバーライド」しないと、ページは継承された値を受け入れます。
次の図は、レイアウトからプロパティを継承し、レイアウトがマスターから継承するスライドを示しています。
スライドのレンダリングに使用されるプロパティは、自身で定義したプロパティと継承されるプロパティを組み合わせたものです。この例では、スライド 1 のレンダリングに使用された解決値は次のようになります。
- プロパティ A は「Red」です。
- プロパティ B は「Orange」です。
シェイプ プロパティの継承
シェイプは、塗りつぶし、枠線、シャドウなどのプロパティを他のシェイプから継承できます。Shape.placeholder フィールドが設定されている場合、シェイプはプレースホルダです。親プレースホルダは、子プレースホルダの Shape.placeholder.parentObjectId フィールドで識別されます。レイアウトに基づいて新しいスライドを作成すると、そのレイアウト内のすべてのプレースホルダが、新しいスライドに子シェイプとして表示されます。同様に、マスターページのプレースホルダは、レイアウトのプレースホルダの親として機能します。
この継承階層が定義されているため、子ページは ShapeProperties メッセージで値を設定しないことにより、プロパティを継承します。親が定義した値をオーバーライドしないことにより、子シェイプは継承された値を受け入れます。
次の図は、スライド、レイアウト、マスターに含まれる 3 つのプレースホルダ間のプロパティの継承を示しています。
プレースホルダのシェイプのレンダリングに使用されるプロパティは、定義したプロパティと継承されたプロパティを組み合わせたものです。この例では、これらのシェイプの解決値は次のようになります。
- プレースホルダ 1: プロパティ A は「黄色」、プロパティ B は「緑」でレンダリングされます。
- プレースホルダ 2: プロパティ A は「黄色」、プロパティ B は「紫」でレンダリングされます。
- プレースホルダ 3: プロパティ A は「黄色」、プロパティ B は「紫」でレンダリングされます。
親を持つことができるページ要素のタイプは、シェイプのみです。画像、表、グラフなどの他のタイプはプレースホルダにできず、親を持つこともできません。
PropertyState を使用してプロパティを「非表示」にする
PropertyState 列挙型は、シェイプのプロパティを実際にレンダリングするか、または値を子シェイプによる継承にのみ使用するかを制御します。プロパティ状態が NOT_RENDERED のプロパティは、ページ上のシェイプのレンダリング時には使用されませんが、対応するプロパティ状態が RENDERED の子は引き続きこのプロパティを継承できます。
次の図は、PropertyState フィールドを操作する 3 つのプレースホルダ間のプロパティの継承を示しています。
シェイプ プロパティのレンダリングは、PropertyState フィールドの影響を受ける可能性があります。 この例では、これらのシェイプの解決値は次のようになります。
- プレースホルダ 1: プロパティ A が「赤」でレンダリングされます。
- プレースホルダ 2: プロパティ A はレンダリングされません。これが枠線プロパティである場合、Placeholder 2 には枠線が表示されません。
- プレースホルダ 3: プロパティ A はレンダリングされません。
PropertyState の列挙型の値がもう 1 つあります。INHERIT プロパティの状態は、プロパティの状態自体が継承され、親の値を使用する必要があることを意味します。親のないシェイプのプロパティ状態を INHERIT にすることはできません。