Visão geral da entrada de arquivo Web Components

O componente Entrada de arquivo Ignite UI for Web Components fornece uma maneira interativa para os usuários selecionarem e carregarem arquivos. Ele estende a funcionalidade básica IgcInputComponent adicionando recursos específicos de arquivo, como seleção de arquivos, exibição de nomes de arquivos selecionados e suporte a vários uploads de arquivos.

Web Components File Input Example

Usage

O componente Entrada de arquivo permite que os usuários selecionem arquivos de seus dispositivos e os carreguem em um aplicativo da Web. Ele exibe os nomes dos arquivos selecionados e oferece opções de personalização para o botão de navegação e o texto "Nenhum arquivo escolhido". O componente também fornece propriedades, métodos e slots que podem ser usados para configurar ainda mais seu comportamento para atender às suas necessidades.

Começando

Para começar a usar o File Input, primeiro você precisa instalar o Ignite UI for Web Components executando o seguinte comando:

npm install igniteui-webcomponents

Depois disso, você precisa importar a entrada do arquivo da seguinte maneira:

import { defineComponents, IgcFileInputComponent } from 'igniteui-webcomponents';

defineComponents(IgcFileInputComponent);

Agora você pode começar com uma configuração básica da entrada de arquivo Web Components.

<igc-file-input label="File Input" required=true></igc-file-input>

Para uma introdução completa ao Ignite UI for Web Components, leia o tópico Introdução.

Configuração

Properties

O componente Entrada de arquivo oferece uma variedade de propriedades que permitem configurar seu comportamento com base em requisitos específicos. Essas propriedades fornecem controle sobre a funcionalidade, a aparência e a validação da entrada.

value- Define o valor atual do campo de entrada do arquivo.
disabled- Desativa a entrada do arquivo, impedindo a interação do usuário.
required- Marca a entrada como obrigatória. O envio do formulário será bloqueado, a menos que um arquivo seja selecionado.
invalid- Indica que o valor de entrada é inválido, usado para acionar estados de erro visual.
multiple- Permite a seleção de vários arquivos.
accept- Define os tipos de arquivos que podem ser selecionados. O valor dessa propriedade precisa ser uma lista separada por vírgulas de formatos de arquivo (por exemplo, .jpg, .png, .gif).
autofocus- Focaliza automaticamente o campo de entrada do arquivo quando a página é carregada.
label- Define o texto do rótulo associado ao elemento de entrada do arquivo.
placeholder- Fornece texto de espaço reservado exibido quando nenhum arquivo é selecionado.

<igc-file-input 
  label="Files Input" 
  accept=".jpg, .png, .gif"
  placeholder="Files missing"
  required
  multiple>
</igc-file-input>

Methods

Além de suas propriedades configuráveis, o componente Entrada de arquivo também herda quatro métodos úteis do IgcInputComponent componente que você pode usar:

focus()- Define o foco no elemento de entrada do arquivo.
blur()- Remove o foco do elemento de entrada do arquivo.
reportValidity()- Verifica a validade da entrada e exibe uma mensagem de validação se a entrada for inválida.
setCustomValidity()- Define uma mensagem de validação personalizada. Se a mensagem fornecida não estiver vazia, a entrada será marcada como inválida.

Slots

O componente Entrada de arquivo também expõe vários slots que podem ser usados para personalizar sua aparência e comportamento.

prefix & suffix- Permite inserir conteúdo antes ou depois da área de entrada principal.
helper-text- Exibe uma dica ou mensagem de instrução abaixo da entrada. Útil para fornecer diretrizes adicionais, como dicas de formatação ou requisitos de campo.
file-selector-text- Permite personalizar o texto exibido no botão de seleção de arquivo.
file-missing-text- Define o texto mostrado no campo de entrada quando nenhum arquivo foi selecionado.
value-missing- Renderiza conteúdo personalizado quando a validação do campo obrigatório falha. (ou seja, quando um arquivo é necessário, mas não fornecido).
invalid– Permite renderizar conteúdo personalizado quando a entrada está em um estado inválido.
custom-error - Displays content when a custom validation message is set using the setCustomValidity() method.

Integration

O componente Entrada de arquivo se integra perfeitamente ao elemento HTML Form. Usando os métodos e propriedades descritos acima, você pode gerenciar efetivamente seu comportamento e validação dentro dos formulários HTML padrão.

Limitations

O componente Entrada de arquivo atualmente tem as seguintes limitações:

As strings padrão para o botão "Procurar" e a mensagem "Nenhum arquivo escolhido" não são localizadas automaticamente. Essas cadeias de caracteres permanecem as mesmas em todas as localidades, mas podem ser personalizadas manualmente usando os slots apropriados ou a associação de espaço reservado.
Os arquivos não podem ser definidos manualmente por meio da value propriedade. A seleção de arquivos pode ser feita apenas por meio do seletor de arquivos. No entanto, você pode passar uma string'' vazia para redefinir o campo.

Accessibility & ARIA Support

O componente File Input é focalizável e interativo, garantindo acessibilidade total do teclado e do leitor de tela. O componente pode ser rotulado usando o label atributo, que aproveita o elemento nativo <label> para fornecer um rótulo semanticamente correto e acessível.

Para oferecer suporte às práticas recomendadas de acessibilidade, o componente também aplica atributos ARIA relevantes:

aria-invalid- Defina como "true" quando a entrada estiver em um estado inválido.
aria-describedby- Vinculado automaticamente ao elemento de texto auxiliar quando presente, permitindo que as tecnologias assistivas anunciem as informações adicionais.

Styling

O File Input componente expõe partes CSS que podemos usar para estilizar. A tabela a seguir lista todas as partes CSS expostas:

Nome	Descrição
`container`	O wrapper principal que contém todos os principais elementos de entrada.
`input`	O elemento de entrada nativo.
`label`	O elemento de rótulo nativo.
`file-names`	O wrapper de nomes de arquivo.
`file-selector-button`	O botão Procurar.
`prefix`	O wrapper de prefixo.
`suffix`	O wrapper de sufixo.
`helper-text`	O wrapper de texto auxiliar.

igc-file-input::part(file-names) {
  background-color: var(--ig-primary-50);
  color: var(--ig-gray-400);
}

igc-file-input::part(suffix) {
  color: var(--ig-primary-700-contrast);
  background-color: var(--ig-primary-700);
}

igc-file-input::part(label) {
  color: var(--ig-gray-600);
}