Giá trị nhập vào lựa 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, công tắc 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.


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

Mở Trình tạo thẻ

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 là Actions sẽ chạy khi có thay đổi 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.

Ví dụ

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:

Ví dụ 1: 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ệ có phải là chuyên gia và/hoặc cá nhân hay không bằng tiện ích SelectionInput sử dụng hộp đánh dấu:

Ví dụ 2: 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:

Ví dụ 3: 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à chuyên nghiệp hay cá nhân bằng tiện ích SelectionInput sử dụng công tắc:

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à cá nhân hay là công việc bằng tiện ích SelectionInput sử dụng trình đơn thả xuống:

Ví dụ 5: 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:

Nguồn dữ liệu bổ sung 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
            },
          ]
        }
      }
    }
  };
}

Biểu diễn JSON và các trường

Biểu diễn dưới dạng JSON
{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  },
  "multiSelectMaxSelectedItems": integer,
  "multiSelectMinQueryLength": integer,

  // Union field multi_select_data_source can be only one of the following:
  "externalDataSource": {
    object (Action)
  },
  "platformDataSource": {
    object (PlatformDataSource)
  }
  // End of list of possible types for union field multi_select_data_source.
}
Trường
name

string

Tên xác định mục nhập lựa chọn trong một sự kiện nhập biểu mẫu.

Để biết thông tin chi tiết về cách xử lý thông tin nhập vào biểu mẫu, hãy xem phần Nhận dữ liệu biểu mẫu.

label

string

Văn bản xuất hiện phía trên trường nhập dữ liệu lựa chọn trong giao diện người dùng.

Chỉ định văn bản giúp người dùng nhập thông tin mà ứng dụng của bạn cần. Ví dụ: nếu người dùng đang chọn mức độ khẩn cấp của phiếu yêu cầu làm việc trong trình đơn thả xuống, thì nhãn có thể là "Khẩn cấp" hoặc "Chọn tính khẩn cấp".

type

enum (SelectionType)

Loại mục mà người dùng nhìn thấy trong tiện ích SelectionInput. Các loại lựa chọn hỗ trợ nhiều loại tương tác. Ví dụ: người dùng có thể chọn một hoặc nhiều hộp đánh dấu, nhưng chỉ có thể chọn một giá trị trong trình đơn thả xuống.

items[]

object (SelectionItem)

Một dãy các mục có thể chọn. Ví dụ: một dãy các nút chọn hoặc hộp đánh dấu. Hỗ trợ tối đa 100 mục.

onChangeAction

object (Action)

Nếu được chỉ định, biểu mẫu sẽ được gửi khi lựa chọn thay đổi. Nếu không chỉ định, bạn phải chỉ định một nút riêng dùng để gửi biểu mẫu.

Để biết thông tin chi tiết về cách xử lý thông tin nhập vào biểu mẫu, hãy xem phần Nhận dữ liệu biểu mẫu.

multiSelectMaxSelectedItems

integer

Đối với trình đơn chọn nhiều mục, số lượng mục tối đa mà người dùng có thể chọn. Giá trị tối thiểu là 1 mục. Nếu không chỉ định, giá trị mặc định sẽ là 3 mục.

multiSelectMinQueryLength

integer

Đối với các trình đơn chọn nhiều mục, số lượng ký tự văn bản mà người dùng nhập trước khi ứng dụng Chat tự động hoàn thành các truy vấn và hiển thị các mục đề xuất trong trình đơn.

Nếu không chỉ định thì giá trị mặc định sẽ là 0 ký tự đối với nguồn dữ liệu tĩnh và 3 ký tự đối với nguồn dữ liệu bên ngoài.

Trường hợp multi_select_data_source. Đối với trình đơn chọn nhiều mục, nguồn dữ liệu sẽ điền sẵn các mục lựa chọn.

Các ứng dụng Google Chat : multi_select_data_source chỉ có thể là một trong những ứng dụng sau:

externalDataSource

object (Action)

Một nguồn dữ liệu bên ngoài, chẳng hạn như cơ sở dữ liệu quan hệ.

platformDataSource

object (PlatformDataSource)

Một nguồn dữ liệu từ Google Workspace.

SelectionType

