O campo autocomplete permite que você pesquise através de uma lista de opções.
A propriedade options pode aceitar três formatos diferentes de valores:
value e label (veja o exemplo acima)['A', 'B', 'C']{ a: 'A', b: 'B', c: 'C' }Se você atribuir opções como um array vazio, o campo será renderizado em um estado desabilitado.
Por padrão, o campo de autocompletar será renderizado no modo de seleção única:
Ao definir a propriedade multiple, o campo de autocompletar será renderizado no modo de seleção múltipla:
Note no exemplo acima que, porque a propriedade multiple está definida, a propriedade value deve ser um array.
O campo de autocompletar filtrará opções com sua própria função interna de busca. Você pode substituir essa função de busca fornecendo à propriedade filter uma função sua. Sua função receberá dois argumentos, a option que está sendo iterada e o valor atual de search:
Em vez de passar uma lista estática para a propriedade options, você pode atribuí-la a uma função. Fazer isso é útil quando você precisa carregar opções de uma API ou outra fonte.
Neste exemplo, vamos atribuir à propriedade options a função searchMovies. Ao fazer isso, searchMovies receberá o objeto context como argumento. Dentro deste objeto context está a propriedade search, que é o valor atual de busca. Para realizar nossa busca, usaremos o valor de busca como o parâmetro de consulta para nossa solicitação de API:
Um cenário provável que você encontrará é a necessidade de pesquisar através de uma API paginada. Isso pode ser feito referenciando o mesmo objeto context de antes. Dentro deste objeto, podemos utilizar as propriedades page e hasNextPage. A propriedade page é o número da página atual, e a propriedade hasNextPage é uma função a ser chamada quando houver mais páginas para carregar:
O input de autocomplete do FormKit também fornece uma propriedade optionLoader que permite reidratar valores que não estão na lista de opções. Neste exemplo, forneceremos ao autocomplete um valor inicial (um ID de filme) e atribuiremos o optionLoader a uma função que fará uma requisição à API para obter o filme:
Note no exemplo acima que a função optionLoader recebe dois argumentos: o value da opção selecionada (neste caso, o ID do filme) e o cachedOption. A propriedade cachedOption é usada para evitar buscas desnecessárias. Se o cachedOption não for null, significa que a opção selecionada já foi carregada, e você pode retornar o cachedOption diretamente.
Em vez de exigir que seus usuários cliquem no botão Carregar mais para carregar opções adicionais, você pode definir a propriedade loadOnScroll como verdadeira, o que paginará as opções à medida que você rolar até o final da lista de opções.
Se você preferir carregar opções quando o autocomplete for criado, você pode definir a propriedade load-on-created como verdadeira, e nossa função, loadCurrentlyPopularMovies, será chamada sem que o usuário precise expandir a lista:
O input de autocomplete permite que você personalize a aparência de cada opção usando o slot de opção. Neste exemplo, estamos usando o slot de opção para exibir o ativo de cada opção; logotipo e nome:
O input de autocomplete permite que você personalize a aparência da opção selecionada.
O campo de entrada do autocomplete permite que você personalize a aparência da opção selecionada usando a propriedade selection-appearance. Tanto para o autocomplete de seleção única quanto para o de múltipla seleção, você pode definir a propriedade selection-appearance para text-input (padrão) ou option:
Se você deseja apenas personalizar a exibição da opção selecionada, defina a aparência da seleção para option.
O campo de entrada do autocomplete, por padrão, não expandirá a caixa de listagem quando nenhum resultado de pesquisa for encontrado durante o filtro. Você pode alterar esse comportamento atribuindo à propriedade empty-message uma mensagem para exibir quando nenhum resultado for encontrado:
Se você deseja que a caixa de listagem permaneça expandida após selecionar um valor, você pode definir close-on-select para false.
Se você deseja que as opções sejam recarregadas quando o usuário confirmar uma seleção, use a propriedade reload-on-commit:
Para habilitar a abertura da caixa de listagem do autocomplete ao clicar em seu campo de pesquisa, defina a propriedade open-on-click para true:
Se você deseja abrir a caixa de listagem do autocomplete sempre que o campo de entrada for clicado, defina a propriedade open-on-focus para true:
Se open-on-focus for usado, open-on-click será implicitamente definido.
Apenas para autocompletes de seleção única, se você deseja limpar o campo de pesquisa quando a lista é aberta, defina a propriedade clear-search-on-open:
Para um autocomplete de seleção única, você pode definir a propriedade selection-removable. Quando definida como true, um botão de remover será exibido ao lado da opção selecionada. Esta propriedade é por padrão definida como true para autocompletes com aparência de seleção de option.
A propriedade selection-removable não pode ser usada para seleções múltiplas.
Se você deseja que a lista se expanda quando uma seleção for removida, use a propriedade open-on-remove:
Se você deseja limitar o número de opções que podem ser selecionadas, você pode usar a propriedade max:
Agora vamos combinar o que aprendemos até agora, utilizando o slot option para marcação personalizada, e definindo a propriedade options para uma função que retornará páginas de filmes de uma API:
| Prop | Type | Padrão | Descrição |
|---|---|---|---|
| debounce | number | 200 | Número de milissegundos para atrasar chamadas a uma função de opções. |
| options | any | [] | A lista de opções que o usuário pode selecionar. |
| load-on-scroll | boolean | false | Quando definido como `true`, o autocomplete tentará carregar mais opções com base na posição de rolagem do usuário final |
| selection-appearance | string | text-input | Altera a maneira como o rótulo da opção é exibido. |
| multiple | boolean | false | Permite seleções múltiplas. |
| open-on-click | boolean | false | O autocomplete é expandido ao focar no campo de entrada, ao contrário de esperar para expandir até que um valor de pesquisa seja inserido. |
| filter | function | null | Usado para aplicar sua própria função de filtro personalizada para opções estáticas. |
| option-loader | function | null | Usado para hidratar o valor inicial ou realizar uma solicitação adicional para carregar mais informações de uma opção selecionada. |
| empty-message | string | undefined | Exibe uma mensagem quando não há opções para mostrar. |
| max | number | undefined | Limita o número de opções que podem ser selecionadas. |
| open-on-remove | boolean | false | Quando a propriedade `selection-removable` está definida como `true`, o autocomplete não abrirá após o valor selecionado ser removido. Você pode alterar esse comportamento definindo a propriedade `open-on-remove` como `true`. |
| open-on-focus | boolean | false | |
| options-appearance | string | undefined | Para autocompletes de seleção múltipla, esta propriedade permite personalizar a aparência das opções selecionadas. Os valores possíveis são `default` (o padrão) ou `checkbox`. |
| always-load-on-open | boolean | true | Determina se o autocomplete deve sempre carregar suas opções quando aberto ou se deve referenciar as opções que foram previamente encontradas ao abrir. |
| load-on-created | boolean | false | Quando definido como `true`, o autocomplete carregará as opções quando o nó for criado. |
| clear-search-on-open | boolean | false | Quando definido como `true`, o campo de pesquisa será limpo quando a lista for aberta. |
| max | number | string | undefined | Se você deseja limitar o número de opções que podem ser selecionadas, você pode usar a propriedade `max` (aplica-se apenas a seleção múltipla). |
| popover | boolean | false | Renderiza a lista do campo de entrada usando a API Popover do navegador. |
| Mostrar Universal props | |||
| config | Object | {} | Opções de configuração a serem fornecidas para o nó do input e qualquer nó descendente deste input. |
| delay | Number | 20 | Número de milissegundos para debounce do valor do input antes de despachar o commit hook. |
| dirtyBehavior | string | touched | Determina como o indicador "dirty" deste input é definido. Pode ser configurado como touched ou compare - touched (o padrão) é mais performático, mas não detectará quando o formulário corresponder novamente ao seu estado inicial. |
| errors | Array | [] | Array de strings para exibir como mensagens de erro neste campo. |
| help | String | '' | Texto para o texto de ajuda associado ao input. |
| id | String | input_{n} | O ID único do input. Fornecer um ID também permite acesso global ao nó do input. |
| ignore | Boolean | false | Impede que um input seja incluído em qualquer pai (grupo, lista, formulário etc). Útil ao usar inputs para a interface do usuário em vez de valores reais. |
| index | Number | undefined | Permite que um input seja inserido no índice fornecido, se o pai for uma lista. Se o valor do input for indefinido, ele herda o valor dessa posição de índice. Se ele tiver um valor, ele o insere nos valores da lista no índice fornecido. |
| label | String | '' | Texto para o elemento label associado ao input. |
| name | String | input_{n} | O nome do input como identificado no objeto de dados. Isso deve ser único dentro de um grupo de campos. |
| parent | FormKitNode | contextual | Por padrão, o pai é um grupo, lista ou formulário de envolvimento, mas essa prop permite a atribuição explícita do nó pai. |
| prefix-icon | String | '' | Especifica um ícone para colocar na seção prefixIcon. |
| preserve | boolean | false | Preserva o valor do input em um grupo pai, lista ou formulário quando o input é desmontado. |
| preserve-errors | boolean | false | Por padrão, os erros definidos em inputs usando setErrors são automaticamente limpos no input. Definir essa prop como true mantém o erro até que ele seja explicitamente limpo. |
| sections-schema | Object | {} | Um objeto de chaves de seção e valores parciais de esquema, em que cada esquema parcial é aplicado à seção respectiva. |
| suffix-icon | String | '' | Especifica um ícone para colocar na seção suffixIcon. |
| type | String | text | O tipo de input a ser renderizado pela biblioteca. |
| validation | String, Array | [] | As regras de validação a serem aplicadas ao input. |
| validation-visibility | String | blur | Determina quando mostrar as regras de validação com falha de um input. Os valores válidos são blur, dirty e live. |
| validation-label | String | {label prop} | Determina qual rótulo usar nas mensagens de erro de validação, por padrão, usa a propriedade label, se disponível, caso contrário, usa a propriedade name. |
| validation-rules | Object | {} | Regras de validação personalizadas adicionais para disponibilizar na propriedade de validação. |
| value | Any | undefined | Inicializa o valor do input e/ou de seus filhos. Não é reativo. Pode inicializar grupos inteiros (formulários) e listas.. |
Você pode direcionar uma seção específica de uma entrada usando a "key" dessa seção, permitindo que você modifique as classes, HTML (por meio de :sections-schema ou o conteúdo (por meio de slots) dessa seção). Saiba mais sobre as seções aqui.
A estrutura do autocompletar muda dependendo de alguns cenários diferentes:
selection-appearance foi definido como text-input (o padrão) ou option.multiple.text-inputoption, seleção únicaoption, seleção múltiplaAbaixo está a estrutura da lista de opções interna (listbox) dos diagramas acima:
| Section-key | Descrição |
|---|---|
| selector | A seção do seletor é um elemento botão que abre a lista de opções do dropdown. |
| selections | Contém seções de seleção individuais. |
| selection | Contém a opção selecionada. |
| listitem | Um elemento de item de lista que contém a seção de opção. |
| option | Uma div que contém o conteúdo da opção. |
| listbox | A seção listbox é um elemento ul que contém a lista de opções. |
| dropdownWrapper | Envolve a seção listbox. Uma div que gerencia a rolagem da listbox. |
| optionLoading | Um elemento span que é renderizado condicionalmente dentro da opção selecionada quando o carregamento está ocorrendo. |
| loaderIcon | Um elemento para exibir um ícone no elemento seletor quando o carregamento está ocorrendo. |
| selectIcon | Um elemento para exibir um ícone no elemento seletor quando o dropdown está fechado. |
| loadMore | Um elemento de item de lista que é renderizado condicionalmente na parte inferior da lista de opções quando há mais páginas para carregar. |
| loadMoreInner | Um elemento span que atua como um invólucro para o loaderIcon dentro da seção loadMore. |
| removeSelection | Um elemento botão usado para remover uma seleção específica. |
| closeIcon | Um elemento para exibir um ícone dentro do botão removeSelection. |
| listboxButton | Um elemento botão que é usado para abrir o dropdown. |
| emptyMessage | Um elemento de item de lista que é renderizado condicionalmente quando não há opções para exibir. |
| emptyMessageInner | Um elemento span que atua como um invólucro para a seção emptyMessage. |
| Mostrar Universal section keys | |
| outer | O elemento de envolvimento mais externo. |
| wrapper | Um invólucro ao redor do rótulo e do input. |
| label | O rótulo do input. |
| prefix | Por padrão, não gera saída, mas permite conteúdo diretamente antes de um elemento input. |
| prefixIcon | Um elemento para gerar um ícone antes da seção de prefixo. |
| inner | Um invólucro ao redor do próprio elemento input. |
| suffix | Por padrão, não gera saída, mas permite conteúdo diretamente após um elemento input. |
| suffixIcon | Um elemento para gerar um ícone após a seção de sufixo. |
| input | O próprio elemento input. |
| help | O elemento que contém o texto de ajuda. |
| messages | Um invólucro ao redor de todas as mensagens. |
| message | O elemento (ou muitos elementos) que contém uma mensagem - na maioria das vezes mensagens de validação e erros. |
Todos os campos de entrada do FormKit são projetados com as seguintes considerações de acessibilidade em mente. Ajude-nos a melhorar continuamente a acessibilidade para todos, relatando problemas de acessibilidade aqui:
| Chave de Seção | Atributo | Padrão | Descrição |
|---|---|---|---|
| input | tabindex | -1 ou 0 | Prioriza a ordem de foco do teclado definindo-a para -1 quando desativado e 0 quando ativado. |
| role | combobox | Indica às tecnologias assistivas que este elemento funciona como uma caixa de combinação. | |
| readonly | Restringe edições do usuário, garantindo a integridade dos dados e uma experiência de usuário controlada e informativa. | ||
| aria-autocomplete | list | Orienta sugestões de entrada, apresentando uma coleção de valores que poderiam completar a entrada do usuário. | |
| aria-activedescendant | Gerencia o foco para o elemento descendente ativo atual. | ||
| aria-expanded | Transmite o estado expansível quando o elemento está em foco. | ||
| aria-controls | Associa o elemento listbox, com este elemento. | ||
| listboxButton | tabindex | -1 ou 0 | Prioriza a ordem de foco do teclado definindo-a para -1 quando desativado e 0 quando ativado. |
| role | button | Indica às tecnologias assistivas que este elemento funciona como um botão. | |
| aria-haspopup | true | Sinaliza que um elemento aciona um pop-up ou menu | |
| aria-expanded | Transmite o estado expansível quando o elemento está em foco. | ||
| aria-controls | Associa o elemento listbox, com este elemento. | ||
| aria-disabled | Comunica o estado desativado quando a entrada está desativada. | ||
| selectionWrapper | tabindex | -1 ou 0 | Prioriza a ordem de foco do teclado definindo-a para -1 quando desativado e 0 quando ativado. |
| selections | aria-live | polite | Comunica mudanças de conteúdo dinâmico quando seleções estão na tela. |
| removeSelection | tabindex | -1 | Remove a priorização do foco do teclado neste elemento. |
| aria-controls | Associa o elemento de entrada, com este elemento. | ||
| Mostrar Universal chave de seção | |||
| label | label | for | Associa isso a um elemento de entrada, aprimorando acessibilidade e experiência do usuário |
| input | input | disabled | Desabilita um elemento HTML, impedindo a interação do usuário e sinalizando um estado não interativo |
| aria-describedby | Aprimora a acessibilidade associando um elemento a uma descrição, auxiliando leitores de tela | ||
| aria-required | Adiciona o estado necessário quando a validação é exigida. | ||
| icon | icon | for | Sempre que um ícone é definido como rótulo, ele o vincula a um elemento de entrada, aprimorando acessibilidade e experiência do usuário |
| Evento de Teclado | Descrição |
|---|---|
| Tab | Move o foco para a próxima entrada focalizável na página. |
| Shift + Tab | Move o foco para a entrada focalizável anterior na página. |