A entrada taglist permite que os usuários pesquisem em uma lista de opções e apliquem qualquer número de tags. Os usuários também podem arrastar e soltar tags para reordenar:
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, a entrada será renderizada em um estado desabilitado.
A entrada taglist permite que os usuários pesquisem em uma lista de opções e apliquem qualquer número de tags. Os usuários também podem arrastar e soltar tags para reordenar:
A entrada de lista de tags filtrará opções com sua própria função de busca interna. 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:
A entrada de lista de tags, ao contrário das entradas de dropdown ou autocomplete, permite que você insira um valor arbitrário (um valor que não está na lista de opções). Isso é útil para criar novas tags na hora. Para habilitar esse recurso, defina a propriedade allow-new-values como true.
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 search 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:
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 irá paginar as opções à medida que você rola até o final da lista de opções.
O input de taglist 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 taglist um valor inicial (um ID de filme) e atribuiremos o optionLoader a uma função que fará uma solicitaçã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. O cachedOption é usado para evitar pesquisas 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 irá paginar as opções à medida que você rola até o final da lista de opções.
Se você preferir carregar opções quando o taglist for criado, você pode definir a propriedade load-on-created como verdadeira, e nossa função, loadCurrentlyPopularMovies, será chamada sem a necessidade do usuário expandir a caixa de listagem:
Assim como no input de taglist ou input de Autocomplete, o input de taglist permite que você utilize slots para personalizar a aparência da lista de opções e da opção selecionada, aproveitando o padrão de componente sem renderização.
Neste exemplo, vamos usar o slot tag para personalizar a aparência das tags:
O campo de entrada de lista de tags, 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 ser exibida quando nenhum resultado for encontrado:
A propriedade max permite que você limite o número de opções que podem ser selecionadas. Quando o limite max é atingido, o campo de entrada de lista de tags desativará a caixa de listagem:
Se você deseja que a caixa de listagem da lista de tags permaneça aberta entre as seleções, defina a propriedade close-on-select como false:
Se você deseja que as opções sejam recarregadas (com opções estáticas, isso filtraria as opções com o valor de string vazia, e com opções dinâmicas, isso faria uma solicitação ao carregador de opções com o valor de string vazia) quando o usuário confirmar uma seleção, use a propriedade reload-on-commit:
Para habilitar a abertura da caixa de listagem da lista de tags ao clicar em seu campo de pesquisa, defina a propriedade open-on-click como true:
Se você deseja abrir a caixa de listagem da lista de tags sempre que seu campo de pesquisa for focado, defina a propriedade open-on-focus como true:
Abrir ao focar engloba abrir ao clicar.
Se você deseja que a caixa de listagem se expanda quando uma seleção for removida, use a propriedade open-on-remove:
Agora vamos combinar o que aprendemos até agora, utilizando o slot tag para marcação personalizada e definindo a propriedade options como 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 debater chamadas para 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 taglist tentará carregar mais opções com base na posição de rolagem do usuário final |
| open-on-click | boolean | false | O autocompletar é expandido ao focar na 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. |
| allow-new-values | boolean | false | Permite que o usuário final insira um novo valor que não existe na lista de opções. |
| disable-drag-and-drop | boolean | true | Impede que o usuário final ordene as tags arrastando e soltando. |
| 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. |
| close-on-select | boolean | true | Fecha a caixa de listagem quando uma opção é selecionada. |
| open-on-remove | boolean | false | Quando a propriedade `selection-removable` está definida como `true`, o taglist 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 taglists 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 taglist deve sempre carregar suas opções quando aberto ou se deve referenciar as opções que foram encontradas anteriormente ao abrir. |
| load-on-created | boolean | false | Quando definido como `true`, o taglist carregará as opções quando o nó for criado. |
| popover | boolean | false | Renderiza a caixa de listagem 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.. |
| Section-key | Descrição |
|---|---|
| selector | A seção do seletor é um elemento de botão que abre a lista de opções do taglist. |
| 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 da caixa de listagem é um elemento ul que contém a lista de opções. |
| taglistWrapper | Envolve a seção da caixa de listagem. Uma div que lida com a rolagem da caixa de listagem. |
| 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 do seletor quando o carregamento está ocorrendo. |
| selectIcon | Um elemento para exibir um ícone no elemento do seletor quando o taglist 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 de botão usado para remover uma seleção específica. |
| closeIcon | Um elemento para exibir um ícone dentro do botão de remover seleção. |
| listboxButton | Um elemento de botão que é usado para abrir o taglist. |
| 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 de mensagem vazia. |
| 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 | 0 | Prioriza a ordem de foco do teclado definindo-a como 0. |
| 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-expanded | Transmite o estado expansível quando o elemento está em foco. | ||
| aria-controls | Associa o elemento da caixa de listagem, com este elemento. | ||
| aria-describedby | Associa um elemento com uma descrição, auxiliando leitores de tela. | ||
| aria-activedescendant | Gerencia o foco para o elemento descendente ativo atual. | ||
| listboxButton | tabindex | -1 | Prioriza a ordem de foco do teclado definindo-a como -1. |
| aria-haspopup | true | Sinaliza que um elemento dispara um pop-up ou menu | |
| aria-expanded | Transmite o estado expansível quando o elemento está em foco. | ||
| aria-controls | Associa o elemento da caixa de listagem, com este elemento. | ||
| tagWrapper | tabindex | -1 | Prioriza a ordem de foco do teclado definindo-a como -1. |
| tag | role | button | Indica às tecnologias assistivas que este elemento funciona como um botão. |
| tags | 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. |