Đề 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 để tự động cung cấp cho người dùng đề xuất về 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 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 nội dung đề xuất cho mục nhập văn bản, bạn chỉ cần làm như sau:

  • Tạo danh sách đề xuất bằng cách:
    • Tạo một danh sách tĩnh và/hoặc
    • Xác định một thao tác bằng hàm callback được 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 tĩnh các đề xuất 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ự, khi đó 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 đề xuất 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 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 các đề xuất đó. 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.

Thao tác đề 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 và 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 hàm đó là đối tượng Action.
  3. Triển khai hàm callback để tạo danh sách đề xuất và trả về đối tượng SuggestionsResponse đã tạo.

Giao diện người dùng gọi hàm callback bất cứ khi nào người dùng nhập một ký tự vào mục nhập văn bản, nhưng chỉ sau khi người dùng đã dừng nhập trong một thời gian. Hàm callback 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ề đối tượng SuggestionsResponse hợp lệ chứa danh sách các đề xuất để hiển thị. Giao diện người dùng cho thấy 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 tiến hành lọc tự động đề 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 áp dụng 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ã sau đây của Tiện ích bổ sung Google Workspace cho biết cách định cấu hình đề xuất trên 2 tiện ích nhập văn bản, thứ nhất với 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ẽ được 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 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() thực thi sau khi bạn chọn một đề xuất.
  2. Nếu người dùng nhấn Enter (hoặc làm cho mục 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.
  4. Nếu người dùng không chọn một đề xuất, setOnChangeAction() sẽ kích hoạt khi mục nhập văn bản mất đi tiêu điểm.