Enum
CHECK_BOX Một tập hợp các hộp đánh dấu. Người dùng có thể chọn một hoặc nhiều hộp đánh dấu.
RADIO_BUTTON Một nhóm các nút chọn. Người dùng có thể chọn một nút chọn.
SWITCH Một bộ công tắc. Người dùng có thể bật một hoặc nhiều công tắc.
DROPDOWN Trình đơn thả xuống. Người dùng có thể chọn một mục trong trình đơn.
MULTI_SELECT

Trình đơn chọn nhiều mục cho dữ liệu tĩnh hoặc động. Trên thanh trình đơn, người dùng có thể chọn một hoặc nhiều mục. Người dùng cũng có thể nhập các giá trị để điền dữ liệu động. Ví dụ: Người dùng có thể bắt đầu nhập tên của một phòng trò chuyện trong Google Chat và tiện ích sẽ tự động đề xuất không gian đó.

Để điền sẵn các mục cho trình đơn chọn nhiều mục, bạn có thể sử dụng một trong các loại nguồn dữ liệu sau:

  • Dữ liệu tĩnh: Các mục được chỉ định làm đối tượng SelectionItem trong tiện ích. Tối đa 100 mục.
  • Dữ liệu trong Google Workspace: Các mục được điền sẵn bằng dữ liệu trên Google Workspace, chẳng hạn như người dùng Google Workspace hoặc phòng trò chuyện trong Google Chat.
  • Dữ liệu bên ngoài: Các mục được điền từ một nguồn dữ liệu bên ngoài Google Workspace.

Để biết ví dụ về cách triển khai trình đơn nhiều chọn, hãy xem trang tiện ích SelectionInput .

Ứng dụng Google Chat :

SelectionItem

Biểu diễn dưới dạng JSON
{
  "text": string,
  "value": string,
  "selected": boolean,
  "startIconUri": string,
  "bottomText": string
}
Trường
text

string

Văn bản giúp nhận dạng hoặc mô tả mặt hàng cho người dùng.

value

string

Giá trị được liên kết với mục này. Ứng dụng nên sử dụng giá trị này làm giá trị nhập vào biểu mẫu.

Để biết thông tin chi tiết về cách xử lý thông tin nhập vào biểu mẫu, hãy xem phần Nhận dữ liệu biểu mẫu.

selected

boolean

Liệu mục đó có được chọn theo mặc định hay không. Nếu dữ liệu đầu vào của lựa chọn chỉ chấp nhận một giá trị (chẳng hạn như các nút chọn hoặc trình đơn thả xuống), hãy chỉ đặt trường này cho một mục.

startIconUri

string

Đối với các trình đơn chọn nhiều mục, URL cho biểu tượng xuất hiện bên cạnh trường text của mục. Hỗ trợ các tệp PNG và JPEG. Bạn phải dùng một URL HTTPS. Ví dụ: https://developers.google.com/chat/images/quickstart-app-avatar.png.

bottomText

string

Đối với các trình đơn chọn nhiều mục, nội dung mô tả bằng văn bản hoặc nhãn xuất hiện bên dưới trường text của mục.

Hành động

Hành động mô tả hành vi khi biểu mẫu được gửi. Ví dụ: bạn có thể gọi một tập lệnh Apps Script để xử lý biểu mẫu. Nếu hành động được kích hoạt, các giá trị của biểu mẫu được gửi đến máy chủ.

Dùng được trong các ứng dụng Google Chat và tiện ích bổ sung của Google Workspace.

Biểu diễn dưới dạng JSON
{
  "function": string,
  "parameters": [
    {
      object (ActionParameter)
    }
  ],
  "loadIndicator": enum (LoadIndicator),
  "persistValues": boolean,
  "interaction": enum (Interaction)
}
Trường
function

string

Một hàm tuỳ chỉnh để gọi khi phần tử chứa được nhấp hoặc kích hoạt theo chiều ngang.

Để tham khảo ví dụ về cách sử dụng, hãy xem phần Tạo thẻ tương tác.

parameters[]

object (ActionParameter)

Danh sách thông số hành động.

loadIndicator

enum (LoadIndicator)

Chỉ định chỉ báo đang tải mà hành động hiển thị trong khi thực hiện lệnh gọi hành động.

persistValues

boolean

Cho biết liệu các giá trị biểu mẫu có còn tồn tại sau hành động hay không. Giá trị mặc định là false.

