Đề 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 các đề 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 tĩnh 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

Việc định cấu hình các đề xuất cho phương thức nhập văn bản chỉ yêu cầu bạn làm như 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 một thao tác bằng hàm callback có chức năng 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 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 tĩnh các đề xuất và hành động, 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ự, trong đó 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 đố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 cách sử dụ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 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ự động tạo đề xuất. 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 rồi liên kết đối tượng đó với một hàm callback mà bạn xác định.
  2. Gọi hàm TextInput.setSuggestionsAction() của tiện ích, cung cấp cho hàm đó đố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 sẽ gọi hàm callback bất cứ khi nào người dùng nhập một ký tự vào phương thức nhập văn bản, nhưng chỉ sau khi người dùng dừng nhập trong giây lát. Hàm callback sẽ 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ẻ mở. Hãy xem phần Đố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 đối tượng SuggestionsResponse hợp lệ có 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ự 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 hoạt động đầu vào của người dùng. Nếu muốn có cơ chế 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 của Google Workspace sau đây 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: tiện ích đầu tiên chứa danh sách tĩnh và tiện ích thứ hai 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()

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. Hàm này 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ý và các đề xuất này đều được bật cho cùng một mụ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 hệ thống chọn một đề xuất.
  2. Nếu người dùng nhấn phím Enter (hoặc làm cho nội dung nhập văn bản mất tiêu điểm) 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 sau khi chọn một đề xuất, hãy chỉnh sửa để không còn khớp với bất kỳ đề xuất nào trong danh sách nữa.
  4. Nếu người dùng không chọn một đề xuất, thì setOnChangeAction() sẽ kích hoạt khi nội dung nhập văn bản mất đi tiêu điểm.