作成アクションで作成 UI を拡張する

Gmail を拡張する Google Workspace アドオンを使用すると、ユーザーが Gmail のメールを読むときにカードベースのインターフェースを利用できるだけでなく、ユーザーが新しいメールを作成するときや既存のメールに返信するときに別のインターフェースを提供することができます。これにより、Google Workspace アドオンを使用して、ユーザーのメール作成タスクを自動化できます。

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

アドオンの作成 UI を表示する方法は 2 つあります。1 つ目は、アドオンを開いた状態で新しい下書きまたは返信を作成することです。下書きの作成中にアドオンを起動することもできます。

どちらの場合も、アドオンのマニフェストで定義された、対応する Compose トリガー関数が実行されます。作成トリガー関数は、その作成アクション用の作成 UI をビルドし、Gmail はそれをユーザーに表示します。

Compose アドオンを作成する

作成機能をアドオンに追加する一般的な手順は次のとおりです。

  1. gmail.composeTrigger フィールドをアドオン スクリプト プロジェクトのマニフェストに追加し、マニフェストのスコープを更新して、作成アクションに必要なものを追加します。
  2. トリガーの開始時に Compose UI を作成する Compose トリガー関数を実装します。Compose トリガー関数は、Compose アクションの Compose UI を構成する単一の Card オブジェクトまたは Card オブジェクトの配列を返します。
  3. ユーザーによる Compose UI の操作に反応するために必要な関連するコールバック関数を実装します。これらの関数は Compose UI を表示するだけの Compose アクションではありません。Compose UI のさまざまな要素が選択されたときに行われる動作を管理する個別の関数です。たとえば、ボタンを含む UI カードは通常、ユーザーがそのボタンをクリックしたときに実行されるコールバック関数が関連付けられています。下書きメッセージ コンテンツを更新するウィジェットのコールバック関数は、UpdateDraftActionResponse オブジェクトを返す必要があります。

Compose トリガー関数

アドオンの作成 UI はアドオンのメッセージ UI と同じ方法で作成されます。Apps Script のカードサービスを使用してカードを作成し、その中にウィジェットを配置します。

マニフェストで定義した gmail.composeTrigger.selectActions[].runFunction を実装する必要があります。Compose トリガー関数は、そのアクションの Compose UI を構成する単一の Card オブジェクトか、Card オブジェクトの配列を返す必要があります。これらの関数はコンテキスト トリガー関数によく似ており、同じ方法でカードを作成します。

トリガー イベント オブジェクトの作成

作成アクションが選択されると、対応する作成トリガー関数が実行され、関数にパラメータとしてイベント オブジェクトが渡されます。イベント オブジェクトには、アドオンのコンテキストと作成中のドラフトに関する情報をトリガー関数に含めることができます。

イベント オブジェクト内での情報の配置について詳しくは、イベント オブジェクトの構造をご覧ください。イベント オブジェクトに含まれる情報は、gmail.composeTrigger.draftAccess マニフェスト フィールドの値によって部分的に制御されます。

  • gmail.composeTrigger.draftAccess マニフェスト フィールドが NONE であるか、含まれていない場合、イベント オブジェクトには最小限の情報しか含まれません。

  • gmail.composeTrigger.draftAccessMETADATA に設定されている場合、作成トリガー関数に渡されるイベント オブジェクトには、作成中のメールの受信者のリストが入力されます。

アクティブな下書きにコンテンツを挿入する

通常、Google Workspace アドオンの作成 UI には、メッセージの作成に役立つオプションとコントロールがユーザーに表示されます。このようなユースケースでは、ユーザーが UI で選択すると、アドオンはその選択を解釈し、それに応じて現在の仕事用メールの下書きを更新します。

現在の下書きメールを簡単に更新できるように、カードサービスが次のクラスで拡張されました。

