Thêm thành phần giao diện người dùng tương tác vào thẻ

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

Các ứng dụng trong Chat có thể sử dụng những giao diện sau đây của Chat để tạo thẻ tương tác:

  • Tin nhắn có chứa một hoặc nhiều thẻ.
  • Trang chủ, là thẻ xuất hiện từ tab Trang chủ trực tiếp tin nhắn bằng ứng dụng Chat.
  • Hộp thoại, là các thẻ sẽ mở ra trong cửa sổ mới từ tin nhắn và trang chủ.

Khi người dùng tương tác với thẻ, các ứng dụng trong Chat có thể sử dụng dữ liệu nhận được để xử lý và phản hồi cho phù hợp. Để biết thông tin chi tiết, hãy xem Thu thập và xử lý thông tin của người dùng Google Chat.


Sử dụng Trình tạo thẻ để thiết kế và xem trước thông báo cũng như giao diện người dùng của các ứng dụng trong Chat:

Mở Trình tạo thẻ

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

Một ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác, hãy hoàn thành một trong các bước bắt đầu nhanh sau đây trên cấu trúc ứng dụng mà bạn muốn sử dụng:

Thêm nút

Chiến lược phát hành đĩa đơn Tiện ích ButtonList 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, hoặc cả văn bản và biểu tượng. Một Button hỗ trợ một OnClick hành động xảy ra khi người dùng nhấp vào nút. Ví dụ:

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

Để 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. Một nút sẽ mở tài liệu dành cho nhà phát triển Google Chat trong thẻ mới. Chiến lược phát hành đĩa đơn 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 nút theo kiểu Material Design

Dưới đây là một tập hợp các nút trong các nút Material Design khác nhau kiểu.

Để áp dụng kiểu Material Design, đừng thêm thuộc tính "màu sắc" .

Thêm một nút có màu sắc tuỳ chỉnh và một nút đã huỷ kích hoạt

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

Dưới đây là một thẻ bao gồm tiện ích ButtonList với hai các nút. Một nút sử dụng Trường Color để tuỳ chỉnh nền của nút . Nút còn lại bị huỷ kích hoạt bằng trường Disabled 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 cho thấy một thẻ bao gồm tiện ích ButtonList có 2 biểu tượng Tiện ích Button. Một nút sử dụng knownIcon để hiển thị biểu tượng email tích hợp sẵn của 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 nút có biểu tượng và văn bản

Phần sau đây hiển thị một thẻ bao gồm tiện ích ButtonList đưa ra lời 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 biểu tượng hoặc văn bản để chạy hàm sendEmail.

Tuỳ chỉnh nút cho một mục có thể thu gọn

Tuỳ chỉnh nút điều khiển có thể thu gọn và mở rộng các phần trong một . Chọn trong số hàng loạt biểu tượng hoặc hình ảnh để trình bày trực quan giúp người dùng hiểu và tương tác dễ dàng hơn thông tin đó.

Thêm trình đơn mục bổ sung

Chiến lược phát hành đĩa đơn Overflow menu có thể dùng trong thẻ Chat để cung cấp thêm tuỳ chọn và thao tác. Chiến dịch này cho phép bạn bao gồm nhiều tuỳ chọn hơn mà không làm lộn xộn giao diện của thẻ, đảm bảo thiết kế gọn gàng và ngăn nắp.

Thêm danh sách Khối

ChipList mang đến một cách linh hoạt và bắt mắt để hiển thị thông tin. Sử dụng danh sách khối để biểu thị thẻ, danh mục hoặc dữ liệu khác có liên quan, giúp để người dùng điều hướng và tương tác với nội dung của bạn dễ dàng hơn.

Thu thập thông tin từ người dùng

Phần này giải thích cách bạn có thể thêm các tiện ích thu thập thông tin, chẳng hạn như hoặc lựa chọn.

Để tìm hiểu cách xử lý dữ liệu mà người dùng nhập vào, hãy xem Thu thập và xử lý thông tin của người dùng Google Chat.

