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

このガイドでは、Google ドキュメントのドキュメントの内部構造、つまりドキュメントを構成する要素とその要素の関係について説明します。

トップレベル要素

ドキュメントの最上位要素には、本文と、ドキュメント全体のその他の属性が含まれます。

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

本文コンテンツの外部にあるグローバル ドキュメント機能を操作するには、ほとんどの場合、1 つ以上のドキュメント テンプレートを使用することをおすすめします。これにより、新しいドキュメントをプログラムで生成できます。

本文

プログラムで使用できるアイテムのほとんど(今後使用する可能性があるアイテム)は、本文コンテンツ内の要素です。

本文コンテンツの図。

構造要素

本文のコンテンツは、単なる StructuralElement オブジェクトのシーケンスです。次の図に示すように、コンテンツ要素は各 StructuralElement オブジェクトをパーソナライズします。

構成要素の図。

構造要素とそのコンテンツ オブジェクトには、ドキュメントのすべてのテキストやインライン画像などが含まれます。

段落には ParagraphElement という特別なタイプの要素があり、StructuralElement のように動作します。次の図に示すように、コンテンツ要素のタイプのセットによって、それぞれ独自の ParagraphElement がパーソナライズされます。

段落要素の図。

完全なドキュメント構造の例については、JSON 形式のドキュメントのサンプルダンプをご覧ください。出力には、重要な構造的要素とコンテンツ要素の多く、および開始インデックスと終了インデックスの使用方法が示されています(次のセクションを参照)。

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

本文コンテンツ内のほとんどの要素には、startIndex プロパティと endIndex プロパティがあります。これらは、要素を含むセグメントの先頭から相対的な、要素の開始位置と終了位置のオフセットを示します。

インデックスは UTF-16 コード単位で測定されます。つまり、サロゲートペアは 2 つのインデックスを使用します。たとえば、「笑顔」の絵文字 Spanner は「\uD83D\uDE00」と表現され、2 つのインデックスを使用します。

ドキュメント本文内の要素の場合、インデックスは本文コンテンツの先頭(ルート要素)からのオフセットを表します。

構造要素(SectionBreakTableOfContentsTableParagraph)の「パーソナライズ」タイプには、これらのインデックスがありません。包含する StructuralElement にこれらのフィールドがあるためです。これは、ParagraphElement に含まれるパーソナライズ タイプにも当てはまります。

段落構造

段落は以下のものから構成されます。

  • elements - textRun の 1 つ以上のインスタンスを含むシーケンス。
  • paragraphStyle - 段落のスタイル プロパティを明示的に設定する要素(省略可)。
  • bullet - 段落がリストの一部である場合に、箇条書きを指定する要素(省略可)。

テキスト実行

textRun は、すべて同じテキスト スタイルを持つ連続したテキスト文字列を表します。段落には複数のテキスト実行を含めることができますが、テキスト実行は段落の境界をまたぐことはできません。たとえば、次のような小さなドキュメントについて考えてみましょう。

次の図は、上記のドキュメントの段落の順序を視覚化する方法を示しています。各段落には、それぞれ独自のテキスト実行とオプションで箇条書きの設定があります。

テキスト実行の図。

要素にアクセスする

多くの要素は、BatchUpdate メソッドを使用して変更できます。たとえば、InsertTextRequest リクエスト タイプを使用すると、テキストを含む任意の要素のコンテンツを変更できます。同様に、UpdateTextStyleRequest を使用すると、1 つ以上の要素に含まれるテキストの範囲に書式を適用できます。

ドキュメントの要素を読み取るには、get メソッドを使用して、ドキュメント全体の JSON ダンプを取得します。(これを行う方法については、出力ドキュメントの内容を JSON として出力するサンプルをご覧ください)。生成された JSON を解析して個々の要素の値を特定できます。

コンテンツの解析は、さまざまなユースケースで役立ちます。たとえば、アプリが検出したドキュメントをリストするドキュメントをカタログ化しているとします。このアプリで、次の図に示すように、ドキュメントのタイトル、リビジョン ID、開始ページ番号を抽出する場合があります。

ドキュメント カタログ アプリの図。

これらの設定を明示的に読み取るメソッドはないため、アプリでドキュメント全体を取得してから、JSON を解析してこれらの値を抽出する必要があります。