Nếu là true, các giá trị biểu mẫu sẽ vẫn còn sau khi hành động được kích hoạt. Để cho phép người dùng thực hiện các thay đổi trong khi thao tác đang được xử lý, hãy đặt LoadIndicator thành NONE. Đối với tin nhắn thẻ trong ứng dụng Chat, bạn cũng phải đặt ResponseType của thao tác thành UPDATE_MESSAGE và sử dụng cùng một cardId từ thẻ chứa thao tác đó.

Nếu là false, các giá trị của biểu mẫu sẽ bị xoá khi hành động được kích hoạt. Để ngăn người dùng thực hiện các thay đổi trong khi thao tác đang được xử lý, hãy đặt LoadIndicator thành SPINNER.

interaction

enum (Interaction)

Không bắt buộc. Bắt buộc khi mở một hộp thoại.

Việc cần làm để phản hồi tương tác với người dùng, chẳng hạn như khi người dùng nhấp vào nút trong thông báo trên thẻ.

Nếu không chỉ định, ứng dụng sẽ phản hồi bằng cách thực thi một action (chẳng hạn như mở một đường liên kết hoặc chạy một hàm) như bình thường.

Bằng cách chỉ định interaction, ứng dụng có thể phản hồi theo những cách tương tác đặc biệt. Ví dụ: bằng cách đặt interaction thành OPEN_DIALOG, ứng dụng có thể mở một hộp thoại. Khi được chỉ định, chỉ báo tải sẽ không hiển thị. Nếu được chỉ định cho tiện ích bổ sung, toàn bộ thẻ sẽ bị xoá và không có nội dung nào hiển thị trong ứng dụng.

Ứng dụng Google Chat :

ActionParameter

Danh sách các tham số chuỗi cần cung cấp khi phương thức hành động được gọi. Ví dụ: xem xét 3 nút tạm ẩn: tạm ẩn ngay bây giờ, tạm ẩn một ngày hoặc tạm ẩn vào tuần tới. Bạn có thể sử dụng action method = snooze() để truyền loại tạm ẩn và thời gian tạm ẩn trong danh sách các tham số chuỗi.

Để tìm hiểu thêm, hãy xem CommonEventObject.

Dùng được trong các ứng dụng Google Chat và tiện ích bổ sung của Google Workspace.

Biểu diễn dưới dạng JSON
{
  "key": string,
  "value": string
}
Trường
key

string

Tên của thông số cho tập lệnh hành động.

value

string

Giá trị của thông số.

LoadIndicator

Chỉ định chỉ báo đang tải mà hành động hiển thị trong khi thực hiện lệnh gọi hành động.

Dùng được trong các ứng dụng Google Chat và tiện ích bổ sung của Google Workspace.

Enum
SPINNER Hiện một vòng quay để cho biết nội dung đang tải.
NONE Không có gì hiển thị.

Tương tác

Không bắt buộc. Bắt buộc khi mở một hộp thoại.

Việc cần làm để phản hồi tương tác với người dùng, chẳng hạn như khi người dùng nhấp vào nút trong thông báo trên thẻ.

Nếu không chỉ định, ứng dụng sẽ phản hồi bằng cách thực thi một action (chẳng hạn như mở một đường liên kết hoặc chạy một hàm) như bình thường.

Bằng cách chỉ định interaction, ứng dụng có thể phản hồi theo những cách tương tác đặc biệt. Ví dụ: bằng cách đặt interaction thành OPEN_DIALOG, ứng dụng có thể mở một hộp thoại.

Khi được chỉ định, chỉ báo tải sẽ không hiển thị. Nếu được chỉ định cho tiện ích bổ sung, toàn bộ thẻ sẽ bị xoá và không có nội dung nào hiển thị trong ứng dụng.

Ứng dụng Google Chat :

Enum
INTERACTION_UNSPECIFIED Giá trị mặc định. action thực thi như bình thường.
OPEN_DIALOG

Mở một hộp thoại – giao diện dạng thẻ có cửa sổ mà các ứng dụng trong Chat dùng để tương tác với người dùng.

Chỉ được các ứng dụng trong Chat hỗ trợ khi người dùng nhấp vào nút trên tin nhắn trong thẻ. Nếu được chỉ định cho tiện ích bổ sung, toàn bộ thẻ sẽ bị xoá và không có nội dung nào hiển thị trong ứng dụng.

Ứng dụng Google Chat :

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.