Thu thập văn bản

Tiện ích TextInput cung cấp một trường để người dùng có thể nhập văn bản. Chiến lược phát hành đĩa đơn tiện ích hỗ trợ các đề xuất, giúp người dùng nhập dữ liệu đồng nhất và khi thay đổi hành động, Actions chạy khi có thay đổi xảy ra trong trường nhập dữ liệu văn bản, chẳng hạn như khi người dùng thêm hoặc đang 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. Để thu thập dữ liệu đã xác định từ người dùng, hãy sử dụng SelectionInput để thay thế.

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

Thu thập ngày hoặc giờ

Chiến lược phát hành đĩa đơn Tiện ích DateTimePicker cho phép người dùng nhập ngày, giờ hoặc cả ngày và giờ một lúc. Hoặc 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 một cách chính xác.

Dưới đây là một thẻ bao gồm ba loại Tiện ích DateTimePicker:

Cho phép người dùng chọn các mục

Tiện ích SelectionInput cung cấp một tập hợp các mục có thể chọ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ể dùng tiện ích này để thu thập dữ liệu được 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 hình ảnh thống nhất dữ liệu và hành động khi thay đổi, Actions sẽ chạy khi thay đổi xảy ra trong trường nhập lựa chọn, chẳng hạn như người dùng chọn hoặc bỏ chọn một mục.

Cá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 đầu vào trong biểu mẫu, hãy xem Xử lý thông tin do người dùng nhập.

Phần này đưa ra 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 thẻ yêu cầu người dùng chỉ định xem là người liên hệ chuyên nghiệp, cá nhân hoặc cả hai với một tiện ích SelectionInput sử dụng hộp đánh dấu:

Thêm nút chọn

Phần sau đây hiển thị một thẻ yêu cầu người dùng chỉ định xem địa chỉ liên hệ là chuyên nghiệp hoặc cá nhân có 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 thẻ yêu cầu người dùng chỉ định xem là người liên hệ chuyên nghiệp, cá nhân hoặc cả hai với một tiện ích SelectionInput sử dụng công tắc:

Phần sau đây hiển thị một thẻ yêu cầu người dùng chỉ định xem địa chỉ liên hệ là chuyên nghiệp hoặc cá nhân có 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 cho thấy một thẻ yêu cầu người dùng chọn người liên hệ trên trình đơn chọn nhiều mục:

Bạn có thể điền các mục cho một trình đơn chọn nhiều mục từ dữ liệu sau trong Google Workspace:

  • Người dùng Google Workspace: Bạn chỉ có thể điền người dùng trong cùng tổ chức trên Google Workspace.
  • Phòng Chat: Người dùng nhập các mục bằng tính năng chọn nhiều mục chỉ có thể xem và chọn các không gian chứa chúng trong trình đơn Tổ chức Google Workspace.

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

Đoạn mã sau đây cho thấy một trình đơn chọn nhiều lựa chọn của người dùng Google Workspace. Để điền người dùng, dữ liệu đầu vào của 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"
    }
  }
}

Đoạn mã sau đây cho thấy một trình đơn nhiều lựa chọn của Chat không gian. Để điền dấu cách, giá trị nhập lựa chọn sẽ chỉ định Trường hostAppDataSource. Trình đơn chọn nhiều mục cũng đặt defaultToCurrentSpace thành true, đặt không gian hiện tại làm mặc định lựa chọn trong trình đơn:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

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

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

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

Đoạn mã sau đây hiển thị một trình đơn chọn nhiều mục trên một danh bạ bên ngoài cho người dùng. Trình đơn hiển thị một người liên hệ theo mặc định 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 chứa các thành phố ở Hoa Kỳ, Ứng dụng Chat có thể tự động đề xuất Atlanta trước người dùng hoàn tất 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, hãy tạo một hàm truy vấn dữ liệu bên ngoài nguồn 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. Chiến lược phát hành đĩa đơn hàm phải làm 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 bằng trình đơn.
  • Xác định rằng sự kiện tương tác invokedFunction khớp với hàm trong trường externalDataSource.
  • Khi các hàm khớp với nhau, hãy trả về các mục được đề xuất từ dữ liệu bên ngoài nguồn. Để đề 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 thuộc tính Khoá autocomplete_widget_query. Giá trị này đại diện cho những gì 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ừ một tài nguyên dữ liệu bên ngoài. Sử dụng ví dụ trước, ứng dụng Chat đề xuất các mục dựa trên khi hàm getContacts được kích hoạt:

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
            },
          ]
        }
      }
    }
  };
}

