텍스트 입력 자동 완성 추천

텍스트 입력 위젯을 사용하면 부가기능이 사용자가 제공하는 텍스트를 읽고 반응할 수 있습니다. 사용자에게 입력 텍스트를 자동으로 추천하도록 이러한 위젯을 구성할 수 있습니다.

추천 검색어는 개발자가 제공하는 정적 문자열 목록에서 가져올 수 있습니다. 또는 사용자가 위젯에 이미 입력한 텍스트와 같은 컨텍스트에서 추천을 빌드할 수도 있습니다.

추천 구성

텍스트 입력에 대한 추천을 구성하려면 다음 작업만 수행하면 됩니다.

  • 다음 방법으로 추천 목록을 만듭니다.
    • 정적 목록 생성
    • 컨텍스트에서 동적으로 목록을 빌드하는 콜백 함수를 사용하여 작업을 정의합니다.
  • 추천 목록 또는 작업을 텍스트 입력 위젯에 첨부합니다.

정적 추천 목록과 작업을 모두 제공하면 애플리케이션 UI는 사용자가 문자를 입력하기 시작할 때까지 정적 목록을 사용합니다. 이때 콜백 함수가 사용되고 정적 목록은 무시됩니다.

정적 추천

정적인 추천 목록을 제공하려면 다음 작업만 수행하면 됩니다.

  1. Suggestions 객체를 만듭니다.
  2. addSuggestion() 또는 addSuggestions()를 사용하여 각 정적 추천을 여기에 추가합니다.
  3. TextInput.setSuggestions()를 사용하여 위젯에 Suggestions 객체를 연결합니다.

UI에는 정적 추천이 추가된 순서대로 표시됩니다. 또한 UI는 대소문자를 구분하지 않는 프리픽스 일치를 자동으로 실행하고 사용자가 위젯에 문자를 입력할 때 추천 목록을 필터링합니다.

추천 작업

정적 제안 목록을 사용하지 않는 경우 제안을 동적으로 빌드하는 작업을 정의해야 합니다. 다음 단계에 따라 무료 사용 기간을 연장할 수 있습니다.

  1. Action 객체를 만들어 정의한 콜백 함수와 연결합니다.
  2. 위젯의 TextInput.setSuggestionsAction() 함수를 호출하여 Action 객체를 제공합니다.
  3. 콜백 함수를 구현하여 추천 목록을 빌드하고 빌드된 SuggestionsResponse 객체를 반환합니다.

사용자가 텍스트 입력에 문자를 입력할 때마다 UI가 콜백 함수를 호출합니다. 사용자가 잠시 입력을 중지한 후에만 UI가 입력됩니다. 콜백 함수는 열린 카드의 위젯에 대한 정보가 포함된 이벤트 객체를 수신합니다. 자세한 내용은 작업 이벤트 객체를 참고하세요.

콜백 함수는 표시할 추천 검색어 목록이 포함된 유효한 SuggestionsResponse 객체를 반환해야 합니다. UI는 추가된 순서대로 추천을 표시합니다. 정적 목록과 달리 UI는 사용자 입력을 기반으로 콜백 추천을 자동 필터링하지 않습니다. 이러한 필터링을 하려면 이벤트 객체에서 텍스트 입력 값을 읽고 목록을 구성할 때 추천 항목을 필터링해야 합니다.

예

다음 Google Workspace 부가기능 코드 스니펫은 두 가지 텍스트 입력 위젯에서 추천을 구성하는 방법을 보여줍니다. 하나는 정적 목록을 사용하고 다른 하나는 콜백 함수를 사용합니다.

// 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!
 }

추천 및 OnChangeAction()

텍스트 입력 위젯에는 위젯이 포커스를 잃을 때마다 실행되는 setOnChangeAction() 핸들러 함수가 정의되어 있을 수 있습니다. 이 핸들러와 제안사항이 동일한 텍스트 입력에 모두 사용 설정된 경우 다음 규칙이 텍스트 입력 상호작용 동작을 정의합니다.

  1. 추천을 선택하면 setOnChangeAction() 핸들러가 실행됩니다.
  2. 사용자가 선택된 추천을 수정하지 않고 Enter 키를 누르거나 텍스트 입력에 포커스를 잃으면 setOnChangeAction()가 다시 트리거되지 않습니다.
  3. setOnChangeAction()는 사용자가 추천을 선택한 후 더 이상 목록의 추천과 일치하지 않도록 수정하면 다시 트리거됩니다.
  4. 사용자가 추천 검색어를 선택하지 않으면 텍스트 입력에 포커스가 없을 때 setOnChangeAction()가 트리거됩니다.