A entrada dropdown permite que os usuários selecionem um valor de uma lista de opções. Diferentemente dos elementos select nativos, a entrada dropdown permite que você personalize tanto a aparência quanto o comportamento.
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 dropdown será renderizada no modo de seleção única por padrão.
Entradas dropdown com a propriedade multiple definida serão renderizadas 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.
Em vez de passar uma lista estática para a propriedade options, as opções podem ser atribuídas dinamicamente.
Neste exemplo, a função, loadHorrorMovies, faz uma solicitação à API do TMDB para carregar uma lista de filmes de terror. Atribuir a função à propriedade options carregará as opções quando o usuário final abrir a caixa de listagem.
Por padrão, o dropdown só carregará opções de forma assíncrona uma vez (quando a caixa de listagem for expandida). Definir a propriedade always-load-on-open fará com que o dropdown carregue opções todas as vezes que a caixa de listagem for expandida.
A propriedade load-on-created fará com que o dropdown carregue opções assim que for criado.
Uma função atribuída à propriedade options receberá dois argumentos: page e hasNextPage. O argumento page indica o número da página atual, e hasNextPage é uma função de retorno que indica se há mais páginas para carregar.
Se você preferir permitir que o usuário carregue mais opções sem ter que clicar na opção Carregar mais no final da lista de opções, você pode definir a propriedade load-on-scroll como verdadeira, e nossa função, loadCurrentlyPopularMovies, será chamada novamente:
O input de dropdown do FormKit também fornece uma propriedade optionLoader que permite reidratar valores que não estão na lista de opções. Neste exemplo, o dropdown é fornecido com um valor inicial (dois IDs de filmes). A função optionLoader é chamada para cada valor que não está na lista de opções.
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.
Ao contrário dos elementos de seleção nativos, a entrada de dropdown pode ser personalizada via marcação.
A entrada de dropdown 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:
A entrada de dropdown permite que você personalize a aparência da(s) opção(ões) selecionada(s).
Ao usar a entrada de dropdown como um multi-select, você pode personalizar a aparência das opções selecionadas definindo a propriedade selection-appearance para truncate (o padrão) ou tags.
Se você deseja personalizar apenas a exibição da opção selecionada, use o slot de seleção (em oposição ao slot de opção mencionado acima):
O slot de seleção não existe no dropdown de seleção múltipla com aparência de truncate.
As seguintes propriedades permitem que você personalize o comportamento do campo de dropdown.
Por padrão, o campo de dropdown será renderizado em um estado desabilitado se nenhuma opção for passada. Opcionalmente, você pode passar a propriedade empty-message com uma mensagem para exibir quando não houver opções disponíveis:
Se você deseja permitir que os usuários removam o valor selecionado, defina a propriedade selection-removable como verdadeira. Isso renderizará um ícone de fechar ao lado do valor selecionado:
A propriedade selection-removable não pode ser usada para seleções múltiplas.
Por padrão, quando a propriedade selection-removable está definida como true, o dropdown não abrirá após o valor selecionado ser removido. Você pode alterar esse comportamento definindo a propriedade open-on-remove como true:
Por padrão, quando a propriedade multiple está definida, o dropdown não fechará após uma opção ser selecionada. Você pode alterar esse comportamento definindo a propriedade close-on-select como true:
Se você deseja expandir a caixa de listagem assim que o campo de dropdown for focado, você pode usar a propriedade open-on-focus:
Ao usar o dropdown com opções estáticas, o dropdown do FormKit também vem com um recurso chamado overscroll. Definir a propriedade behavior para overscroll renderizará a caixa de listagem diretamente sobre o campo de entrada para maximizar o tamanho disponível para a lista:
Se você deseja limitar o número de opções que podem ser selecionadas, você pode usar a propriedade max:
| Prop | Type | Padrão | Descrição |
|---|---|---|---|
| options | any | [] | A lista de opções que o usuário pode selecionar. |
| load-on-scroll | boolean | false | Quando definido como `true`, o dropdown tentará carregar mais opções com base na posição de rolagem do usuário final |
| 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. |
| selection-appearance | string | truncate | Para dropdowns de seleção múltipla, esta propriedade permite personalizar a aparência das opções selecionadas. Os valores possíveis são `truncate` (o padrão) ou `tags`. |
| selection-removable | boolean | false | Para dropdowns de seleção única, esta propriedade permite remover o valor selecionado. |
| open-on-remove | boolean | false | Quando a propriedade `selection-removable` está definida como `true`, o dropdown não se abrirá após o valor selecionado ser removido. Você pode alterar esse comportamento definindo a propriedade `open-on-remove` como `true`. |
| close-on-select | boolean | false | Quando a propriedade `multiple` está definida, o dropdown não se fechará após uma opção ser selecionada. Você pode alterar esse comportamento definindo a propriedade `close-on-select` como `true`. |
| open-on-focus | boolean | false | Se você deseja expandir a lista assim que o campo de entrada do dropdown receber foco, você pode usar a propriedade `open-on-focus`. |
| options-appearance | string | undefined | Para dropdowns 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`. |
| multiple | boolean | false | Quando definido como `true`, o dropdown permitirá que o usuário selecione várias opções. |
| behavior | string | undefined | Renderiza a lista diretamente sobre o campo de entrada para maximizar o tamanho disponível para a lista. |
| always-load-on-open | boolean | false | Determina se o dropdown 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 dropdown carregará as opções quando o nó for criado. |
| 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 à seleção múltipla). |
| deselect | boolean | true | Quando definido como `false`, o usuário final não pode desmarcar uma opção selecionada da lista. |
| 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.
| Section-key | Descrição |
|---|---|
| selector | A seção do seletor é um elemento botão que abre a lista de opções do dropdown. |
| 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 lida com a rolagem do 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. |
| selectedIcon | Um elemento para exibir um ícone ao lado da opção selecionada quando dentro do listbox. |
| 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. |
| 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. |
| tagsWrapper | Um elemento div que envolve a seção de tags. |
| tags | Um elemento div que contém as tags. |
| tagWrapper | Um elemento div que envolve a tag. |
| tag | Um elemento div que contém o rótulo da tag e a seção removeSelection. |
| tagLabel | Um elemento span que contém o rótulo da tag. |
| removeSelection | Um elemento span que contém o ícone de remoção da seleção. |
| selectorSelectionsWrapper | Um elemento div que envolve a seção selectorSelections. |
| selectorSelections | Um elemento div que contém as seções selectorSelectionsItem. |
| selectorSelectionsItem | Um elemento div que contém o conteúdo do selectorSelectionsItem. |
| truncationCount | Um elemento div que contém o conteúdo do truncationCount. |
| 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 |
|---|---|---|---|
| selector | tabindex | 0 | Prioriza a ordem de foco do teclado definindo-a como 0 |
| aria-haspopup | listbox | Sinaliza a presença de uma caixa de listagem pop-up acionada pela interação. | |
| aria-expanded | Indica se o elemento suspenso está atualmente expandido ou recolhido. | ||
| aria-controls | Vincula este elemento ao ID do elemento da caixa de listagem. | ||
| aria-describedBy | Associa este elemento com texto descritivo de outro elemento. | ||
| placeholder | aria-hidden | true | Torna este elemento não exposto à API de acessibilidade quando não existe um placeholder. |
| removeSelection | tabindex | -1 | Prioriza a ordem de foco do teclado definindo-a como -1 |
| aria-controls | Vincula este elemento ao ID do elemento de entrada. | ||
| selections | aria-live | polite | Anuncia aos leitores de tela que este elemento foi atualizado dinamicamente sem interromper a tarefa atual. |
| aria-hidden | true | Torna este elemento não exposto à API de acessibilidade. | |
| selectionsItem | aria-hidden | true | Torna este elemento não exposto à API de acessibilidade quando o último índice visível e o índice são maiores que o último índice visível. |
| tagWrapper | tabindex | 0 | Prioriza a ordem de foco do teclado definindo-a como 0 |
| tag | tabindex | 0 | Prioriza a ordem de foco do teclado definindo-a como 0 |
| tagsWrapper | aria-live | polite | Anuncia aos leitores de tela que este elemento foi atualizado dinamicamente sem interromper a tarefa atual. |
| 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. |