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 Gmail thư, Tiện ích bổ sung của Google Workspace giúp 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 đang trả lời những câu hỏi hiện có. Điều này cho phép các Tiện ích bổ sung của Google Workspace tự động hoá tác vụ soạn email cho người dùng.

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

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 thư nháp hoặc thư trả lời mới trong khi tiện ích bổ sung đã mở. Thứ hai là khởi động tiện ích bổ sung trong khi soạn bản nháp.

Một trong hai trường hợp đều khiến tiện ích bổ sung thực thi lệnh gọi hàm kích hoạt Compose, được xác định trong tiện ích bổ sung tệp kê khai. Hàm kích hoạt Compose tạo giao diện người dùng cho Compose đó hành động mà 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 soạn thư vào tiện ích bổ sung bằng cách làm theo các bước chung sau:

  1. Thêm gmail.composeTrigger với dự án tập lệnh tiện ích bổ sung tệp kê khai và cập nhật tệp kê khai phạm vi cần đưa vào những yêu cầu bắt buộc đối với thao tác soạn thư.
  2. Triển khai hàm kích hoạt Compose tạo giao diện người dùng khi trình kích hoạt sẽ kích hoạt. Hàm kích hoạt Compose trả về một giá trị duy nhấ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 thao tác soạn thư.
  3. Triển khai các hàm callback được liên kết để phản ứng lại các lệnh gọi lại của người dùng các lượt tương tác trên giao diện người dùng Compose. Các hàm này không phải là chính thao tác Compose (chỉ khiến giao diện người dùng Compose xuất hiện); đúng hơn, đây là những các chức năng riêng lẻ chi phối điều sẽ xảy ra khi các phần tử khác nhau của giao diện người dùng Compose đượ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 callback được liên kết thực thi khi người dùng nhấp vào nút đó. Hàm callback cho các tiện ích cập nhật tin nhắn nháp Nội dung nên trả về một giá trị UpdateDraftActionResponse .

Hàm kích hoạt Compose

Giao diện người dùng soạn thư của tiện ích bổ sung được xây dựng theo cách giống với thông báo của tiện ích bổ sung Giao diện người dùng – sử dụng dịch vụ Thẻ Apps Script để tạo thẻ và điền chúng 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 thao tác đó. Các hàm này rất giống nhau đến hàm kích hoạt theo ngữ cảnh và nên xây dựng thẻ theo cách tương tự.

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

Khi bạn chọn một thao tác soạn thư, thao tác này sẽ thực thi điều kiện kích hoạt tương ứng trong Compose hàm và truyền cho hàm một đố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ề bối cảnh của tiện ích bổ sung và bản nháp đang được kết hợp với chức năng kích hoạt.

Xem bài viết Cấu trúc đối tượng sự kiện để biết chi tiết về cách thông tin được sắp xếp 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 bởi giá trị của thuộc tính gmail.composeTrigger.draftAccess trường tệp kê khai:

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

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

Đang chèn nội dung vào bản thảo đang hoạt động

Thông thường, giao diện người dùng Compose Tiện ích bổ sung của Google Workspace cung cấp các tuỳ chọn và chức năng điều khiển cho người dùng giúp soạn thư. Đối với các trường hợp sử dụng này, khi người dùng đã thực hiện lựa 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 làm việc cho phù hợp.

Để cập nhật email nháp hiện tại dễ dàng hơn, hãy nhấp vào 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 trong Compose có nút "Lưu" hoặc "Chèn" mà một người dùng có thể nhấp để cho biết họ đã chọn xong trong giao diện người dùng và muốn biết các lựa chọn cần thêm vào email mà họ đang soạn. Để thêm nội dung này tương tác, thì tiện ích phải có một đối tượng Action được liên kết hướng dẫn tiện ích bổ sung chạy một hàm callback cụ thể khi tiện ích này đã nhấp vào. Bạn phải triển khai các hàm callback này. Mỗi hàm callback phải trả về một biến đã tạo UpdateDraftActionResponse nêu chi tiết các 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à Tới, Cc, Bcc của những người nhận 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 một giao diện người dùng Compose có 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;
    }