通常、アドオン作成 UI には「保存」または「挿入」ウィジェットが含まれています。ユーザーはこのウィジェットをクリックして、UI で選択を完了し、作成中のメールに選択肢を追加したいことを示します。このインタラクティビティを追加するには、ウィジェットがクリックされたときに特定のコールバック関数を実行するようにアドオンに指示する Action オブジェクトがウィジェットに含まれている必要があります。これらのコールバック関数は実装する必要があります。各コールバック関数は、現在の下書きメールに加える変更の詳細を含むビルド済み UpdateDraftActionResponse オブジェクトを返す必要があります。

例 1

次のコード スニペットは、現在のメールの下書きの件名と、To、Cc、Bcc の宛先を更新する Compose UI の作成方法を示しています。

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getComposeUI(e) {
      return [buildComposeCard()];
    }

    /**
     * Build a card to display interactive buttons to allow the user to
     * update the subject, and To, Cc, Bcc recipients.
     *
     * @return {Card}
     */
    function buildComposeCard() {

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('Update email');
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update subject')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('applyUpdateSubjectAction')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update To recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateToRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Cc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateCcRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Bcc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateBccRecipients')));
      return card.addSection(cardSection).build();
    }

    /**
     * Updates the subject field of the current email when the user clicks
     * on "Update subject" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateSubjectAction() {
      // Get the new subject field of the email.
      // This function is not shown in this example.
      var subject = getSubject();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftSubjectAction(CardService.newUpdateDraftSubjectAction()
              .addUpdateSubject(subject))
          .build();
      return response;
    }

    /**
     * Updates the To recipients of the current email when the user clicks
     * on "Update To recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateToRecipientsAction() {
      // Get the new To recipients of the email.
      // This function is not shown in this example.
      var toRecipients = getToRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftToRecipientsAction(CardService.newUpdateDraftToRecipientsAction()
              .addUpdateToRecipients(toRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Cc recipients  of the current email when the user clicks
     * on "Update Cc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateCcRecipientsAction() {
      // Get the new Cc recipients of the email.
      // This function is not shown in this example.
      var ccRecipients = getCcRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftCcRecipientsAction(CardService.newUpdateDraftCcRecipientsAction()
              .addUpdateToRecipients(ccRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Bcc recipients  of the current email when the user clicks
     * on "Update Bcc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateBccRecipientsAction() {
      // Get the new Bcc recipients of the email.
      // This function is not shown in this example.
      var bccRecipients = getBccRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBccRecipientsAction(CardService.newUpdateDraftBccRecipientsAction()
              .addUpdateToRecipients(bccRecipients))
          .build();
      return response;
    }

例 2

次のコード スニペットは、現在の下書きメールに画像を挿入する Compose UI の作成方法を示しています。

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getInsertImageComposeUI(e) {
      return [buildImageComposeCard()];
    }

    /**
     * Build a card to display images from a third-party source.
     *
     * @return {Card}
     */
    function buildImageComposeCard() {
      // Get a short list of image URLs to display in the UI.
      // This function is not shown in this example.
      var imageUrls = getImageUrls();

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('My Images');
      for (var i = 0; i < imageUrls.length; i++) {
        var imageUrl = imageUrls[i];
        cardSection.addWidget(
            CardService.newImage()
                .setImageUrl(imageUrl)
                .setOnClickAction(CardService.newAction()
                      .setFunctionName('applyInsertImageAction')
                      .setParameters({'url' : imageUrl})));
      }
      return card.addSection(cardSection).build();
    }

    /**
     * Adds an image to the current draft email when the image is clicked
     * in the compose UI. The image is inserted at the current cursor
     * location. If any content of the email draft is currently selected,
     * it is deleted and replaced with the image.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @param {event} e The incoming event object.
     * @return {UpdateDraftActionResponse}
     */
    function applyInsertImageAction(e) {
      var imageUrl = e.parameters.url;
      var imageHtmlContent = '<img style=\"display: block\" src=\"'
           + imageUrl + '\"/>';
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
              .addUpdateContent(
                  imageHtmlContent,
                  CardService.ContentType.MUTABLE_HTML)
              .setUpdateType(
                  CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
          .build();
      return response;
    }