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

Các đề xuất được cung cấp có thể đến từ danh sách chuỗi tĩnh mà bạn cung cấp. Ngoài ra, bạn có thể tạo nội dung đề xuất từ 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 nội dung đề xuất

Để định cấu hình tính năng đề 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 theo:
    • Tạo danh sách tĩnh và/hoặc
    • Xác định một hành động bằng một hàm gọi lại 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 hành động, thì giao diện người dùng của ứng dụng sẽ 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 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 danh sách gợi ý tĩnh, bạn chỉ cần làm như sau:

  1. Tạo đối tượng Suggestions.
  2. Thêm từng đề xuất tĩnh vào bằng addSuggestion() hoặc addSuggestions().
  3. Gắn đối tượng Suggestions vào 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ự được thêm. 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 đề 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 gọi lại để 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 mỗi khi người dùng nhập một ký tự vào văn bản đầu vào, 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 được một đối tượng sự kiện chứa thông tin về các tiện ích của thẻ đang mở. Hãy xem phần Các đố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. Không giống như danh sách tĩnh, giao diện người dùng không thực hiện bất kỳ hoạt động lọc tự động nào đối với các đề xuất lệnh gọi lại dựa trên dữ liệu đầu vào của người dùng. 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 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 nội dung đề xuất trên hai 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 
 *  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()

Các tiện ích nhập văn bản có thể có một hàm 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ý và đề xuất này đề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 đây sẽ xác định hành vi tương tác với phương thứ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 Enter (hoặc làm mất tiêu điểm nhập văn bản) mà không sửa đổi nội dung đề 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, sau khi chọn một đề xuất, chỉnh sửa đề 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.