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

O widget Text Input permite que o complemento leia e reaja ao texto fornecido pelos usuários. Você pode configurar esses widgets para fornecer aos usuários sugestões automáticas para o texto de entrada.

As sugestões fornecidas podem vir de uma lista estática de strings que você fornece. Como alternativa, você pode criar as sugestões a partir do contexto, como o texto que o usuário já tenha digitado no widget.

Como configurar sugestões

A configuração de sugestões para uma entrada de texto exige apenas que você faça o seguinte:

  • Criar 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 a lista dinamicamente a partir do 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, o interface do aplicativo usa a lista estática até que o usuário comece a inserir caracteres, em que a função de callback é usada e a lista estática é ignorada.

Sugestões estáticas

Para oferecer uma lista estática de sugestões, você só precisa fazer o seguinte:

  1. Criar um Suggestions objeto.
  2. Adicione cada sugestão estática usando addSuggestion(). ou addSuggestions().
  3. Anexar o 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 que não diferencia maiúsculas de minúsculas e filtra a lista de sugestões enquanto o usuário digita caracteres no widget.

Ações da sugestão

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

  1. Crie um objeto Action. e associá-lo a uma função de callback definido por você.
  2. Chame o método TextInput.setSuggestionsAction() do widget. fornecendo a ela o objeto Action objeto.
  3. Implementar a função de callback para criar a lista de sugestões e retornar um SuggestionsResponse criado objeto.

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

A função de retorno de chamada deve retornar um valor SuggestionsResponse objeto que contém a lista de sugestões a serem exibidas. A interface exibe as sugestões na ordem em que são adicionadas. Ao contrário das listas estáticas, a interface não realiza nenhuma filtragem automática de sugestões de callback com base no usuário entrada. Para aplicar esse filtro, leia o valor de entrada de texto do objeto de evento e filtre suas sugestões conforme constrói a lista.

Exemplo

O seguinte snippet de código de complemento do Google Workspace mostra como configurar as sugestões em dois widgets diferentes de entrada de texto, o primeiro com uma lista estática e o segundo usando uma função de retorno de chamada:

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

Sugestões e OnChangeAction()

Os widgets de entrada de texto podem ter setOnChangeAction() definida, que é executada sempre que o widget perde o foco. Se esse gerenciador e as sugestões estiverem ativados para a mesma entrada de texto, o as regras a seguir definem o comportamento de interação da 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() será acionado novamente se o usuário, após selecionar um sugestão, edita-a para que não corresponda mais a nenhuma das sugestões na lista.
  4. Se o usuário não selecionar uma sugestão, setOnChangeAction() vai acionar quando a entrada de texto perde o foco.