Google エディタのインターフェースを構築する

Google Workspace アドオンを使用すると、Google ドキュメント、Google スプレッドシート、Google スライドなどのエディタ内にカスタマイズされたインターフェースを提供できます。これにより、ユーザーに関連性の高い情報を提供したり、タスクを自動化したり、サードパーティシステムをエディタに接続したりできます。

アドオンの UI にアクセスする

Google ドキュメント、Google スプレッドシート、Google スライドのユーザーインターフェースの Google Workspace クイックアクセスサイドパネルにアイコンが表示されている場合、エディタで Google Workspace アドオンを開くことができます。

Google Workspace アドオンは、次のインターフェースを表示できます。

ホームページインターフェース: アドオンのマニフェストに、ユーザーがアドオンを開くエディタのトリガー EDITOR_NAME.homepageTrigger が含まれている場合、アドオンは、そのエディタ専用のホームページカードを構築して返します。アドオンのマニフェストに、ユーザーが開いたエディタの EDITOR_NAME.homepageTrigger が含まれていない場合は、代わりに汎用のホームページカードが表示されます。
REST API インターフェース: アドオンで REST API を使用している場合は、drive.file スコープを使用してドキュメントへのファイル単位のアクセスをリクエストするトリガーを含めることができます。権限が付与されると、EDITOR_NAME.onFileScopeGrantedTrigger という別のトリガーが実行され、ファイル固有のインターフェースが表示されます。
リンクプレビューインターフェース: アドオンがサードパーティサービスと統合されている場合は、サービスの URL からコンテンツをプレビューするカードを作成できます。

Editor アドオンのインターフェースを構築する

次の手順に沿って、エディタ用の Build Editor アドオンインターフェースを構築します。

アドオンスクリプトプロジェクトのマニフェストに、適切な addOns.common、addOns.docs、addOns.sheets、addOns.slides フィールドを追加します。
必要なエディタスコープをスクリプトプロジェクトのマニフェストに追加します。
エディタ固有のホームページを提供する場合は、EDITOR_NAME.homepageTrigger 関数を実装してインターフェースを構築します。そうでない場合は、common.homepageTrigger インターフェースを使用して、ホストアプリの共通のホームページを構築します。
REST API を使用する場合は、drive.file スコープの認可フローと EDITOR_NAME.onFileScopeGrantedTrigger トリガー関数を実装して、開いているファイルに固有のインターフェースを表示します。詳細については、REST API インターフェースをご覧ください。
サードパーティサービスからリンクのプレビューを構成する場合は、https://www.googleapis.com/auth/workspace.linkpreview スコープの認可フローと linkPreviewTriggers 関数を実装します。詳細については、リンクプレビューインターフェースをご覧ください。
ボタンのクリックなど、ユーザーの UI 操作に応答するために必要な関連するコールバック関数を実装します。

エディタのホームページ

アドオンのホームページを構成する単一の Card または Card オブジェクトの配列を構築して返すホームページトリガー関数を、アドオンのスクリプトプロジェクトで指定する必要があります。

ホームページトリガー関数には、クライアントのプラットフォームなどの情報を含むイベントオブジェクトがパラメータとして渡されます。イベントオブジェクトのデータを使用して、ホームページの構成を調整できます。

共通のホームページを表示することも、ユーザーがアドオンを開いたエディタに固有のホームページを表示することもできます。

共通のホームページを表示する

エディタにアドオンの共通ホームページを表示するには、アドオンのマニフェストに、addOns.docs、addOns.sheets、addOns.slides などの適切なエディタフィールドを含めます。

次の例は、Google Workspace アドオンのマニフェストの addons 部分を示しています。このアドオンはドキュメント、スプレッドシート、スライドを拡張し、各ホストアプリに共通のホームページを表示します。

