텍스트 입력 자동 완성 추천

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

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

추천 구성

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

• 다음과 같이 추천 목록을 만듭니다.
  • 정적 목록 만들기
  • 컨텍스트에서 동적으로 목록을 빌드하는 콜백 함수로 작업을 정의합니다.
• 추천 목록 또는 작업을 텍스트 입력 위젯에 연결합니다.

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

정적 추천

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

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

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

추천 작업

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

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

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 
 *  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()이 트리거됩니다.