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 có thể mở rộng Gmail còn 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 soạn thư của tiện ích bổ sung. Cách đầu tiên là bắt đầu soạn thảo một bản nháp mới hoặc trả lời trong khi tiện ích bổ sung đã 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 thành phần kết hợp 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 thành phần tạo sẽ tạo giao diện người dùng thành phần cho thao tác thành phần đó, sau đó Gmail sẽ hiển thị cho người dùng.

Tạo tiện ích bổ sung soạn thư

Bạn có thể thêm chức năng soạn thư vào một 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 dự án tập lệnh của tiện ích bổ sung và cập nhật các phạm vi của tệp kê khai để thêm những phạm vi cần thiết cho các thao tác tạo.
  2. Triển khai một hàm kích hoạt Compose để tạo giao diện người dùng Compose khi sự kiện kích hoạt xảy ra. Các hàm kích hoạt Compose trả về một đối tượng Card duy nhất hoặc một mảng các đối tượng Card bao gồm giao diện người dùng Compose cho thao tác Compose.
  3. Triển khai các hàm gọi lại được liên kết cần thiết để phản ứng với các lượt tương tác của người dùng trên giao diện người dùng Compose. Những hàm này không phải là 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à những hàm riêng lẻ chi phối những gì xảy ra khi các phần tử 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 những tiện ích cập nhật nội dung thư nháp phải trả về một đối tượng UpdateDraftActionResponse.

Hàm điều kiện kích hoạt Compose

Giao diện người dùng Compose của tiện ích bổ sung được tạo theo cách tương tự 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 tiện ích vào thẻ.

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 thành phần phải trả về một đối tượng Card hoặc một mảng các đối tượng Card tạo nên giao diện người dùng thành phần cho thao tác đó. Các hàm này rất giống với hàm kích hoạt theo bối cảnh và phải tạo thẻ theo cùng một cách.

Soạn các đối tượng sự kiện kích hoạt

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

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 có trong đối tượng sự kiện được kiểm soát một phần theo giá trị của trường tệp kê khai gmail.composeTrigger.draftAccess:

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

  • Nếu gmail.composeTrigger.draftAccess được đặt thành METADATA, thì đối tượng sự kiện được truyền đến hàm kích hoạt thành phần sẽ được điền sẵn danh sách người nhận của 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 cung cấp cho người dùng các lựa chọn và chế độ kiểm soát giúp soạn thư. Đối với những 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 hiện tại 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 Compose của tiện ích bổ sung sẽ có 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 các lựa chọn của mình được thêm 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ó một đối tượng Action được liên kết. Đối tượng này 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, 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 đề, người nhận Đến, Cc và Bcc của bản nháp email 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;
    }