{
 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

エディタ専用のホームページを表示する

エディタ固有のホームページを表示するには、アドオンマニフェストに EDITOR_NAME.homepageTrigger を追加します。

次の例は、Google Workspace アドオンのマニフェストの addons 部分を示しています。アドオンはドキュメント、スプレッドシート、スライドで有効になっています。ドキュメントとスライドには共通のホームページが表示され、スプレッドシートには独自のホームページが表示されます。コールバック関数 onSheetsHomepage は、スプレッドシート固有のホームページカードを構築します。

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

REST API インターフェース

Google Sheets API などの REST API をアドオンで使用している場合は、onFileScopeGrantedTrigger 関数を使用して、エディタホストアプリで開いているファイルに固有の新しいインターフェースを表示できます。

onFileScopeGrantedTrigger 関数を使用するには、drive.file スコープの認証フローを含める必要があります。drive.file スコープをリクエストする方法については、現在のドキュメントのファイルアクセスをリクエストするをご覧ください。

ユーザーが drive.file スコープを付与すると、EDITOR_NAME.onFileScopeGrantedTrigger.runFunction がトリガーされます。トリガーが起動すると、アドオンマニフェストの EDITOR_NAME.onFileScopeGrantedTrigger.runFunction フィールドで指定されたコンテキストトリガー関数が実行されます。

エディタのいずれかの REST API インターフェースを作成するには、次の操作を行います。EDITOR_NAME は、使用するエディタホストアプリ（sheets.onFileScopeGrantedTrigger など）に置き換えます。

マニフェストの適切なエディタセクションに EDITOR_NAME.onFileScopeGrantedTrigger を含めます。たとえば、このインターフェースを Google スプレッドシートで作成する場合は、"sheets" セクションにトリガーを追加します。
EDITOR_NAME.onFileScopeGrantedTrigger セクションで指定された関数を実装します。この関数は、イベントオブジェクトを引数として受け取り、単一の Card オブジェクトまたは Card オブジェクトの配列を返す必要があります。
他のカードと同様に、インターフェースのウィジェットのインタラクティビティを提供するために使用されるコールバック関数を実装する必要があります。たとえば、インターフェースにボタンを含める場合は、ボタンに Action を関連付け、ボタンがクリックされたときに実行されるコールバック関数を実装する必要があります。

次の例は、Google Workspace アドオンマニフェストの addons 部分を示しています。アドオンは REST API を使用するため、Google スプレッドシート用に onFileScopeGrantedTrigger が含まれています。ユーザーが drive.file スコープを付与すると、コールバック関数 onFileScopeGrantedSheets がファイル固有のインターフェースを構築します。

{
  "addOns": {
    "common": {
      "name": "Productivity add-on",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
      "layoutProperties": {
        "primaryColor": "#669df6",
        "secondaryColor": "#ee675c"
      }
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedSheets"
      }
    }
  }
}

サードパーティサービスのリンクプレビューインターフェース

サードパーティサービスのリンクプレビューを有効にするには、アドオンのマニフェストでリンクプレビューを構成し、プレビューカードを返す関数を作成する必要があります。ユーザー認証が必要なサービスの場合、関数は認証フローも呼び出す必要があります。

リンクプレビューをオンにする手順については、スマートチップを使用してリンクをプレビューするをご覧ください。

イベントオブジェクト

イベントオブジェクトが作成され、EDITOR_NAME.homepageTrigger や EDITOR_NAME.onFileScopeGrantedTrigger などのトリガー関数に渡されます。トリガー関数は、イベントオブジェクトの情報を使用して、アドオンカードの作成方法やアドオンの動作の制御方法を決定します。

イベントオブジェクトの完全な構造については、イベントオブジェクトをご覧ください。

エディタがアドオンのホストアプリとして機能している場合、イベントオブジェクトには、クライアント情報を保持する Docs、Sheets、または Slides のイベントオブジェクトフィールドが含まれます。

アドオンに現在のユーザーまたはドキュメントに対する drive.file スコープの承認がない場合、イベントオブジェクトには docs.addonHasFileScopePermission フィールド、sheets.addonHasFileScopePermission フィールド、または slides.addonHasFileScopePermission フィールドのみが含まれます。アドオンに承認がある場合、イベントオブジェクトにはすべてのエディタイベントオブジェクトフィールドが含まれます。

次の例は、sheets.onFileScopeGrantedTrigger 関数に渡されるエディタイベントオブジェクトを示しています。この場合、アドオンは現在のドキュメントに対する drive.file スコープの承認を取得しています。

{
  "commonEventObject": { ... },
  "sheets": {
    "addonHasFileScopePermission": true,
    "id":"A_24Q3CDA23112312ED52",
    "title":"How to get started with Sheets"
  },
  ...
}

Google エディタのインターフェースを構築する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。