Xác thực dữ liệu đã nhập vào các thẻ

Trang này giải thích cách xác thực dữ liệu đã nhập vào action của thẻ và tiện ích. Ví dụ: bạn có thể xác thực rằng trường nhập văn bản có văn bản được nhập bằng người dùng hoặc có chứa số lượng ký tự nhất định.

Đặt tiện ích bắt buộc cho các thao tác

Nằm trong action của thẻ, thêm tên của tiện ích mà một thao tác cần vào danh sách requiredWidgets.

Nếu bất kỳ tiện ích nào được liệt kê ở đây không có giá trị khi hành động này được gọi, thì lượt gửi hành động biểu mẫu sẽ bị huỷ.

Khi bạn đặt "all_widgets_are_required": "true" cho một thao tác, thì tất cả tiện ích trong thẻ thì phải thực hiện thao tác này.

Đặt một hành động all_widgets_are_required trong chế độ chọn nhiều mục

JSON

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "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
              }
            ]
          }
        }
      ]
    }
  ]
}
Đặt một hành động all_widgets_are_required trong dateTimePicker

JSON

{
  "sections": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "A datetime picker widget with both date and time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_and_time",
            "label": "meeting",
            "type": "DATE_AND_TIME"
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just date:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_only",
            "label": "Choose a date",
            "type": "DATE_ONLY",
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_time_only",
            "label": "Select a time",
            "type": "TIME_ONLY"
          }
        }
      ]
    }
  ]
}
Thiết lập một hành động all_widgets_are_required trong trình đơn thả xuống

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "text": "Red",
                "value": "red",
                "selected": false
              },
              {
                "text": "Green",
                "value": "green",
                "selected": false
              },
              {
                "text": "White",
                "value": "white",
                "selected": false
              },
              {
                "text": "Blue",
                "value": "blue",
                "selected": false
              },
              {
                "text": "Black",
                "value": "black",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

Đặt quy trình xác thực cho tiện ích nhập văn bản

Trong textInput trường xác thực của tiện ích, trường này có thể chỉ định giới hạn ký tự và loại dữ liệu đầu vào cho tiện ích nhập văn bản này.

Đặt giới hạn ký tự cho tiện ích nhập văn bản

JSON

{
  "sections": [
    {
      "header": "Tell us about yourself",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "favoriteColor",
            "label": "Favorite color",
            "type": "SINGLE_LINE",
            "validation": {"character_limit":15},
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        }
      ]
    }
  ]
}
Đặt loại dữ liệu nhập cho tiện ích nhập văn bản

JSON

{
  "sections": [
    {
      "header": "Validate text inputs by input types",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "mailing_address",
            "label": "Please enter a valid email address",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "EMAIL"
            },
            "onChangeAction": {
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "input_type": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

Khắc phục sự cố

Khi một ứng dụng Google Chat hoặc card trả về một lỗi, thì phương thức Giao diện Chat hiển thị một thông báo với nội dung "Đã 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ông báo lỗi nào ngoài ứng dụng Chat hoặc thẻ tạo 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 xuất hiện trong giao diện người dùng Chat, thông báo lỗi mô tả và dữ liệu nhật ký luôn có sẵn để giúp bạn sửa lỗi khi tính năng ghi nhật ký lỗi cho các ứng dụng trong Chat được bật. Để được trợ giúp xem, gỡ lỗi và sửa lỗi, hãy xem Khắc phục lỗi và khắc phục lỗi của Google Chat.