Đề xuất tự động hoàn thành cho mục nhập văn bản

Tiện ích Nhập văn bản cho phép tiện ích bổ sung của bạn đọc và phản hồi văn bản mà người dùng cung cấp. Bạn có thể định cấu hình các tiện ích này để cung cấp cho người dùng các đề xuất tự động cho văn bản đầu vào.

Các đề xuất được cung cấp có thể đến từ một danh sách tĩnh gồm các chuỗi mà bạn cung cấp. Ngoài ra, bạn có thể tạo các đề xuất dựa trên ngữ cảnh, chẳng hạn như văn bản mà người dùng đã nhập vào tiện ích.

Định cấu hình đề xuất

Để định cấu hình các đề xuất cho một mục nhập văn bản, bạn chỉ cần làm những việc sau:

  • Tạo danh sách đề xuất bằng cách:
    • Tạo danh sách tĩnh và/hoặc
    • Xác định một hành động bằng một hàm callback tạo danh sách đó một cách linh động từ ngữ cảnh.
  • Đính kèm danh sách đề xuất và/hoặc thao tác vào tiện ích nhập văn bản.

Nếu bạn cung cấp cả danh sách đề xuất tĩnh và một thao tác, thì giao diện người dùng ứng dụng sẽ sử dụng danh sách tĩnh cho đến khi người dùng bắt đầu nhập các ký tự, sau đó hàm gọi lại sẽ được sử dụng và danh sách tĩnh sẽ bị bỏ qua.

Đề xuất tĩnh

Để cung cấp một danh sách đề xuất tĩnh, bạn chỉ cần làm như sau:

  1. Tạo một đối tượng Suggestions.
  2. Thêm từng đề xuất tĩnh vào đó bằng cách sử dụng addSuggestion() hoặc addSuggestions().
  3. Đính kèm đối tượng Suggestions vào tiện ích bằng TextInput.setSuggestions().

Giao diện người dùng sẽ hiển thị các đề xuất tĩnh theo thứ tự mà chúng được thêm vào. Giao diện người dùng cũng tự động thực hiện so khớp tiền tố không phân biệt chữ hoa chữ thường và lọc danh sách đề xuất khi người dùng nhập các ký tự vào tiện ích.

Hành động đề xuất

Nếu không sử dụng danh sách đề xuất tĩnh, bạn phải xác định một thao tác để tạo đề xuất một cách linh động. Bạn có thể thực hiện việc này bằng cách làm theo các bước sau:

  1. Tạo một đối tượng Action và liên kết đối tượng đó với một hàm gọi lại mà bạn xác định.
  2. Gọi hàm TextInput.setSuggestionsAction() của tiện ích, cung cấp cho hàm này đối tượng Action.
  3. Triển khai hàm callback để tạo danh sách đề xuất và trả về một đối tượng SuggestionsResponse đã tạo.

Giao diện người dùng gọi hàm gọi lại bất cứ khi nào người dùng nhập một ký tự vào dữ liệu đầu vào văn bản, nhưng chỉ sau khi người dùng ngừng nhập một lúc. Hàm gọi lại nhận một đối tượng sự kiện chứa thông tin về các tiện ích của thẻ mở. Hãy xem Đối tượng sự kiện hành động để biết thông tin chi tiết.

Hàm gọi lại phải trả về một đối tượng SuggestionsResponse hợp lệ chứa danh sách các đề xuất cần hiển thị. Giao diện người dùng hiển thị các đề xuất theo thứ tự được thêm vào. Không giống như danh sách tĩnh, giao diện người dùng không tự động lọc các đề xuất lệnh gọi lại dựa trên thông tin đầu vào của người dùng. Nếu muốn có tính năng lọc như vậy, bạn phải đọc giá trị đầu vào văn bản từ đối tượng sự kiện và lọc các đề xuất khi tạo danh sách.

Ví dụ:

Đoạn mã tiện ích bổ sung Google Workspace sau đây cho biết cách định cấu hình các đề xuất trên 2 tiện ích nhập văn bản khác nhau, tiện ích đầu tiên có danh sách tĩnh và tiện ích thứ hai sử dụng hàm gọi lại:

// Create an input with a static suggestion list.
var textInput1 = CardService.newTextInput()
    .setFieldName('colorInput')
    .setTitle('Color choice')
    .setSuggestions(CardService.newSuggestions()
        .addSuggestion('Red')
        .addSuggestion('Yellow')
        .addSuggestions(['Blue', 'Black', 'Green']));

// Create an input with a dynamic suggestion list.
var action = CardService.newAction()
    .setFunctionName('refreshSuggestions');
var textInput2 = CardService.newTextInput()
    .setFieldName('emailInput')
    .setTitle('Email')
    .setSuggestionsAction(action);

// ...

/**
 *  Build and return a suggestion response. In this case, the suggestions
 *  are a list of emails taken from the To: and CC: lists of the open
 *  message in Gmail, filtered by the text that the user has already
 *  entered. This method assumes the Google Workspace
 *  add-on extends Gmail; the add-on only calls this method for cards
 *  displayed when the user has entered a message context.
 *
 *  @param {Object} e the event object containing data associated with
 *      this text input widget.
 *  @return {SuggestionsResponse}
 */
 function refreshSuggestions(e) {
   // Activate temporary Gmail scopes, in this case so that the
   // open message metadata can be read.
   var accessToken = e.gmail.accessToken;
   GmailApp.setCurrentMessageAccessToken(accessToken);

   var userInput = e && e.formInput['emailInput'].toLowerCase();
   var messageId = e.gmail.messageId;
   var message = GmailApp.getMessageById(messageId);

   // Combine the comma-separated returned by these methods.
   var addresses = message.getTo() + ',' + message.getCc();

   // Filter the address list to those containing the text the user
   // has already entered.
   var suggestionList = [];
   addresses.split(',').forEach(function(email) {
     if (email.toLowerCase().indexOf(userInput) !== -1) {
       suggestionList.push(email);
     }
   });
   suggestionList.sort();

   return CardService.newSuggestionsResponseBuilder()
       .setSuggestions(CardService.newSuggestions()
           .addSuggestions(suggestionList))
       .build();  // Don't forget to build the response!
 }

Đề xuất và OnChangeAction()

Tiện ích nhập văn bản có thể có một hàm trình xử lý setOnChangeAction() được xác định để thực thi bất cứ khi nào tiện ích mất tiêu điểm. Nếu trình xử lý này và các đề xuất đều được bật cho cùng một phương thức nhập văn bản, thì các quy tắc sau sẽ xác định hành vi tương tác nhập văn bản:

  1. Trình xử lý setOnChangeAction() sẽ thực thi sau khi một đề xuất được chọn.
  2. Nếu người dùng nhấn phím Enter (hoặc khiến dữ liệu đầu vào văn bản mất tiêu điểm theo cách khác) mà không sửa đổi đề xuất đã chọn, thì setOnChangeAction() sẽ không kích hoạt lại.
  3. setOnChangeAction() sẽ kích hoạt lại nếu người dùng chỉnh sửa một đề xuất đã chọn sao cho đề xuất đó không còn khớp với bất kỳ đề xuất nào trong danh sách.
  4. Nếu người dùng không chọn một đề xuất, setOnChangeAction() sẽ kích hoạt khi phương thức nhập văn bản mất tiêu điểm.