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

Slides API を効果的に使うには、プレゼンテーションとそのコンポーネント、さらにコンポーネント間の相互作用について把握しておく必要があります。このページでは以下のトピックの概要を説明しています。

  • プレゼンテーション コンポーネントの概念モデル
  • API によるコンポーネントの表現方法
  • コンポーネントのスタイリング プロパティ

このページやその他の概念的な説明を読めば、How To ガイドリファレンス ドキュメント説明用のサンプルの内容が理解しやすくなります。

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

Google スライドにおける最も大きなコンテナ要素はプレゼンテーションです。 このプレゼンテーションを単位として、Google Drive への保存や、ユーザー間の共有などが行われます。

各プレゼンテーションには、さまざまなタイプのページが含まれます。 その 1 つがスライドで、これはプレゼンテーションが画面上にレンダリングされた際に表示され、ユーザーによる切り替えが可能なページに相当します。

以下の図のように、各ページには複数のページ要素が含まれており、それらがページ コンテンツを構成しています。

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

スライド以外にもマスターレイアウトというページタイプがあり、これらを使用して異なるスライドにデザインを適用すると、見た目に統一感が出ます。 以下のようにマスターとレイアウトのプロパティによって、スライドのレンダリング方法が決まります。

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

マスター: マスターページには 2 つの役割があります。 マスターのプレースホルダには、プレゼンテーション全体で使用される既定のテキスト スタイルが含まれます。 また、マスター スライドに含まれる背景やその他のシェイプによって、そのマスターをベースとする全スライドの既定の背景が構成されます。 企業ロゴなどをプレゼンテーションの全スライドに表示したい場合は、それをマスターに含めるようにしてください。

レイアウト: レイアウトのテンプレートにより、各種スライド上でのコンテンツの配置方法が決まります。 たとえば、すべてのタイトル スライドの表示形式を指定したい場合は、タイトル レイアウトのテンプレートを編集します。

API の表現形式と構造

このセクションでは、先ほど説明した Google スライドの概念モデルが Slides API でどのように表現されるのかを説明していきます。

以下の図はプレゼンテーション、ページ、ページ要素の関係を Slides API における形式で表現したものです。

erd-style の図

以下のセクションでは、これらを JSON 形式で表す方法について説明します。

プレゼンテーション

プレゼンテーションには多数のプロパティがあります。また、プレゼンテーション内にはページが含まれています。

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { 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) },
  // End of list of possible types for union field properties.
}

ページ要素

ページ要素はページ上に配置される視覚的なコンポーネントです。 Slides 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 で定義されたものを含め、さまざまなページ要素があります。 これらのページ要素を以下の表にまとめています。

要素の種類 説明
グループ 独立した単位として扱われるページ要素一式。 まとめて移動、サイズ変更、回転が可能。
シェイプ 長方形、楕円、テキストボックスなどのシンプルなビジュアル オブジェクト。 シェイプはスライドの作成時に最もよく使用されるページ要素で、中にテキストを含めることもできます。
画像 スライドにインポートされるグラフィック。
動画 スライドにインポートされる動画。
直線、曲線、コネクタ。
コンテンツのグリッド。
ワードアート Shape と同様に機能する装飾文字。
グラフ Google スプレッドシートからインポートするグラフ。

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

Slides API を使用すると、プレゼンテーション内のページやページ要素の外観の読み込み、アップデートが可能です。 ページ要素の種類に応じて、そのレンダリング方法を制御するプロパティは異なります。

各種ページ要素には、次のように、それぞれに対応したプロパティ要素とプロパティの更新メッセージがあります。

同じような要素、プロパティ、アップデート リクエストのセットが他のページ要素にも存在します。たとえば ImageimagePropertiesUpdateImageProperties などです。

要素の読み込み中は、要素の検出箇所にかかわらず、プロパティ属性を読み出すことができます。そのプロパティの値を変更するには、batchUpdate メソッドのペイロードとしてマッチング リクエスト タイプと使用することで、プレゼンテーション内の値を変更できます。

プロパティの種類

Slides API には、異なる種類のオブジェクト間で共通するプロパティがいくつかあります。

プロパティ 説明
Color Slides API では、RGB 値またはテーマ色の参照を色として使用できます。 名前(DARK1 など)によって参照されたテーマ色は、ページのカラー スキームを用いて RGB 値にマッピングされます。 このカラー スキームは通常、スライド エディタにあるプレゼンテーションのテーマ変更時に更新されます。
Fill オブジェクト内部の空白スペースのレンダリングです。 スライドで最も多くサポートされている Fill は、オブジェクトの内部を単色で塗りつぶします。 Fill はページの背景にも使用できます。
Outline ページ要素を囲う一連の外形線です。 線の色は Fill で制御します。 呼び出し元では、外形線の太さと破線のスタイルも調整できます。
Shadow オブジェクトの物理的な影を再現するための視覚効果です。 既存の Slides API は、影の読み込みにのみ対応しています。

