Đề 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à tương tác vớ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 đề xuất tự động cho người dùng văn bản nhập.

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

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

Việc định cấu hình đề xuất cho phương thức nhập văn bản chỉ yêu cầu bạn thực hiện sau:

  • Tạo danh sách các đề xuất bằng cách:
    • Tạo danh sách tĩnh và/hoặc
    • Xác định hành động bằng một hàm callback tạo danh sách động theo ngữ cảnh.
  • Đính kèm danh sách đề xuất và/hoặc hành động 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à hành động thì giao diện người dùng của ứng dụng sử dụng danh sách tĩnh cho đến khi người dùng bắt đầu nhập ký tự, Sau đó, hàm callback được sử dụng và danh sách tĩnh sẽ bị bỏ qua.

Đề xuất tĩnh

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

  1. Tạo một 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 Suggestions đối tượng cho tiện ích bằng TextInput.setSuggestions().

Giao diện người dùng hiển thị các đề xuất tĩnh theo thứ tự thêm vào. Giao diện người dùng cũng tự động thực hiện việc 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 hành động để tạo các đề 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 hàm đó với một hàm callback bạn xác định.
  2. Gọi TextInput.setSuggestionsAction() của tiện ích , cung cấp cho nó Action .
  3. Triển khai hàm callback để tạo danh sách đề xuất và trả về SuggestionsResponse bản dựng .

Giao diện người dùng sẽ gọi hàm callback mỗi khi người dùng nhập một ký tự vào nhưng chỉ sau khi người dùng đã dừng nhập trong giây lát. Chiến lược phát hành đĩa đơn hàm callback nhận một đối tượng sự kiện chứa thông tin về mở tiện ích của thẻ. Xem Đối tượng sự kiện hành động để biết thông tin chi tiết.

Hàm callback phải trả về một giá trị hợp lệ SuggestionsResponse chứa danh sách đề xuất hiển thị. Giao diện người dùng hiển thị đề 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 tiến hành lọc tự động các đề xuất gọi lại dựa trên người dùng đầu vào. Nếu muốn có bộ lọc như vậy, bạn phải đọc giá trị nhập văn bản từ đối tượng sự kiện và lọc các đề xuất khi bạn tạo danh sách.

Ví dụ:

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

// 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ó setOnChangeAction() hàm xử lý được xác định sẽ thực thi bất cứ khi nào tiện ích mất đi tiêu điểm. Nếu trình xử lý này và các đề xuất được bật cho cùng một mục nhập văn bản, thì các quy tắc sau đây 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 hệ thống chọn một đề xuất.
  2. Nếu người dùng nhấn Enter (hoặc làm cho việc nhập văn bản mất tiêu điểm) nếu không sửa đổi đề xuất đã chọn, 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 sau khi chọn một đề xuất, chỉnh sửa để 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 việc nhập văn bản mất tiêu điểm.