google-docs

Google Docs の作成

インデックスを計算せず、テキストを検索してください（バグの最大の原因）

Docs の編集では、1 つのタブ内のゼロベースの UTF-16 インデックス範囲を指定します。また、書き込みを行うたびに、それより後のインデックスがすべてずれます。推測したインデックスや古いインデックスを使うと、気づかないうちに誤った段落が対象になります。よくある症状は、2 つのリストが結合され、番号が続いてしまうことです。インデックス計算はツールに任せられます。

• find_text は、完全一致するテキストの最新の {start, end} 範囲を返します。これは apply_text_style、apply_paragraph_style、delete_content、set_paragraph_format で使うインデックスの直接の参照元になります。検索してから編集するまで、続けて呼び出してください。
• create_list は firstItemText／lastItemText アンカーを受け取り、範囲を自動的に解決します。最初と最後の項目の段落を指定すれば、インデックスを扱う必要はありません。リストごとに適切なプリセット（箇条書きには BULLET_、番号付きリストには NUMBERED_）を使って create_list を 1 回呼び出してください。見た目上分かれている 2 つのリストを、1 回の呼び出しでまたがないでください。

範囲をフレーズではなく構造から取得する必要がある場合（段落全体のスタイル設定、表の指定など）は、read_document の要素から読み取ってください。段落の {start, end} が段落レベルのツールに渡す範囲です。END は含まれません。範囲が 1 つ短いと最後の文字が対象外になり、1 つ長いとフレーズの次の文字にスタイルが適用されます（イタリック体やリンクでよくあるオフバイワンの問題です）。

生のインデックスを使わざるを得ない場合は、まず read_document を呼び出し、編集を 1 つだけ計算して、requiredRevisionId を渡して適用し、次の位置指定編集の前にもう一度読み取ってください。複数箇所を位置指定で編集するとき、手順間の再読み込みに時間がかかりすぎる場合は、後ろから前へ（インデックスの大きい順に）処理してください。先にある範囲が有効なまま保たれます。

ドキュメントの作成

create_document は空のドキュメントを作成します（API はコンテンツを無視します）。そのため、次のように計画してください。

• コンテンツがあらかじめ決まっている場合：Markdown を使って google-drive の google_drive_create_file を優先してください（target_mime_type: ...document）。見出し、リスト、表を 1 回の呼び出しでインポートでき、フォルダーも指定できます。
• 少しずつ作成する場合：create_document の後、index を省略して insert_text で各段落を追加します。追加モードでは末尾を自動的に読み取り、リビジョンも自動で保護されます。paragraphStyle で新しい段落のスタイルを設定し、同じ呼び出しで挿入したテキストに bold／italic を適用できるため、適切に構成されたドキュメントをスタイル設定の後処理なしで順に追加できます。
• ドキュメントの作成時には親フォルダーを設定できません。保存先が重要な場合は、作成後に destination_folder_id を指定して google-drive の google_drive_move_or_rename を呼び出してください。

構造は必須です

階層のないドキュメントは、単なるテキストの羅列に見えます。レポート／メモ／ノートを作成するときは、以下を基本構成としてください。TITLE 段落、イタリック体の署名行または日付行、セクションごとの HEADING_2、重要なフレーズを太字にした短い本文段落、列挙には箇条書きを使います。後からスタイルを設定するのではなく、作成時に insert_text の paragraphStyle／bold／italic 引数を使ってください。

スタイル設定

• 文字スタイル（apply_text_style）：太字／斜体／下線／取り消し線、 fontSize、fontFamily、textColor/backgroundColor（#RRGGBB形式）、linkUrl。 終了インデックスは排他的です。末尾の改行を除いた段落全体にスタイルを適用するには、 読み取り時の end - 1 を使います。
• 段落スタイル：名前付きスタイル（TITLE/HEADING_1..6）には apply_paragraph_style、 配置、インデント、行間（パーセント。100 = 1行）には set_paragraph_format を使います。
• リスト：段落の範囲に create_list を適用します。改行で区切られた各段落が1つの項目になります。まず通常の行を挿入してから、箇条書きにします。
• プリセットは正確性の一部です。列挙にはデフォルトで BULLET_* プリセットを使います。NUMBERED_* を使うのは、内容が順序付き（手順、ランキング）である場合、または番号付きにするよう指示された場合のみです。
• 箇条書きにする前に、読み取り結果で先頭に箇条書き記号がすでに表示されている段落がないか確認します。リストの直後に追加したテキストはそのリストの所属を引き継ぎます。そのような段落に対して create_list を適用すると、元のリストが再スタイルされ、番号が続きます（2つ目のリストに4、5、6と表示されます）。先にリストを解除します。新しい段落だけを正確に指定して create_list に remove: true を設定し、その後、目的のプリセットを適用します。

表と画像

• insert_table は空のグリッドを挿入します。入力するには、再読み込みしてセルごとのインデックス範囲を確認し、先にあるセルのインデックスを維持するため、最後のセルから最初のセルの順に insert_text を使います。
• 表のスタイル設定は入力後に行います。read_document の表要素の start を指定します。ヘッダー行には set_table_cell_shading を適用し（塗りつぶし色に対して適切な文字色を選択）、列にまたがるタイトルセルには merge_table_cells を適用します（左上の内容は残り、それ以外は削除されます）。固定幅をポイント単位で指定するには set_table_column_width を使います。結合などの構造編集を行うとインデックスがずれるため、以降のテキスト編集の前に再読み込みしてください。
• insert_image には、誰でも取得できる公開URL（Googleが取得するため、認証が必要な場所やプライベートホストでは失敗します）と、PNG/JPEG/GIF形式の画像が必要です。幅または高さのどちらか一方だけを指定した場合、アスペクト比は維持されます。サイズは幅／高さをポイント単位で指定します。
• insert_page_break は、指定したインデックスで新しいページを開始します。

ヘッダーとフッター

set_header_footer は、1回の呼び出しでデフォルトのヘッダーまたはフッターを設定します。ドキュメントにセグメントがない場合は作成し、既存の場合はテキストを置き換え、空のテキストを指定するとクリアします。テキストは静的です（APIにページ番号フィールドはありません）。最初のタブに適用されます。本文に偽のヘッダーを insert_text で挿入しないでください。コンテンツとともにスクロールしてしまいます。

テキストの一括操作

replace_text はインデックス計算なしで、すべての箇所（または名前付きタブ内）の文字列をそのまま置き換えます。名前の変更や修正には、こちらを優先してください。delete_content は、表の構造やサロゲートペアを分割する範囲を拒否します。段落末尾の改行を削除すると、次の段落と結合されます。

作業の確認

構造とスタイルを確認するには read_document で再読み込みするか、ドキュメント全体をMarkdownとして確認するには google-drive の google_drive_read_file を使います。見た目を確認する必要がある場合は、google_drive_export_file（pdf）を使います。スタイル設定の呼び出し後は、次の作業に進む前に、スタイルが適用された範囲が意図したテキストと正確に一致していることを確認してください。