プロパティの更新

プロパティを更新するには、batchUpdate 呼び出しの中で、対応する Update...Properties リクエストを使用します。たとえば Shape であれば、UpdateShapeProperties を使用します。 これらのリクエストは、すべてのプロパティ メッセージを受け入れ、フィールド マスクを使用し、更新が必要なプロパティメッセージのフィールドを判別します。

* フィールド マスクはワイルドカードと同様に、メッセージ内のすべてのフィールドを指定する記号として処理されます。

* フィールド マスクは商用版のコードで使用しないでください。読み取り専用のフィールドや新規に追加されたフィールドで、将来的にエラーが発生する可能性があります。

プロパティの継承

ページやページ要素は、その親オブジェクトのプロパティを継承することができます。 最終的な外観は、定義または継承したオブジェクトのプロパティによって決まります。

  • ページ プロパティ: ページでは、そのページで定義されておらず、かつベースとなるレイアウトまたはマスターで定義されている任意のプロパティを継承できます。

  • シェイプ プロパティ: シェイプをプレースホルダとしてマークすると、プロパティの継承元となる別のプレースホルダのシェイプ(そのページの親レイアウトまたはマスターにあるシェイプ)を明示的に参照できます。

上記の内容については、以降のセクションで詳しく説明します。

ページ プロパティの継承

スライド、レイアウト、マスターの構成上、プレゼンテーション内では、スライドはレイアウトを継承し、レイアウトはマスターを継承するという継承階層になっています。スライドの親レイアウトとマスターは、スライドの slideProperties で指定されます。

ページでは、背景カラー スキームなどのプロパティを親ページから継承できます。 プロパティを継承するには、子ページの PageProperties メッセージに含まれるプロパティの値を未設定にします。このように親ページで定義した値をオーバーライドしなければ、その値が子ページに適用されます。

以下の図は、スライドがレイアウトから、レイアウトがマスターからプロパティを継承する仕組みを表しています。

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

スライドのレンダリングに使用されるプロパティは、自身で定義したプロパティと継承したものとの組み合わせになります。上の例の場合、最終的に Slide 1 のレンダリングには次の値が使用されます。

  • Property A は "Red"
  • Property B は "Orange"

シェイプ プロパティの継承

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

このような継承階層が定義されているため、子ページでは、自身の ShapeProperties で値を指定しないことにより、プロパティを継承できます。子シェイプにおいても、親で定義された値をオーバーライドしなければ、継承した値が適用されます。

以下の図は、スライド、レイアウト、マスターのそれぞれに含まれる 3 つのプレースホルダのプロパティの継承関係を表しています。

シェイプ プロパティの継承

プレースホルダのシェイプをレンダリングする際に使われるプロパティは、自身で定義したプロパティと継承したプロパティの組み合わせになります。 上の例の場合、各シェイプの最終的な値は次のようになります。

  • Placeholder 1: Property A は "Yellow" で、property B は "Green" でレンダリングされる。
  • Placeholder 2: Property A は "Yellow" で、property B は "Purple" でレンダリングされる。
  • Placeholder 3: Property A は "Yellow" で、property B は "Purple" でレンダリングされる。

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

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

PropertyState 列挙型を使うと、シェイプのプロパティを実際にレンダリングに使用するのか、または子シェイプによる継承のためだけに使用するのかを管理できます。プロパティ状態が NOT_RENDERED に指定されているプロパティは、そのページ上のシェイプをレンダリングする際に使用されません。ただし、子において対応するプロパティ状態が RENDERED の場合は、そのプロパティを継承することができます。

以下の図は、PropertyState フィールドを扱う 3 つのプレースホルダ間におけるプロパティの継承関係を表しています。

プロパティ状態と継承

PropertyState フィールドは、シェイプ プロパティのレンダリングに影響を及ぼす場合があります。 上の例の場合、各シェイプの最終的な値は次のようになります。

  • Placeholder 1: Property A は "Red" でレンダリングされる。
  • Placeholder 2: Property A はレンダリングされない。 これが外形線のプロパティである場合は、Placeholder 2 に外形線は表示されません。
  • Placeholder 3: Property A はレンダリングされない。

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

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。