Mở rộng giao diện người dùng Compose bằng các thao tác Compose

Ngoài việc cung cấp giao diện dựa trên thẻ khi người dùng đang đọc thư trên Gmail, các tiện ích bổ sung của Google Workspace mở rộng Gmail có thể cung cấp một giao diện khác khi người dùng đang soạn thư mới hoặc trả lời thư hiện có. Điều này cho phép các tiện ích bổ sung của Google Workspace tự động hoá việc soạn email cho người dùng.

Truy cập vào giao diện người dùng Compose của tiện ích bổ sung

Có hai cách để xem giao diện người dùng Compose của một tiện ích bổ sung. Cách đầu tiên là bắt đầu soạn một thư nháp hoặc thư trả lời mới trong khi tiện ích bổ sung đang mở. Cách thứ hai là bắt đầu tiện ích bổ sung trong khi soạn bản thảo.

Trong cả hai trường hợp, tiện ích bổ sung sẽ thực thi hàm kích hoạt Compose tương ứng, được xác định trong tệp kê khai của tiện ích bổ sung. Hàm kích hoạt Compose sẽ tạo giao diện người dùng Compose cho hành động Compose đó, sau đó Gmail sẽ hiển thị cho người dùng.

Tạo tiện ích bổ sung cho Compose

Bạn có thể thêm chức năng Compose vào tiện ích bổ sung bằng cách làm theo các bước chung sau:

  1. Thêm trường gmail.composeTrigger vào tệp kê khai của dự án tập lệnh bổ sung và cập nhật phạm vi của tệp kê khai để bao gồm các phạm vi cần thiết cho các hành động trong Compose.
  2. Triển khai hàm điều kiện kích hoạt Compose để tạo giao diện người dùng Compose khi điều kiện kích hoạt được kích hoạt. Hàm kích hoạt Compose trả về một đối tượng Card hoặc một mảng các đối tượng Card bao gồm giao diện người dùng Compose cho hành động Compose.
  3. Triển khai các hàm gọi lại liên kết cần thiết để phản hồi các hoạt động tương tác trên giao diện người dùng của người dùng. Các hàm này không phải là chính thao tác soạn thư (chỉ khiến giao diện người dùng soạn thư xuất hiện); mà là các hàm riêng lẻ điều chỉnh những gì xảy ra khi các thành phần khác nhau của giao diện người dùng soạn thư được chọn. Ví dụ: thẻ giao diện người dùng chứa một nút thường có một hàm gọi lại được liên kết sẽ thực thi khi người dùng nhấp vào nút đó. Hàm gọi lại cho các tiện ích cập nhật nội dung thư nháp phải trả về đối tượng UpdateDraftActionResponse.

Hàm kích hoạt Compose

Giao diện người dùng Compose của tiện ích bổ sung được xây dựng giống như giao diện người dùng thông báo của tiện ích bổ sung – sử dụng Dịch vụ thẻ của Apps Script để tạo thẻ và điền vào các thẻ đó bằng tiện ích.

Bạn phải triển khai gmail.composeTrigger.selectActions[].runFunction mà bạn xác định trong tệp kê khai. Hàm kích hoạt Compose phải trả về một đối tượng Card hoặc một mảng các đối tượng Card bao gồm giao diện người dùng Compose cho hành động đó. Các hàm này rất giống với hàm điều kiện kích hoạt theo ngữ cảnh và sẽ tạo thẻ theo cách tương tự.

Đối tượng sự kiện kích hoạt Compose

Khi một thao tác Compose được chọn, thao tác đó sẽ thực thi hàm trình kích hoạt Compose tương ứng và truyền hàm đối tượng sự kiện dưới dạng tham số. Đối tượng sự kiện có thể mang thông tin về ngữ cảnh của tiện ích bổ sung và bản nháp đang được soạn cho hàm kích hoạt.

Hãy xem phần Cấu trúc đối tượng sự kiện để biết thông tin chi tiết về cách sắp xếp thông tin trong đối tượng sự kiện. Thông tin chứa trong đối tượng sự kiện được kiểm soát một phần bằng giá trị của trường tệp kê khai gmail.composeTrigger.draftAccess:

  • Nếu trường tệp kê khai gmail.composeTrigger.draftAccess là NONE hoặc không được đưa vào, thì đối tượng sự kiện sẽ chỉ có thông tin tối thiểu.

  • Nếu bạn đặt gmail.composeTrigger.draftAccess thành METADATA, thì đối tượng sự kiện được truyền đến hàm điều kiện kích hoạt của Compose sẽ được điền sẵn danh sách người nhận email đang được soạn.

Chèn nội dung vào bản nháp đang hoạt động

Thông thường, giao diện người dùng soạn thư của tiện ích bổ sung Google Workspace sẽ cung cấp cho người dùng các tuỳ chọn và chế độ kiểm soát giúp soạn thư. Đối với các trường hợp sử dụng này, sau khi người dùng đã chọn trong giao diện người dùng, tiện ích bổ sung sẽ diễn giải các lựa chọn đó và cập nhật bản nháp email đang hoạt động cho phù hợp.

Để giúp bạn dễ dàng cập nhật email nháp hiện tại, Dịch vụ thẻ đã được mở rộng với các lớp sau:

Thông thường, giao diện người dùng của tiện ích bổ sung Compose bao gồm một tiện ích "Lưu" hoặc "Chèn" mà người dùng có thể nhấp vào để cho biết họ đã hoàn tất việc lựa chọn trong giao diện người dùng và muốn thêm các lựa chọn của họ vào email mà họ đang soạn. Để thêm tính năng tương tác này, tiện ích phải có đối tượng Action liên kết để hướng dẫn tiện ích bổ sung chạy một hàm gọi lại cụ thể khi người dùng nhấp vào tiện ích. Bạn phải triển khai các hàm gọi lại này. Mỗi hàm gọi lại phải trả về một đối tượng UpdateDraftActionResponse được tạo sẵn, trong đó nêu chi tiết những thay đổi cần thực hiện đối với email nháp hiện tại.

Ví dụ 1

Đoạn mã sau đây cho biết cách tạo giao diện người dùng Compose để cập nhật tiêu đề và người nhận To (Đến), Cc (Cc) và Bcc (Ẩn tên người nhận) của thư nháp hiện tại.

    /**
     * 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;
    }

Ví dụ 2

Đoạn mã sau đây cho biết cách tạo giao diện người dùng Compose để chèn hình ảnh vào email nháp hiện tại.

    /**
     * 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;
    }