Thiết kế thẻ hoặc hộp thoại tương tác

Trang này giải thích cách thêm tiện ích và các phần tử trên giao diện người dùng vào thẻ hoặc tin nhắn hộp thoại để người dùng có thể tương tác với ứng dụng Google Chat, chẳng hạn như bằng cách nhấp vào một nút hoặc gửi thông tin.


Thiết kế và xem trước thẻ bằng Trình tạo thẻ.

Mở Trình tạo thẻ

Điều kiện tiên quyết

  • Một tài khoản Google Workspace có quyền truy cập vào Google Chat.
  • Một ứng dụng Chat đã phát hành. Để tạo ứng dụng Chat, hãy làm theo phần quickstart này.
  • Thêm nút

    Tiện ích ButtonList sẽ hiển thị một tập hợp các nút. Các nút có thể hiển thị văn bản, biểu tượng hoặc cả văn bản và biểu tượng. Mỗi Button đều hỗ trợ một thao tác OnClick xảy ra khi người dùng nhấp vào nút. Ví dụ:

    • Mở một siêu liên kết có OpenLink để cung cấp thêm thông tin cho người dùng.
    • Chạy action để chạy một hàm tuỳ chỉnh, chẳng hạn như gọi API.

    Đối với tính năng hỗ trợ tiếp cận, các nút hỗ trợ văn bản thay thế.

    Thêm một nút chạy hàm tuỳ chỉnh

    Sau đây là một thẻ bao gồm tiện ích ButtonList có 2 nút. Nút Một sẽ mở tài liệu Google Chat dành cho nhà phát triển trong một thẻ mới. Nút còn lại chạy một hàm tuỳ chỉnh có tên là goToView() và truyền tham số viewType="BIRD EYE VIEW".

    Thêm một nút có màu tuỳ chỉnh và nút đã tắt

    Bạn có thể ngăn người dùng nhấp vào một nút bằng cách đặt "disabled": "true".

    Phần sau đây sẽ hiển thị một thẻ bao gồm tiện ích ButtonList có 2 nút. Một nút dùng trường Color để tuỳ chỉnh màu nền của nút. Nút còn lại được huỷ kích hoạt bằng trường Disabled. Trường này ngăn người dùng nhấp vào nút đó và thực thi hàm.

    Thêm nút có biểu tượng

    Phần sau đây sẽ hiển thị một thẻ bao gồm một tiện ích ButtonList với hai tiện ích biểu tượng Button. Một nút dùng trường knownIcon để hiển thị biểu tượng email tích hợp sẵn trong Google Chat. Nút còn lại sử dụng trường iconUrl để hiển thị tiện ích biểu tượng tuỳ chỉnh.

    Thêm một nút có biểu tượng và văn bản

    Phần sau đây sẽ hiển thị một thẻ bao gồm tiện ích ButtonList nhắc người dùng gửi email. Nút đầu tiên hiển thị biểu tượng email và nút thứ hai hiển thị văn bản. Người dùng có thể nhấp vào nút biểu tượng hoặc văn bản để chạy hàm sendEmail.

    Thêm các thành phần giao diện người dùng có thể chọn

    Tiện ích SelectionInput cung cấp một tập hợp các mục có thể chọn, chẳng hạn như hộp đánh dấu, nút chọn, nút chuyển hoặc trình đơn thả xuống. Bạn có thể sử dụng tiện ích này để thu thập dữ liệu đã xác định và chuẩn hoá từ người dùng. Để thu thập dữ liệu không xác định từ người dùng, hãy sử dụng tiện ích TextInput.

    Tiện ích SelectionInput hỗ trợ các đề xuất, giúp người dùng nhập dữ liệu đồng nhất và các hành động thay đổi Actions sẽ chạy khi có thay đổi xảy ra trong trường nhập dữ liệu lựa chọn, chẳng hạn như người dùng chọn hoặc bỏ chọn một mục.

    Ứng dụng trong Chat có thể nhận và xử lý giá trị của các mục đã chọn. Để biết thông tin chi tiết về cách xử lý thông tin nhập vào biểu mẫu, vui lòng xem phần Nhận dữ liệu biểu mẫu.

    Phần này đưa ra các ví dụ về các thẻ sử dụng tiện ích SelectionInput. Các ví dụ này sử dụng nhiều loại dữ liệu đầu vào mục:

    Thêm hộp đánh dấu

    Phần sau đây hiển thị một hộp thoại yêu cầu người dùng chỉ định xem một người liên hệ là nghề nghiệp, cá nhân hay cả hai, bằng tiện ích SelectionInput sử dụng hộp đánh dấu:

    Thêm nút chọn

    Phần sau đây sẽ hiển thị một hộp thoại yêu cầu người dùng chỉ định xem một người liên hệ là chuyên nghiệp hay cá nhân thông qua tiện ích SelectionInput sử dụng nút chọn:

    Thêm một nút chuyển

    Phần sau đây hiển thị một hộp thoại yêu cầu người dùng chỉ định xem một người liên hệ là nghề nghiệp, cá nhân hay cả hai bằng tiện ích SelectionInput sử dụng công tắc:

    Phần sau đây sẽ hiển thị một hộp thoại yêu cầu người dùng chỉ định xem một người liên hệ là cá nhân hay là công việc bằng một tiện ích SelectionInput sử dụng trình đơn thả xuống:

    Thêm trình đơn chọn nhiều mục

    Phần sau đây sẽ hiển thị một hộp thoại yêu cầu người dùng chọn các mục liên hệ trong trình đơn chọn nhiều mục:

    Sử dụng nguồn dữ liệu cho trình đơn chọn nhiều mục

    Phần sau đây giải thích cách sử dụng trình đơn chọn nhiều mục để điền dữ liệu từ các nguồn động, chẳng hạn như một ứng dụng trên Google Workspace hoặc nguồn dữ liệu bên ngoài.

    Nguồn dữ liệu từ Google Workspace

    Bạn có thể điền sẵn các mục cho trình đơn nhiều lựa chọn từ các nguồn dữ liệu sau đây trong Google Workspace:

    • Người dùng Google Workspace: Bạn chỉ có thể điền dữ liệu cho người dùng trong cùng một tổ chức Google Workspace.
    • Không gian trò chuyện: Người dùng nhập các mục trong trình đơn chọn nhiều mục chỉ có thể xem và chọn các không gian chứa người đó trong tổ chức của họ trên Google Workspace.

    Để sử dụng các nguồn dữ liệu của Google Workspace, bạn cần chỉ định trường platformDataSource. Không giống như các loại dữ liệu đầu vào lựa chọn khác, bạn bỏ qua các đối tượng SectionItem, vì các mục lựa chọn này có nguồn gốc động từ Google Workspace.

    Mã sau đây cho thấy một trình đơn nhiều lựa chọn gồm người dùng Google Workspace. Để điền sẵn người dùng, trường nhập lựa chọn sẽ đặt commonDataSource thành USER:

    JSON

    {
      "selectionInput": {
        "name": "contacts",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 5,
        "multiSelectMinQueryLength": 1,
        "platformDataSource": {
          "commonDataSource": "USER"
        }
      }
    }
    

    Mã sau đây cho thấy một trình đơn nhiều lựa chọn của các phòng Chat. Để điền sẵn không gian, dữ liệu đầu vào của lựa chọn sẽ chỉ định trường hostAppDataSource. Trình đơn nhiều lựa chọn cũng đặt defaultToCurrentSpace thành true, khiến không gian hiện tại trở thành lựa chọn mặc định trong trình đơn:

    JSON

    {
      "selectionInput": {
        "name": "spaces",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 3,
        "multiSelectMinQueryLength": 1,
        "platformDataSource": {
          "hostAppDataSource": {
            "chatDataSource": {
              "spaceDataSource": {
                "defaultToCurrentSpace": true
              }
            }
          }
        }
      }
    }
    
    Các nguồn dữ liệu bên ngoài Google Workspace

    Trình đơn chọn nhiều mục cũng có thể điền sẵn các mục từ nguồn dữ liệu của bên thứ ba hoặc nguồn dữ liệu bên ngoài. Ví dụ: bạn có thể sử dụng các trình đơn chọn nhiều mục để giúp người dùng chọn trong danh sách khách hàng tiềm năng của hệ thống quản lý quan hệ khách hàng (CRM).

    Để sử dụng nguồn dữ liệu bên ngoài, bạn hãy sử dụng trường externalDataSource để chỉ định hàm trả về các mục từ nguồn dữ liệu này.

    Để giảm yêu cầu đến nguồn dữ liệu bên ngoài, bạn có thể đưa các mục được đề xuất xuất hiện trong trình đơn chọn nhiều trước khi người dùng nhập vào trình đơn. Ví dụ: bạn có thể điền sẵn các địa chỉ liên hệ được tìm kiếm gần đây cho người dùng. Để điền sẵn các mục được đề xuất từ một nguồn dữ liệu bên ngoài, hãy chỉ định các đối tượng SelectionItem.

    Mã sau đây cho người dùng thấy một trình đơn chọn nhiều mục từ một nhóm địa chỉ liên hệ bên ngoài. Theo mặc định, trình đơn này hiển thị một người liên hệ và chạy hàm getContacts để truy xuất và điền các mục từ nguồn dữ liệu bên ngoài:

    JSON

    {
      "selectionInput": {
        "name": "contacts",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 5,
        "multiSelectMinQueryLength": 2,
        "externalDataSource": {
          "function": "getContacts"
        },
        "items": [
          {
            "text": "Contact 3",
            "value": "contact-3",
            "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
            "bottomText": "Contact three description",
            "selected": false
          }
        ]
      }
    }
    

    Đối với các nguồn dữ liệu bên ngoài, bạn cũng có thể tự động hoàn thành các mục mà người dùng bắt đầu nhập vào trình đơn chọn nhiều mục. Ví dụ: nếu người dùng bắt đầu nhập Atl cho một trình đơn điền sẵn các thành phố ở Hoa Kỳ, thì ứng dụng Chat có thể tự động đề xuất Atlanta trước khi người dùng hoàn tất việc nhập. Bạn có thể tự động hoàn thành tối đa 100 mục.

    Để tự động hoàn thành các mục, bạn cần tạo một hàm truy vấn nguồn dữ liệu bên ngoài và trả về các mục bất cứ khi nào người dùng nhập vào trình đơn chọn nhiều mục. Hàm phải thực hiện những việc sau:

    • Truyền một đối tượng sự kiện đại diện cho hoạt động tương tác của người dùng với trình đơn.
    • Xác định rằng giá trị invokedFunction của sự kiện tương tác khớp với hàm từ trường externalDataSource.
    • Khi các hàm khớp, hãy trả về các mục đề xuất từ nguồn dữ liệu bên ngoài. Để đề xuất các mục dựa trên nội dung người dùng nhập, hãy lấy giá trị cho khoá autocomplete_widget_query. Giá trị này biểu thị nội dung người dùng nhập trong trình đơn.

    Mã sau đây sẽ tự động hoàn thành các mục từ tài nguyên dữ liệu bên ngoài. Trong ví dụ trước, ứng dụng Chat sẽ đề xuất các mục dựa trên thời điểm kích hoạt hàm getContacts:

    Apps Script

    apps-script/selection-input/on-widget-update.gs
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              items: [
                {
                  value: "contact-1",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 1",
                  bottomText: "Contact one description",
                  selected: false
                },
                {
                  value: "contact-2",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 2",
                  bottomText: "Contact two description",
                  selected: false
                },
                {
                  value: "contact-3",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 3",
                  bottomText: "Contact three description",
                  selected: false
                },
                {
                  value: "contact-4",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 4",
                  bottomText: "Contact four description",
                  selected: false
                },
                {
                  value: "contact-5",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 5",
                  bottomText: "Contact five description",
                  selected: false
                },
              ]
            }
          }
        }
      };
    }
    

    Node.js

    node/selection-input/on-widget-update.js
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              items: [
                {
                  value: "contact-1",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 1",
                  bottomText: "Contact one description",
                  selected: false
                },
                {
                  value: "contact-2",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 2",
                  bottomText: "Contact two description",
                  selected: false
                },
                {
                  value: "contact-3",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 3",
                  bottomText: "Contact three description",
                  selected: false
                },
                {
                  value: "contact-4",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 4",
                  bottomText: "Contact four description",
                  selected: false
                },
                {
                  value: "contact-5",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 5",
                  bottomText: "Contact five description",
                  selected: false
                },
              ]
            }
          }
        }
      };
    }
    

    Thêm trường mà người dùng có thể nhập văn bản

    Tiện ích TextInput cung cấp một trường mà người dùng có thể nhập văn bản. Tiện ích này hỗ trợ các đề xuất, giúp người dùng nhập dữ liệu đồng nhất và các hành động thay đổi (Actions sẽ chạy khi có thay đổi trong trường nhập văn bản, chẳng hạn như người dùng thêm hoặc xoá văn bản).

    Khi bạn cần thu thập dữ liệu trừu tượng hoặc không xác định từ người dùng, hãy sử dụng tiện ích TextInput này. Để thu thập dữ liệu đã xác định từ người dùng, hãy sử dụng tiện ích SelectionInput.

    Để xử lý văn bản mà người dùng nhập, hãy xem phần Nhận dữ liệu biểu mẫu.

    Dưới đây là một thẻ bao gồm tiện ích TextInput:

    Cho phép người dùng chọn ngày và giờ

    Tiện ích DateTimePicker cho phép người dùng nhập ngày, giờ hoặc cả ngày và giờ. Ngoài ra, người dùng có thể sử dụng bộ chọn để chọn ngày và giờ. Nếu người dùng nhập ngày hoặc giờ không hợp lệ, bộ chọn sẽ hiển thị lỗi nhắc người dùng nhập thông tin chính xác.

    Để xử lý các giá trị ngày và giờ mà người dùng nhập, hãy xem phần Nhận dữ liệu biểu mẫu.

    Phần sau đây sẽ hiển thị một thẻ gồm 3 loại tiện ích DateTimePicker:

    Khắc phục sự cố

    Khi ứng dụng Google Chat hoặc thẻ trả về lỗi, giao diện Chat sẽ hiển thị thông báo "Đã xảy ra lỗi." hoặc "Không thể xử lý yêu cầu của bạn". Đôi khi, giao diện người dùng của Chat không hiển thị thông báo lỗi nào, nhưng ứng dụng hoặc thẻ Chat cho ra kết quả không mong muốn; ví dụ: thông báo thẻ có thể không xuất hiện.

    Mặc dù thông báo lỗi có thể không hiển thị trong giao diện người dùng Chat, nhưng chúng tôi cung cấp dữ liệu nhật ký và thông báo lỗi mô tả để giúp bạn khắc phục lỗi khi bật tính năng ghi nhật ký lỗi cho các ứng dụng trong Chat. Để được trợ giúp về việc xem, gỡ lỗi và sửa lỗi, hãy xem phần Khắc phục sự cố và sửa lỗi trên Google Chat.