O widget Entrada de texto permite que o complemento leia e reaja ao texto fornecido pelos usuários. Esses widgets podem ser configurados para fornecer aos usuários sugestões automáticas de texto de entrada.
As sugestões fornecidas podem vir de uma lista estática de strings fornecidas. Como alternativa, é possível criar as sugestões com base no contexto, como o texto que o usuário já digitou no widget.
Como configurar sugestões
Para configurar sugestões para uma entrada de texto, faça o seguinte:
- Criar uma lista de sugestões da seguinte maneira:
- Criar uma lista estática e/ou
- Definição de uma ação com uma função de callback que cria essa 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, a interface do app vai usar a lista estática até o usuário começar a inserir caracteres, em que 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, você só precisa fazer o seguinte:
- Crie um objeto
Suggestions
. - Adicione cada sugestão estática usando
addSuggestion()
ouaddSuggestions()
. - Anexe o objeto
Suggestions
ao widget usandoTextInput.setSuggestions()
.
A IU exibe sugestões estáticas na ordem em que foram adicionadas. A interface também executa automaticamente a correspondência de prefixo que não diferencia maiúsculas de minúsculas e filtra a lista de sugestões conforme o usuário digita caracteres no widget.
Ações sugeridas
Se você não estiver usando uma lista de sugestões estática, será necessário definir uma ação para criar as sugestões dinamicamente. Para isso, siga as etapas abaixo:
- Crie um objeto
Action
e associe-o a uma função de callback definida por você. - Chame a função
TextInput.setSuggestionsAction()
do widget, fornecendo a ela o objetoAction
. - 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 evento de ação para mais detalhes.
A função de callback precisa retornar um objeto
SuggestionsResponse
válido que contém a lista de sugestões a serem exibidas. A interface mostra
sugestões na ordem em que são adicionadas. Ao contrário das listas estáticas, a interface não
conduz nenhuma filtragem automática de sugestões de callback com base na entrada
do usuário. Se você quiser usar esse tipo de filtragem, leia o valor de entrada de texto do objeto de evento e filtre as sugestões ao criar 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 com uma lista estática e o segundo usando 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 gerenciador 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, as
regras a seguir definirão o comportamento de interação de entrada de texto:
- O gerenciador
setOnChangeAction()
é executado depois que uma sugestão é selecionada. - Se o usuário pressionar Enter (ou fizer a entrada de texto perder o foco)
sem modificar a sugestão selecionada,
setOnChangeAction()
não será acionado novamente. - O
setOnChangeAction()
será acionado novamente se o usuário, depois de selecionar uma sugestão, editá-lo para que não corresponda mais a nenhuma das sugestões na lista. - Se o usuário não selecionar uma sugestão,
setOnChangeAction()
será acionado quando a entrada de texto perderá o foco.