Trang này giải thích cách thêm tiện ích và thành phần trên giao diện người dùng vào thẻ hoặc thông báo 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 nút hoặc gửi thông tin.
Sử dụng Trình tạo thẻ để thiết kế và xem trước thông báo trên thẻ JSON cho các ứng dụng trong Chat:
Mở Trình tạo thẻĐiều kiện tiên quyết
Thêm nút
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, biểu tượng hoặc cả văn bản và biểu tượng. Mỗi Button 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 bằng
OpenLinkđể cung cấp thêm thông tin cho người dùng. - Chạy
actioncó chức năng tuỳ chỉnh, chẳng hạn như gọi 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. Nút khác 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 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 có 2 nút. Một nút sử dụng trường Color để tuỳ chỉnh màu nền của nút đó. Nút còn lại bị 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 chức năng.
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 với 2 tiện ích biểu tượng Button. Một nút sử dụng trường knownIcon để hiển thị biểu tượng email tích hợp 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
Dưới đây là 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 biểu tượng hoặc nút văn bản để chạy hàm sendEmail.
Thêm các thành phần có thể chọn trên giao diện người dùng
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à thao tác khi thay đổi, chẳng hạn như 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.
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 làm việc với thông tin đầu vào của biểu mẫu, hãy xem phần Nhận dữ liệu biểu mẫu.
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
Cửa sổ sau đây sẽ cho thấy một hộp thoại yêu cầu người dùng chỉ định một người liên hệ là tính năng công việc, 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à người chuyên nghiệp hay cá nhân thông qua một tiện ích SelectionInput sử dụng các nút chọn:
Thêm một nút chuyể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à công việc, cá nhân hay cả hai thông qua một tiện ích SelectionInput sử dụng công tắc:
Thêm trình đơn thả xuống
Đoạn mã sau đây sẽ hiển thị một hộp thoại yêu cầu người dùng chỉ định một người liên hệ là người chuyên nghiệp hay cá nhân thông qua 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
Sau đây là hộp thoại yêu cầu người dùng chọn 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 đối tượng để điền dữ liệu từ các nguồn động, chẳng hạn như ứng dụng 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 một trình đơn chọn nhiều mục từ những nguồn dữ liệu sau trong Google Workspace:
- Người dùng Google Workspace: Bạn chỉ có thể điền sẵn 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 những không gian thuộc tổ chức của họ trên Google Workspace.
Để sử dụng 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 kiểu nhập 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 lấy nguồn tự độ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 chọn nhiều không gian trong Chat. Để điền dấu cách, dữ liệu đầu vào của lựa chọn sẽ chỉ định trường hostAppDataSource. Trình đơn chọn nhiều đối tượng 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
}
}
}
}
}
}
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 bên ngoài. Ví dụ: bạn có thể sử dụng trình đơn nhiều lựa chọn để giúp người dùng chọn trong 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).
Để sử 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 yêu cầu đến một 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 mục 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 danh bạ đượ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 các đối tượng SelectionItem.
Đoạn mã sau đây cho thấy trình đơn chọn nhiều mục trong một tập hợp danh bạ bên ngoài cho người dùng. Trình đơn hiển thị một địa chỉ 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 có sẵn các thành phố tại Hoa Kỳ, thì ứng dụng Chat có thể tự động đề xuất Atlanta trước khi người dùng nhập xong. 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 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 bằng trình đơn.
- Xác định rằng giá trị
invokedFunctioncủa sự kiện tương tác khớp với hàm trong trườngexternalDataSource. - Khi các hàm khớp, hãy trả về các mục đượ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 vào 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
thời điểm kích hoạt hàm getContacts:
Apps Script
Node.js
Thêm một 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 để 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 khi thay đổi, chẳng hạn như Actions. Các hành động này sẽ chạy khi có thay đổi xảy ra trong trường nhập văn bản, chẳng hạn như khi 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 của 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.
Sau đâ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ờ. 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 chính xác.
Để xử lý 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.
Sau đây là một thẻ bao gồm 3 loại tiện ích DateTimePicker:
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 được nhập vào action và tiện ích của thẻ.
Ví dụ: bạn có thể xác thực rằng một trường nhập dữ liệu văn bản có văn bản do người dùng nhập 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
Trong action của thẻ, hãy thêm tên của các tiện ích mà một hành động 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, thao tác này sẽ yêu cầu tất cả tiện ích trong thẻ đó.
Đặ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 trường xác thực của tiện ích textInput, trường đó 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 hoặc thẻ Google Chat trả về lỗi, giao diện Chat sẽ hiển thị một thông báo cho biết "Đã 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ẻ trong Chat lại 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 xuất hiện trong giao diện người dùng của 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 xem, gỡ lỗi và sửa lỗi, hãy xem bài viết Khắc phục sự cố và sửa lỗi Google Chat.