このページは Cloud Translation API によって翻訳されました。

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

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

アドオン UI へのアクセス

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

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

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

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

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

アドオンスクリプトプロジェクトのマニフェストに、適切な 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 オブジェクトの配列を返す必要があります。
他のカードと同様に、インターフェースにウィジェットのインタラクティビティを提供するために使用されるコールバック関数を実装する必要があります。たとえば、インターフェースにボタンを追加する場合は、ボタンにアクションを適用し、ボタンがクリックされたときに実行されるコールバック関数を実装する必要があります。

次の例は、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 などのトリガー関数に渡されます。トリガー関数は、イベントオブジェクトの情報を使用して、アドオンカードの作成方法やアドオンの動作を制御する方法を決定します。

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

アドオンのホストアプリとしてエディタが機能している場合、イベントオブジェクトには、クライアント情報を伝送するドキュメント、スプレッドシート、スライドのイベントオブジェクトフィールドが含まれます。

アドオンに現在のユーザーまたはドキュメントに対する 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 エディタ インターフェースの構築