google-slides

Google Slides の作成

座標はスライドの左上を基準とするポイント単位です。標準的なスライドのサイズは 720x405 です （実際のサイズは read_slide_layout で確認できます）。すべてのオブジェクトは read_presentation で取得した objectId で指定します。最新の読み取りまたは書き込みから requiredRevisionId を渡すことで、同時編集があった場合にデータを破損させず、書き込みが失敗します。

新しいデッキの作成：構成してから確認

各スライドは座標ではなくレイアウトとして記述します。compose_slide は ツリー（スタック、グリッド、カード、テキスト、画像）または HTML/CSS のサブセットを受け取り、 スライド全体を 1 回の呼び出しでレイアウトします。同じ階層の要素は同じサイズになり、ガターは均等で、 垂直方向の中央揃えやコントラストのペアも設計上保たれます。テキストには fit: "shrink" を指定でき、応答には各要素のボックスとプランに対する lint 結果が含まれます。各スライドで：

1. add_slide でレイアウトを BLANK に設定します（または、デッキの最初のスライドで clear: true を指定します）。その後、 毎回同じ theme を使って compose_slide を呼び出します（パレットの役割 background/surface/primary/textSecondary とフォントファミリーを指定します）。 ツリー内の色は 16 進数ではなく役割で指定するため、テーマを 1 か所変更するだけでデッキ全体のスタイルを変更できます。
2. 応答の issues を確認します。text_overflow はテキストを短くする、fit: "shrink" を指定する、またはノードにより大きな size を割り当てる必要があることを意味します。overlap は 2 つのノードが同じボックスを共有していることを意味します（通常は gap が必要な行です）。
3. スライドごとに 1 回 get_slide_thumbnail（LARGE）を実行し、サムネイルを確認します。要素が密集していないか、隅に無駄な空間がないか、タイトルが本文のように見えないか、画像がパレットと競合していないかを見ます。修正するにはスライドを再構成します（古い要素を先に削除するか、新しい BLANK スライドに構成してから古い要素を delete_object で削除します）。

ツリーのレシピ（ルートはカラム。ルートのボックスはスライドから 48 pt の余白を除いた範囲です）：

• タイトルスライド：stack column justify:center に display テキストと、textSecondary の h2 サブタイトルを配置し、どちらも align:center にします。
• KPI カード：h1 の下に、stack row size:150 gap:24 を配置し、card を並べます。それぞれに caption ラベル（textSecondary）とその下の kpi 値を含めます。
• テキスト＋画像：stack row gap:32 に body テキスト（bullets:true、size:{flex:1}）と image（size:{flex:1}）を配置します。画像はアスペクト比を保ってサイズ調整されます。
• アジェンダ：改行で項目を区切った 1 つの body テキストに bullets:true を指定します。

同じ結果を得られる HTML 形式の例：<section style="background:#0B2A4A; padding:48pt; gap:24pt"> の中に <h1>、<div style="display:flex; gap:24pt; height:150pt"> を配置し、その中に <article class="card"><span class="caption">…</span><span class="kpi">…</span></article>、箇条書き用の <ul><li>、<img style="flex:1"> を配置します。 コンパイルされるのはドキュメントに記載されたタグとプロパティのみです。それ以外は破棄されず、名前を示して拒否されます。

既存のデッキの編集：配置、確認、修正、表示

すでにコンテンツがあるデッキや、ツリーで表現できない要素を扱う場合：

1. カード、テキスト、画像の行、列、グリッドには insert_grid を使います（1 回の呼び出しで整列し、サイズを均等にします）。単独の要素には insert_text_box / insert_shape / insert_image を使います。
2. read_slide_layout で、各要素のボックス、z-order、テキストスタイル、折り返し後の推定高さ（textFit.fits）、issues を確認します。すべての error と warn（text_overflow、overlap、off_slide、 テキストの背後に実際にある塗りつぶしの色が示される low_contrast）を修正します。また、手間がかからない場合は info 項目（near_miss_alignment、unequal_peers、 tight_margin、empty_placeholder）も修正します。
3. lint の問題がなくなったら、get_slide_thumbnail を 1 回実行して表示を確認します。

グリッドの慣例（手動で配置する場合）

