Google ドキュメントの拡張

Google Apps Script を使用すると、Google ドキュメントをプログラムで作成、変更できるだけでなく、新しいメニュー、ダイアログ ボックス、サイドバーを使用してユーザー インターフェースをカスタマイズすることもできます。

基本情報

Apps Script は、Google ドキュメントと大きく 2 つの方法でやり取りできます。スクリプトのユーザーにドキュメントに対する適切な権限がある場合、任意のスクリプトでドキュメントを作成または変更できます。また、スクリプトをドキュメントにバインドすることもできます。これにより、スクリプトでユーザー インターフェースを変更したり、ドキュメントを開いたときに応答したりできます。Google ドキュメント内からコンテナにバインドされたスクリプトを作成するには、[拡張機能] > [Apps Script] をクリックします。

どちらの場合も、次の例に示すように、Apps Script の Document Service を介して Google ドキュメント ドキュメントを簡単に操作できます。

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

上記のスクリプトは、ユーザーの Google ドライブに新しいドキュメントを作成し、ID t.0 のタブ（デフォルトの最初のタブ）を取得し、ドキュメントの名前と同じテキストを含む段落を挿入して、その段落にヘッダーのスタイルを設定し、2 次元配列の値に基づいて表を追加します。スクリプトでは、DocumentApp.create() の呼び出しを DocumentApp.openById() または openByUrl() に置き換えることで、既存のドキュメントにも同様に変更を加えることができます。ドキュメント内で作成されたスクリプト（コンテナにバインドされたスクリプト）の場合は、DocumentApp.getActiveDocument() と Document.getActiveTab() を使用します。

ドキュメントの構造

Apps Script の観点からは、Google ドキュメント ドキュメントは HTML ドキュメントとよく似ています。つまり、ドキュメントは 1 つ以上の Tab オブジェクトで構成されており、各オブジェクトには、多くの場合、他の要素を含む要素（Paragraph や Table など）が含まれています。Google ドキュメントのドキュメントを変更するほとんどのスクリプトは、getTab() と asDocumentTab() の呼び出しで始まり、その後に getBody() が続きます。これは、Body がコア要素であり、HeaderSection、FooterSection、Footnotes を除くタブ内の他のすべての要素が含まれているためです。

ただし、どのタイプの要素に他のタイプを含めることができるかについてはルールがあります。さらに、Apps Script の Document Service では、特定のタイプの要素のみを他の要素に挿入できます。次のツリーは、特定のタイプの要素に含めることができる要素を示しています。

太字で表示されている要素は挿入できますが、太字以外の要素は現地でのみ操作できます。

テキストを置き換えています

Apps Script は、Google ドキュメント内のテキストの置換によく使用されます。たとえば、クライアント情報を含むスプレッドシートがあり、クライアントごとにパーソナライズされた Google ドキュメントを生成するとします。（このタイプのオペレーションは、メールの統合とも呼ばれます）。

テキストを置き換える方法はいくつかありますが、最も簡単なのは、以下の例に示す replaceText() メソッドです。replaceText は、JavaScript の正規表現機能のほとんどをサポートしています。以下の最初の関数は、Google ドキュメントにプレースホルダ テキストを数行追加します。実際は、プレースホルダを自分でドキュメントに入力することになります。2 番目の関数は、プレースホルダを client オブジェクトで定義されたプロパティに置き換えます。

どちらの関数も getActiveDocument() メソッドと getActiveTab() メソッドを使用します。これらは Google ドキュメント ドキュメント内で作成されたスクリプトにのみ適用されます。スタンドアロン スクリプトの場合は、DocumentApp.create()、openById()、または openByUrl() を Document.getTab() と組み合わせて使用します。

プレースホルダを追加する

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

プレースホルダを置き換える

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

カスタム メニューとユーザー インターフェース

Google ドキュメントをカスタマイズするには、メニュー、ダイアログ ボックス、サイドバーを追加します。ただし、スクリプトが操作できるのは、開いているドキュメントの現在のインスタンスの UI のみであり、スクリプトがドキュメントにバインドされている場合に限られます。

Google ドキュメントにカスタム メニューとダイアログを追加する方法をご覧ください。ダイアログまたはサイドバーのカスタム インターフェースの作成の詳細については、HTML Service のガイドをご覧ください。カスタム インターフェースをアドオンの一部として公開する場合は、スタイルガイドに沿って、Google ドキュメント エディタのスタイルとレイアウトと整合させます。

Google ドキュメント用アドオン

アドオンは Google ドキュメント内で実行され、Google ドキュメント アドオンストアからインストールできます。Google ドキュメント用のスクリプトを開発して他のユーザーと共有する場合は、Apps Script でスクリプトをアドオンとして公開して、他のユーザーがアドオンストアからインストールできるようにします。

Google ドキュメントのアドオンを作成する方法については、ドキュメント アドオンの作成に関するクイックスタートをご覧ください。

トリガー

Google ドキュメントにバインドされたスクリプトでは、シンプルなトリガーを使用して、ドキュメントの onOpen イベントに応答できます。このイベントは、ドキュメントへの編集権限を持つユーザーが Google ドキュメントでドキュメントを開くたびに発生します。

トリガーを設定するには、onOpen() という関数を作成します。このトリガーの例については、Google Workspace のカスタム メニューをご覧ください。シンプルなトリガーはメニューの追加に便利ですが、承認が必要な Apps Script サービスは使用できません。