Sugestões de preenchimento automático para entradas de texto

Com o widget Entrada de texto, seu complemento pode ler e reagir ao texto fornecido pelos usuários. É possível configurar esses widgets para oferecer aos usuários sugestões automáticas de texto de entrada.

As sugestões podem vir de uma lista estática de strings fornecida por você. Como alternativa, você pode criar as sugestões com base no contexto, como o texto que o usuário já digitou no widget.

Configurar sugestões

Para configurar sugestões para uma entrada de texto, basta fazer o seguinte:

• Crie uma lista de sugestões por:
  • Criar uma lista estática e/ou
  • Definir uma ação com uma função de callback que cria essa lista dinamicamente com base no contexto.
• Anexe a lista de sugestões e/ou a ação ao widget de entrada de texto.

Se você fornecer uma lista estática de sugestões e uma ação, a interface do aplicativo usará a lista estática até que o usuário comece a inserir caracteres, quando a função de callback será usada e a lista estática será ignorada.

Sugestões estáticas

Para oferecer uma lista estática de sugestões, basta fazer o seguinte:

1. Crie um objeto Suggestions.
2. Adicione cada sugestão estática usando addSuggestion() ou addSuggestions().
3. Anexe o objeto Suggestions ao widget usando TextInput.setSuggestions().

A interface mostra sugestões estáticas na ordem em que foram adicionadas. A interface também realiza automaticamente a correspondência de prefixos sem diferenciação de maiúsculas e minúsculas e filtra a lista de sugestões conforme o usuário digita caracteres no widget.

Ações de sugestão

Se você não estiver usando uma lista de sugestões estática, defina uma ação para criar sugestões de forma dinâmica. Para isso, siga as seguintes etapas:

1. Crie um objeto Action e associe-o a uma função de callback que você definir.
2. Chame a função TextInput.setSuggestionsAction() do widget, fornecendo o objeto Action.
3. Implemente a função de callback para criar a lista de sugestões e retornar um objeto SuggestionsResponse criado.

A interface chama a função de callback sempre que o usuário digita um caractere na entrada de texto, mas somente depois que ele para de digitar por um momento. A função de callback recebe um objeto de evento com informações sobre os widgets do card aberto. Consulte Objetos de eventos de ação para mais detalhes.

A função de callback precisa retornar um objeto SuggestionsResponse válido que contenha a lista de sugestões a serem mostradas. A interface mostra sugestões na ordem em que são adicionadas. Ao contrário das listas estáticas, a interface não faz filtragem automática das sugestões de callback com base na entrada do usuário. Se você quiser esse tipo de filtragem, leia o valor da entrada de texto do objeto de evento e filtre suas sugestões ao construir a lista.

Exemplo

O snippet de código do complemento do Google Workspace a seguir mostra como configurar sugestões em dois widgets de entrada de texto diferentes. O primeiro usa uma lista estática e o segundo usa uma função de 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!
 }

Sugestões e OnChangeAction()

Os widgets de entrada de texto podem ter uma função de manipulador setOnChangeAction() definida que é executada sempre que o widget perde o foco. Se esse manipulador e as sugestões estiverem ativados para a mesma entrada de texto, as regras a seguir vão definir o comportamento da interação de entrada de texto:

1. O gerenciador setOnChangeAction() é executado depois que uma sugestão é selecionada.
2. Se o usuário pressionar "Enter" (ou fizer com que a entrada de texto perca o foco) sem modificar a sugestão selecionada, o setOnChangeAction() não será acionado novamente.
3. setOnChangeAction() é acionado novamente se o usuário, depois de selecionar uma sugestão, a editar para que ela não corresponda mais a nenhuma das sugestões na lista.
4. Se o usuário não selecionar uma sugestão, setOnChangeAction() será acionado quando a entrada de texto perder o foco.