Google エディタのインターフェースを作成する

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

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

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

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

  • ホームページのインターフェース: アドオンのマニフェストに、ユーザーがアドオンを開いたエディタのトリガー EDITOR_NAME.homepageTrigger が含まれている場合、アドオンはそのエディタ専用のホームページ カードをビルドして返します。アドオンのマニフェストにユーザーが開いたエディタの EDITOR_NAME.homepageTrigger が含まれていない場合は、代わりに汎用のホームページ カードが表示されます。

  • REST API インターフェース: アドオンが REST API を使用する場合は、drive.file スコープを使用して、ドキュメントへのファイルごとのアクセスをリクエストするトリガーを含めることができます。権限が付与されると、EDITOR_NAME.onFileScopeGrantedTrigger という別のトリガーが実行され、ファイルに固有のインターフェースが表示されます。

  • プレビュー インターフェースをリンクする: アドオンをサードパーティ サービスと統合する場合は、サービスの URL からコンテンツをプレビューするカードを作成できます。

エディタ アドオンのインターフェースの構築

エディタ用のエディタ アドオン インターフェースをビルドする手順は次のとおりです。

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

エディタのホームページ

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

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

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

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

エディタにアドオンの共通ホームページを表示するには、アドオンのマニフェストに適切なエディタ フィールド(addOns.docsaddOns.sheetsaddOns.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 など)に置き換えます。

  1. マニフェストの適切なエディタ セクションに EDITOR_NAME.onFileScopeGrantedTrigger を含めます。たとえば、Google スプレッドシートでこのインターフェースを作成する場合は、トリガーを "sheets" セクションに追加します。
  2. EDITOR_NAME.onFileScopeGrantedTrigger セクションにある関数を実装します。この関数はイベント オブジェクトを引数として受け取り、単一の Card オブジェクトまたは Card オブジェクトの配列を返す必要があります。
  3. 他のカードと同様に、インターフェースのウィジェット インタラクティビティを提供するために使用するコールバック関数を実装する必要があります。たとえば、インターフェースにボタンを含める場合、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.homepageTriggerEDITOR_NAME.onFileScopeGrantedTrigger などのトリガー関数に渡されます。トリガー関数は、イベント オブジェクト内の情報を使用して、アドオンカードの構築方法やアドオンの動作の制御方法を決定します。

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

エディタがアドオンの代替ホストアプリである場合、イベント オブジェクトには、クライアント情報を格納する Google ドキュメントスプレッドシートスライドのイベント オブジェクト フィールドが含まれます。

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

次の例は、sheets.onFileScopeGrantedTrigger 関数に渡される Editor イベント オブジェクトを示しています。この例では、アドオンには現在のドキュメントの drive.file スコープ承認があります。

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