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

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

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

アドオン UI へのアクセス

Google Workspace アドオンのアイコンが、ドキュメント、スプレッドシート、スライドのユーザーインターフェースの右側にある 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 オブジェクトの配列を返す必要があります。
他のカードと同様に、インターフェースのウィジェットのインタラクティビティを提供するために使用されるコールバック関数を実装する必要があります。たとえば、インターフェースにボタンを含める場合は、ボタンに 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 エディタ インターフェースの構築 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。