Google Docs API を効果的に使用するには、Google ドキュメントのアーキテクチャと、ドキュメントを構成する要素、およびそれらの関係を理解する必要があります。このページでは、次のトピックについて詳しく説明します。
- ドキュメント要素の概念モデル
- Docs API がこれらの要素をどのように表現するか
- 要素のスタイル設定プロパティ
トップレベル要素
Google ドキュメントの最も外側のコンテナ要素は document です。これは、Google ドライブに保存したり、他のユーザーと共有したり、テキストや画像で更新したりできる単位です。
documents リソースの最上位要素には、Tab、SuggestionsViewMode、その他の属性が含まれます。
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
タブ
1 つのドキュメントに複数のタブを含めることができます。各タブには異なるテキストレベルのコンテンツが含まれます。ドキュメントの tabs プロパティは、Tab オブジェクトのシーケンスです。Tab は次のフィールドで構成されます。
TabProperties: ID、タイトル、インデックスなどのタブの属性が含まれます。childTabs: タブの子タブ（直下にネストされているタブ）を公開します。DocumentTab: タブのテキスト コンテンツを表します。
以降のセクションでは、ドキュメント タブの階層の概要を説明します。タブの JSON 表現でも、詳細な情報を提供しています。タブ機能の詳細については、タブを使用するをご覧ください。
Body コンテンツの外部でグローバル ドキュメント タブの機能を操作するには、1 つ以上のドキュメント テンプレートを使用する方がほぼ常に適しています。これらのテンプレートは、新しいドキュメントをプログラムで生成するための基盤として使用できます。詳しくは、ドキュメントにテキストを差し込むをご覧ください。
本文コンテンツ
通常、Body にはドキュメントのタブのすべての内容が含まれます。プログラムで利用できる、または利用したいと思われるアイテムのほとんどは、Body コンテンツ内の要素です。
構造要素
StructuralElement は、ドキュメントの構造を提供するコンテンツを記述します。Body コンテンツは StructuralElement オブジェクトのシーケンスです。コンテンツ要素は、次の図に示すように、各 StructuralElement オブジェクトをパーソナライズします。
構造要素とそのコンテンツ オブジェクトには、ドキュメント内のすべての視覚コンポーネントが含まれています。これには、テキスト、インライン画像、書式設定が含まれます。
段落の構造
Paragraph は、段落を表す StructuralElement です。改行文字で終了するコンテンツの範囲があります。次のオブジェクトで構成されています。
ParagraphElement: 段落内のコンテンツを説明します。ParagraphStyle: 段落のスタイル プロパティを明示的に設定する要素（任意）。Bullet: 段落がリストの一部である場合、箇条書きの仕様を提供する省略可能な要素。
ParagraphElement は StructuralElement のような働きをします。コンテンツ要素タイプ（ColumnBreak や Equation など）のセットは、次の図に示すように、独自の ParagraphElement をパーソナライズします。
完全なドキュメント構造の例については、JSON 形式のドキュメントの例をご覧ください。出力には、多くの主要な構造要素とコンテンツ要素が表示されます。また、次のセクションで説明する開始インデックスと終了インデックスの使用も確認できます。
テキスト実行
TextRun は、すべて同じテキスト スタイルで連続するテキスト文字列を表す ParagraphElement です。1 つの段落に複数のテキスト実行を含めることができますが、テキスト実行が段落の境界を越えることはありません。内容は改行文字の後に分割され、個別のテキスト実行が形成されます。たとえば、次のような小さなドキュメントを考えてみましょう。
次の図は、前のドキュメントの段落のシーケンスを視覚化する方法を示しています。各段落には独自の TextRun とオプションの Bullet 設定があります。
AutoText
AutoText は、時間とともに変化するコンテンツで動的に置き換えられるテキスト内のスポットを表す ParagraphElement です。ドキュメントでは、これはページ番号に使用されます。
開始インデックスと終了インデックス
ドキュメントのタブのコンテンツを更新すると、各更新はドキュメント内の特定の場所または範囲で行われます。これらの位置と範囲は、包含ドキュメントのセグメント内のオフセットを表すインデックスを使用して指定されます。セグメントは、構造要素またはコンテンツ要素を含む本文、ヘッダー、フッター、脚注です。セグメント内の要素のインデックスは、そのセグメントの先頭を基準としています。
本文コンテンツ内のほとんどの要素には、ゼロベースの startIndex プロパティと endIndex プロパティがあります。これらは、要素の開始と終了のオフセットを、囲んでいるセグメントの開始を基準として示します。Docs API 呼び出しのバッチ処理の順序付けについて詳しくは、バッチ更新をご覧ください。
インデックスは UTF-16 コード単位で測定されます。つまり、サロゲートペアは 2 つのインデックスを消費します。たとえば、「GRINNING FACE」の絵文字 😄 は \uD83D\uDE00 として表され、2 つのインデックスを使用します。
ドキュメント本文内の要素の場合、インデックスは本文コンテンツの先頭（「ルート」要素）からのオフセットを表します。
構造要素の「パーソナライズ」タイプ（SectionBreak、TableOfContents、Table、Paragraph）には、これらのインデックスがありません。これは、囲み StructuralElement にこれらのフィールドがあるためです。これは、ParagraphElement に含まれるパーソナライズ タイプ（TextRun、AutoText、PageBreak など）にも当てはまります。
要素にアクセスする
多くの要素は documents.batchUpdate メソッドで変更できます。たとえば、InsertTextRequest を使用して、テキストを含む要素のコンテンツを変更できます。同様に、UpdateTextStyleRequest を使用して、1 つ以上の要素に含まれるテキストの範囲に書式を適用できます。
ドキュメントの要素を読み取るには、documents.get メソッドを使用して、ドキュメント全体の JSON ダンプを取得します。その後、結果の JSON を解析して、個々の要素の値を見つけることができます。詳細については、ドキュメントの内容を JSON として出力するをご覧ください。
コンテンツの解析は、さまざまなユースケースで役立ちます。たとえば、検出したドキュメントを一覧表示するドキュメント カタログ アプリケーションを考えてみましょう。このアプリは、次の図に示すように、ドキュメントのタブのタイトル、リビジョン ID、開始ページ番号を抽出できます。
これらの設定を明示的に読み取るメソッドはないため、アプリはドキュメント全体を取得し、JSON を解析してこれらの値を抽出する必要があります。
プロパティからの継承
StructuralElement は親オブジェクトからプロパティを継承できます。オブジェクトのプロパティ（定義されたプロパティと継承されたプロパティを含む）によって、最終的な外観が決まります。
テキスト文字の書式設定では、ドキュメント内のテキストのレンダリング方法（太字、斜体、下線など）を指定します。適用した書式設定は、基になる段落の TextStyle から継承されたデフォルトの書式設定よりも優先されます。逆に、書式設定を行わない文字は、段落のスタイルを継承し続けます。
段落の書式設定では、配置、枠線、インデントなど、ドキュメント内のテキスト ブロックのレンダリング方法を指定します。適用した書式設定は、基盤となる ParagraphStyle から継承されたデフォルトの書式設定をオーバーライドします。逆に、設定しない書式設定機能は、段落スタイルから引き続き継承されます。