タイトルは x 40、y 32、幅 640、高さ 60～70 とし、28～34 pt の 1 行で配置します（2 行の場合は約 110 が必要です）。その下に 16～18 pt のサブタイトルを置きます。コンテンツ領域は x 40、y 130、640 x 235 です（insert_grid のデフォルト）。フッターは y 370、12 pt にします。要素を意図的に全面表示にする場合を除き、左右に 40 pt の余白を保ちます。プロセスフローでは、ステップの図形を insert_grid（列数はステップ数）で配置してから、隣り合う図形を connect_shapes で接続します。コネクタは図形を移動すると追従します。

34 pt の太字タイトルは、幅 600 pt のボックスでは約 32 文字を超えると折り返され、その下の要素に重なります（API はボックスを自動で拡大しません）。レイアウト読み取りの textFit と compose の応答に含まれる issues でこれを予測できます。長いタイトルには 24～28 pt を指定するか、fit: "shrink" を使うか、2 行にしてサブタイトルを下にずらします。

配色とコントラスト

最初に配色を選び、すべてのスライドで（compose_slide の theme.palette として）再利用します。背景色、カード／サーフェスの色を1色、アクセントカラーを1色、セカンダリテキストの色を1色選びます。上に載せる色は自動的に導出されます。ユーザーがテンプレートやブランドを指定した場合は、その色を使います。それ以外の場合は、次の組み合わせであればそのまま WCAG AA に準拠します。

• ダーク：背景 #0B2A4A、カード #1E4976、アクセント #4FC3F7、タイトル／テキスト #FFFFFF、セカンダリ #B8CCE0。
• ライト：背景 #FFFFFF、カード #F1F3F4、アクセント #0B57D0（その上のテキストは白）、 テキスト #202124、セカンダリ #444746。

色付きの塗りつぶし上では、テキストの色が適切に初期設定されるとは限りません。テキストを含む各要素では、テキストの背後にある塗りつぶし（スライドの塗りつぶしではなく、カードの塗りつぶし）に対して色を選びます。中間色のグレーを中間色の背景に使わないでください。白の上では、セカンダリテキストに #444746 以上に暗い色を使います（#5F6368 はぎりぎりで、それより明るい色は不適合です）。テンプレートやブランドの配色を使う場合は、作成前に使用予定のテキストと塗りつぶしの組み合わせすべてに対して check_contrast を実行します（不適合な組み合わせごとに、適合する色合いまたは濃淡が返されます）。レイアウトの読み取りにある low_contrast は、その後の確認に使います。

色付きのスライド上の表は、テーマの塗りつぶしによって暗い色同士で表示されます。すべてのセルに set_table_cell_fill を適用し（明るい塗りつぶし＋暗いテキスト、またはアクセントカラー＋白）、set_text_style（cellRow/cellColumn）でスタイルを整えます。タイトルスライドやまとめスライドでは、数値を並べたグリッドよりも統計カードを優先します。表は、本当に表形式のデータにのみ使い、ヘッダー行はアクセントカラーで塗りつぶし、行数は少数に抑えます。

スライドと繰り返し

• create_presentation は空白のスライドを1枚作成します（プレースホルダーを削除するか、set_shape_text で内容を入れます）。フォルダーを指定できないため、作成後に google-drive の google_drive_move_or_rename で移動します。
• 定義済みレイアウトを指定した add_slide は、同じ呼び出しでタイトルと本文のプレースホルダーを埋めます（テーマに一貫性のあるスライドを最も速く作成できます）。move_slide で順序を変更します。
• レイアウトを繰り返す場合（1つのテンプレートから N 個のバリエーションを作成）：最初のスライドを完成させてから、バリエーションごとにスライド ID に対して duplicate_object を実行します（コピーは元のスライドの直後に作成されます）。続けて pageObjectIds の範囲をコピーに限定して replace_text を実行します。{{TITLE}} のような個別のプレースホルダーを使うと、置換対象が明確になります。
• set_shape_text は図形またはセルのテキスト全体を置き換えます（セルは {rowIndex, columnIndex}）。set_text_style は範囲ではなく、図形またはセル全体のスタイルを変更します。update_element_position は移動のみで、サイズは変更しません。適切なサイズで作り直すには、削除して再作成します。
• 発表者ノート：read_presentation から取得したスライドの notesPageId を pageObjectId に、speakerNotesObjectId を objectId に指定して set_shape_text を実行します。
• デッキ全体のレンダリング：google-drive の google_drive_export_file（pdf）。