Sugerencias de autocompletado para entradas de texto

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

El widget de entrada de texto permite que el complemento lea y reaccione al texto que proporcionan los usuarios. Puedes configurar estos widgets a fin de proporcionar a los usuarios sugerencias automáticas para el texto de entrada.

Las sugerencias proporcionadas pueden provenir de una lista estática de strings que usted proporciona. Como alternativa, puedes compilar las sugerencias a partir de contexto, como el texto que el usuario ya escribió en el widget.

Configurar sugerencias

La configuración de sugerencias para una entrada de texto solo requiere que hagas lo siguiente:

  • Sigue estos pasos para crear una lista de sugerencias:
    • Crear una lista estática o
    • Definir una acción con una función de devolución de llamada que compila esa lista de forma dinámica a partir del contexto
  • Adjunta la lista de sugerencias o la acción al widget de entrada de texto.

Si proporcionas una lista estática de sugerencias y una acción, la IU de la aplicación usa la lista estática hasta que el usuario comienza a ingresar caracteres. Luego, se usa la función de devolución de llamada y se ignora la lista estática.

Sugerencias estáticas

Para ofrecer una lista estática de sugerencias, solo debes hacer lo siguiente:

  1. Crea un objeto Suggestions.
  2. Agrega cada sugerencia estática mediante addSuggestion() o addSuggestions().
  3. Adjunta el objeto Suggestions al widget mediante TextInput.setSuggestions().

La IU muestra sugerencias estáticas en el orden en que se agregaron. La IU también realiza automáticamente una coincidencia de prefijo que no distingue entre mayúsculas y minúsculas, y filtra la lista de sugerencias a medida que el usuario escribe los caracteres en el widget.

Acciones de sugerencia

Si no usas una lista de sugerencias estáticas, debes definir una acción para compilar las sugerencias de forma dinámica. Para hacerlo, debes seguir estos pasos:

  1. Crea un objeto Action y asócialo con una función de devolución de llamada que definas.
  2. Llama a la función TextInput.setSuggestionsAction() del widget y proporciónale el objeto Action.
  3. Implementa la función de devolución de llamada para compilar la lista de sugerencias y mostrar un objeto SuggestionsResponse compilado.

La IU llama a la función de devolución de llamada cada vez que el usuario escribe un carácter en la entrada de texto, pero solo después de que el usuario deja de escribir por un momento. La función de devolución de llamada recibe un objeto de evento que contiene información sobre los widgets de la tarjeta abierta. Consulta Objetos de eventos de acción para obtener más detalles.

La función de devolución de llamada debe mostrar un objeto SuggestionsResponse válido que contenga la lista de sugerencias que se mostrarán. La IU muestra sugerencias en el orden en que se agregan. A diferencia de las listas estáticas, la IU no realiza ningún filtro automático de sugerencias de devolución de llamada en función de la entrada del usuario. Si deseas tener ese filtrado, debes leer el valor de entrada de texto del objeto del evento y filtrar tus sugerencias a medida que construyes la lista.

Ejemplo

En el siguiente fragmento de código de Google Workspace complemento, se muestra cómo configurar sugerencias en dos widgets de entrada de texto diferentes: el primero con una lista estática y el segundo, con una función de devolución de llamada:

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

Sugerencias y OnChangeAction()

Los widgets de entrada de texto pueden tener una función de controlador setOnChangeAction() definida que se ejecute cada vez que el widget pierda el foco. Si este controlador y las sugerencias están habilitados para la misma entrada de texto, las siguientes reglas definen el comportamiento de interacción de la entrada de texto:

  1. El controlador setOnChangeAction() se ejecuta después de que se selecciona una sugerencia.
  2. Si el usuario presiona Intro (o de otro modo hace que la entrada de texto pierda el foco) sin modificar la sugerencia seleccionada, setOnChangeAction() no se vuelve a activar.
  3. setOnChangeAction() vuelve a activarse si el usuario, después de seleccionar una sugerencia, la edita para que ya no coincida con ninguna de las sugerencias de la lista.
  4. Si el usuario no selecciona una sugerencia, setOnChangeAction() se activa cuando la entrada de texto pierde el foco.