このページは Cloud Translation API によって翻訳されました。

Google ドキュメントドキュメントの構造

Google Docs API を効果的に使用するには、Google Docs ドキュメントのアーキテクチャとドキュメントを構成する要素、およびそれらの関係を理解する必要があります。このページでは、以下のトピックの概要を説明します。

ドキュメント要素のコンセプトモデル
Docs API によるこれらの要素の表現方法
要素のスタイル設定プロパティ

トップレベル要素

Google ドキュメントで一番外側のコンテナ要素はドキュメントです。このプレゼンテーションを単位として、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 です。段落には複数のテキスト実行を含めることができますが、テキスト実行が段落の境界を越えることはありません。内容は改行文字の後に分割され、個別のテキスト行を形成します。たとえば、次のような小さなドキュメントについて考えてみましょう。

パラグラフと箇条書きリストを含む小さなドキュメント。 — **図 5.** 小さなドキュメント。

次の図は、上のドキュメントの段落の順序を可視化したものです。各段落には独自の TextRun 設定とオプションの Bullet 設定があります。

AutoText

AutoText は、時間の経過とともに変化するコンテンツに動的に置き換えられるテキスト内の場所を表す ParagraphElement です。ドキュメントではページ番号に使用されます

開始インデックスと終了インデックス

ドキュメントのタブのコンテンツを更新すると、各更新はドキュメント内の 1 か所または範囲で行われます。これらの位置と範囲は、包含するドキュメント セグメント内のオフセットを表すインデックスを使用して指定します。セグメントは、構造要素またはコンテンツ要素を含む本文、ヘッダー、フッター、または脚注です。セグメント内の要素のインデックスは、そのセグメントの先頭を基準とします。

本文のコンテンツ内のほとんどの要素には、ゼロベースの startIndex プロパティと endIndex プロパティがあります。要素を含むセグメントの開始点を基準とした、要素の開始位置と終了位置のオフセットを示します。Docs 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 から継承されたデフォルトの書式設定をオーバーライドします。逆に、設定していない書式設定機能は引き続き段落スタイルを継承します。