Google ドキュメント API を効果的に使用するには、Google ドキュメント ドキュメントのアーキテクチャ、ドキュメントを構成する要素、それらの関係について理解する必要があります。このページでは、これらのトピックについて詳しく説明します。
- ドキュメント要素の概念モデル
- ドキュメント API によるこれらの要素の表示
- 要素のスタイル設定プロパティ
トップレベル要素
Google ドキュメントの最も外側のコンテナ要素はドキュメントです。この単位を Google ドライブに保存して、他のユーザーと共有し、テキストや画像で更新できます。
documents リソースの最上位要素には、Body、Header、Footer など、複数の属性があります。
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Body コンテンツの外部でグローバル ドキュメント機能を操作するには、ほとんどの場合、1 つ以上のドキュメント テンプレートを使用することをおすすめします。テンプレートは、プログラムで新しいドキュメントを生成するために使用できます。詳しくは、テキストをドキュメントに結合するをご覧ください。
本文
Body には通常、ドキュメントの全コンテンツが含まれます。プログラムで使用できる、または使用する可能性が高いアイテムのほとんどは、Body コンテンツ内の要素です。
構造要素
StructuralElement は、ドキュメントに構造を提供するコンテンツを記述します。Body コンテンツは、StructuralElement オブジェクトのシーケンスです。次の図に示すように、コンテンツ要素は各 StructuralElement オブジェクトをパーソナライズします。
構造要素とそのコンテンツ オブジェクトには、ドキュメント内のすべての視覚的コンポーネントが含まれています。これには、テキスト、インライン画像、書式設定が含まれます。
段落構造
Paragraph は、段落を表す StructuralElement です。改行文字で終わるさまざまなコンテンツがあります。これは、次のオブジェクトで構成されます。
ParagraphElement: 段落内のコンテンツを記述します。ParagraphStyle: 段落のスタイル プロパティを明示的に設定する省略可能な要素。Bullet: 段落がリストの一部である場合、箇条書きの仕様を提供するオプション要素。
ParagraphElement は StructuralElement のように機能します。次の図に示すように、一連のコンテンツ要素タイプ（ColumnBreak や Equation など）は、独自の ParagraphElement をパーソナライズします。
完全なドキュメント構造の例については、JSON 形式のドキュメントの例をご覧ください。出力では、主要な構造要素とコンテンツ要素の多くを確認できます。また、次のセクションで説明するように、開始インデックスと終了インデックスの使用も確認できます。
テキスト実行
TextRun は、すべて同じテキスト スタイルが適用された、連続したテキスト文字列を表す ParagraphElement です。段落には複数のテキスト実行を含めることができますが、テキスト実行は段落の境界を越えません。コンテンツは改行文字の後で分割され、別々のテキストの実行が形成されます。たとえば、次のような小さなドキュメントについて考えてみましょう。
次の図は、前のドキュメントの段落のシーケンスを可視化する方法を示しています。各段落には独自の TextRun 設定とオプションの Bullet 設定があります。
AutoText
AutoText は、テキスト内の場所を表す ParagraphElement です。この部分は、時間の経過とともに変化する可能性のあるコンテンツによって動的に置き換えられます。ドキュメントでは、ページ番号に使用されます。
開始インデックスと終了インデックス
ドキュメントのコンテンツを更新すると、ドキュメント内の特定の場所または範囲内で更新が行われます。これらの場所と範囲は、含まれるドキュメントのセグメント内のオフセットを表すインデックスを使用して指定されます。セグメントとは、構造要素やコンテンツ要素を含む本文、ヘッダー、フッター、脚注のことです。セグメント内の要素のインデックスは、そのセグメントの先頭を基準とします。
本文コンテンツ内のほとんどの要素には、ゼロベースの startIndex プロパティと endIndex プロパティがあります。要素を含むセグメントの開始からの相対的な開始位置と終了位置のオフセットを示します。ドキュメント API の一括呼び出しの順序付けについて詳しくは、一括更新をご覧ください。
インデックスは UTF-16 コード単位で測定されます。つまりサロゲートペアは
2 つのインデックスを消費しますたとえば、「笑顔」の絵文字 が大きい と、\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 から継承されたデフォルトの書式をオーバーライドします。逆に、設定していない書式設定機能は、その段落スタイルを継承します。