O input file utiliza o input de arquivo nativo do HTML. Ele permite que os usuários selecionem arquivos de seu dispositivo para upload. Além das funcionalidades nativas do input, ele adiciona suporte para:
O valor do tipo file deve ser sempre um array de objetos onde cada objeto contém um name (string) e uma propriedade file (File) opcional. Ao selecionar novos arquivos do dispositivo do usuário, o FormKit converterá a FileList nativa para a estrutura baseada em array automaticamente.
Esta estrutura pode ser usada para pré-popular um input de arquivo com valores de arquivos previamente carregados:
Pré-popular um input com nomes de arquivos é apenas para fins de exibição. É um recurso opcional que fornece uma interface consistente para transmitir que um arquivo foi previamente carregado — no entanto — uma FileList não está anexada à tag <input> real para upload.
O processo de upload de arquivos é deixado para o manipulador de envio do seu formulário. Ao enviar o formulário via solicitação de página completa nenhum processamento adicional é necessário, no entanto, ao enviar via solicitação XHR/Fetch você precisará criar uma instância de FormData com os arquivos anexados. Aqui está um exemplo funcional:
O input file possui algumas props únicas. Há também vários atributos HTML nativos comumente usados que ajudam a controlar os uploads de arquivos.
| Prop | Type | Padrão | Descrição | ||
|---|---|---|---|---|---|
| Commonly used native attributes | |||||
| accept | -- | -- | Ver no MDN | ||
| capture | -- | -- | Ver no MDN | ||
| multiple | -- | -- | Ver no MDN | ||
| webkitdirectory | -- | -- | Ver no MDN | ||
| Props | |||||
| file-item-icon | String | ’’ | Especifica um ícone para colocar na seção fileItemIcon. Apenas exibido quando há um arquivo selecionado. O padrão é o ícone fileDoc. | ||
| file-remove-icon | String | ’’ | Especifica um ícone para colocar na seção fileRemoveIcon. Apenas exibido quando um arquivo está selecionado. O padrão é o ícone close. | ||
| no-files-icon | String | ’’ | Especifica um ícone para colocar na seção noFilesIcon. Apenas exibido quando nenhum arquivo está selecionado. O padrão é o ícone fileDoc. | ||
| 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 |
|---|---|
| fileList | Um invólucro para a lista inteira de arquivos. |
| fileItemIcon | Um elemento contendo um ícone opcional de item de arquivo. |
| fileItem | Um elemento contendo o nome do arquivo e a ação de remoção para cada arquivo. |
| fileName | O elemento contendo o nome de um arquivo. |
| fileRemove | O elemento que remove um arquivo da lista. |
| fileRemoveIcon | Um elemento contendo o ícone de remoção de arquivo. |
| noFiles | O elemento exibido quando não há arquivos selecionados. |
| noFilesIcon | Um elemento contendo um ícone dentro da seção noFiles. |
| 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 inputs do FormKit são projetados levando em consideração as seguintes considerações de acessibilidade. Ajude-nos a melhorar continuamente a acessibilidade para todos, relatando problemas de acessibilidade aqui:
| Chave de Seção | Atributo | Padrão | Descriçã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. |