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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

アドオンの作成 UI へのアクセス

アドオンの作成 UI を表示する方法は 2 つあります。1 つ目の方法は、アドオンがすでに開いているときに新しい下書きまたは返信の作成を開始することです。2 つ目の方法は、ドラフトを作成しながらアドオンを開始することです。

いずれの場合も、対応する作成トリガー関数(アドオンのマニフェストで定義)は、アドオンによって実行されます。作成トリガー関数では、その作成アクションの UI を作成し、Gmail でそれを表示します。

Compose アドオンの作成

作成機能は、以下の一般的な手順に沿ってアドオンに追加できます。

  1. gmail.composeTrigger フィールドをアドオン スクリプト プロジェクトのマニフェストに追加し、マニフェスト スコープを更新して、作成アクションに必要なスコープを追加します。
  2. トリガーの起動時に Compose UI を作成する Compose トリガー関数を実装します。Compose トリガー関数は、1 つの Card オブジェクト、または Compose アクションの作成 UI を構成する Card オブジェクトの配列を返します。
  3. ユーザー作成 UI インタラクションへの応答に必要な関連するコールバック関数を実装します。これらの関数は Compose アクションそのものではなく、Compose UI が表示されるだけです。これは、Compose UI のさまざまな要素が選択されたときの動作を制御する個々の関数です。たとえば、ボタンを含む UI カードには通常、ユーザーがそのボタンをクリックしたときに実行されるコールバック関数が関連付けられています。メッセージの下書き内容を更新するウィジェット用のコールバック関数は、UpdateDraftActionResponse オブジェクトを返します。

Compose トリガー関数

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

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

Compose トリガー イベント オブジェクト

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

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

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

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

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

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

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

通常、作成用 UI のアドオンには、' Save' 'Insert' ウィジェットが含まれます。ユーザーはこのウィジェットをクリックして、UI での選択を行い、作成中のメールに選択内容を追加させることができます。このインタラクティビティを追加するには、ウィジェットが関連付けられている Action オブジェクトが必要です。このオブジェクトは、ウィジェットがクリックされたときに特定のコールバック関数を実行するようアドオンに指示します。これらのコールバック関数を実装する必要があります。各コールバック関数は、現在の下書きメールに加えられた変更の詳細を示すビルドされた UpdateDraftActionResponse オブジェクトを返します。

例 1

次のコード スニペットは、現在の UI のメール作成ウィンドウで、件名と宛先、Cc、Bcc を更新する作成 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;
    }