Componentes · Arquivos
Arquivos, imagens e assinatura
Contrato em PDF, foto do cadastro, assinatura do cliente, código de barras lido pela câmera: tudo entra pelo mesmo tipo de campo. Você decide onde o arquivo fica guardado e o que a pessoa pode enviar; arrastar, pré-visualizar, recortar e baixar já vêm prontos.
<mad-file-field>
Paleta → Campos → Upload / Imagem (crop) / Avatar / Assinatura
Até 10 MB por arquivo no disco — conteúdo no banco só para imagem pequena e assinatura
01
Qual campo para qual arquivo
Todos recebem um arquivo pela tela e guardam uma referência a ele no registro. A diferença é o que a pessoa faz na hora: solta um documento, tira e recorta uma foto, assina com o dedo ou aponta a câmera para um código.
| Sua situação | Componente certo |
|---|---|
| Um documento por registro (contrato, comprovante, planilha) | Upload |
| Vários arquivos de uma vez (anexos de um chamado, documentos de um pedido) | Upload Múltiplo |
| Uma foto que precisa de recorte, giro ou câmera na hora | Imagem (crop) |
| A foto de perfil, redonda e pequena | Avatar |
| A pessoa assina na tela, com o dedo, o mouse ou digitando o nome | Assinatura |
| Ler um código de barras ou QR com a câmera do celular | Scanner Barcode/QR |
| Mostrar na lista o arquivo que já foi enviado (miniatura, avatar, link para baixar) | Listagem, no transformador da coluna |
| Uma linha para assinar à caneta no PDF impresso | Documentos (PDF) |
| Guardar só o endereço de um arquivo que mora em outro sistema | Campos de texto |
O leitor de código não é um upload: ele preenche um campo de texto com o que a câmera leu. Está
nesta página porque usa a câmera como os outros.
1
Colocar na tela
- Abra o formulário no Studio e clique com o botão direito na Linha onde o campo vai ficar.
- Escolha o campo na categoria Campos: Upload, Upload Múltiplo, Imagem (crop), Avatar, Assinatura ou Scanner Barcode/QR.
- Em Nome, escolha a coluna da tabela que vai guardar o arquivo. Em Label, o texto que a pessoa lê.
Resultado: o campo aparece como uma área de soltar arquivo — mas ainda sem Tipo de gravação: a pessoa consegue escolher o arquivo e, ao salvar, nada é guardado.
Quando a tela é gerada a partir do modelo de dados, colunas chamadas foto, imagem,
logo, anexo, arquivo, avatar ou assinatura já nascem com o campo certo e o
lugar de gravação decidido pelo tipo da coluna. Esta página é para quando você monta à mão.
2
Decidir onde o arquivo fica
- Abra a seção Armazenamento de dados.
- Em Tipo de gravação, escolha Armazenar caminho do arquivo na coluna: o arquivo vai para uma pasta do servidor e a coluna guarda só o caminho. É o padrão para documento, PDF e qualquer coisa grande.
- Em Pasta de upload, dê um nome de pasta por assunto — uploads/contratos, pessoas/fotos.
- Modo de renomeação decide o nome do arquivo no servidor. Deixe em prefix: um código na frente do nome original evita que dois arquivos com o mesmo nome se sobrescrevam.
- Em Tipos aceitos, marque as fichas do que pode entrar — PDF, Imagens (todas), Excel. Em Tamanho máximo, o limite por arquivo, como 10MB.
- Só para imagem pequena ou assinatura, a alternativa é Armazenar conteúdo + nome na tabela: o arquivo inteiro vai para dentro da coluna, sem pasta. Aí aparece Coluna do nome, que guarda o nome original.
Resultado para quem usa o sistema: a pessoa arrasta o arquivo ou clica em Clique para enviar, vê o nome e o tamanho, e depois de salvar ganha os botões Visualizar, Baixar, Trocar e Remover.
Destaque
Passe o mouse na lista — ou use ↑ ↓ depois de focar um item.
O que o painel escreve no código
Destaque
Sem Tipo de gravação, o arquivo não é guardado. A tela aceita o arquivo, o registro salva
e a coluna fica vazia — sem erro nenhum. É o primeiro lugar para olhar quando "o anexo sumiu".
3
Vários arquivos de uma vez
- Use o Upload Múltiplo e escolha o Tipo de gravação como no passo anterior.
- Em Modo de armazenamento, escolha entre os dois jeitos de guardar a lista: comma põe todos os caminhos na mesma coluna, separados por vírgula; table cria uma linha por arquivo numa tabela de anexos.
- Com table, escolha a tabela de anexos em Tabela-pivô e, no assistente, a coluna que guarda o caminho. Se a tabela tiver colunas de nome original, tamanho e tipo, elas são preenchidas sozinhas.
- Em Máximo de arquivos, o limite de quantos podem ser enviados; em Tamanho máximo, o limite de cada um, em KB.
Resultado para quem usa o sistema: a pessoa solta vários arquivos de uma vez, vê um cartão para cada um com o × de remover, e o cartão Adicionar some quando chega ao limite.
Destaque
Uma tabela de anexos com colunas obrigatórias que o upload não conhece (o cliente, a empresa)
recusa o arquivo com erro de banco. Nesse caso a gravação precisa ser feita por uma ação da tela.
4
Foto com recorte e foto de perfil
- Para uma foto que a pessoa ajusta, use Imagem (crop). Em Tipos aceitos, deixe só imagens.
- Marque Permitir recorte para abrir o editor de recorte depois de escolher a foto, e Permitir câmera para tirar a foto na hora.
- Em Proporção do recorte, fixe o formato quando a foto precisa caber num espaço certo — 1 para quadrada, 16/9 para capa. Vazio deixa livre.
- Para a foto de perfil, use Avatar: em Tamanho, o diâmetro do círculo; Permite remover mostra o × para tirar a foto.
Resultado para quem usa o sistema: a pessoa solta a imagem, a janela Recortar imagem abre com giro e zoom, e ao aplicar a foto já aparece do tamanho certo. No avatar, passar o mouse mostra Trocar foto.
Destaque
Destaque
5
Assinatura e leitor de código
- Use Assinatura onde a pessoa precisa assinar. Em Modos disponíveis, deixe só o que faz sentido: draw para desenhar, type para digitar o nome em letra cursiva, upload para enviar uma imagem pronta.
- Em Altura e Largura, o tamanho da área de assinar. No celular, ela abre em tela cheia quando a pessoa toca no campo.
- Use Scanner Barcode/QR para ler um código. Em Formato, escolha qr, barcode ou both para aceitar os dois.
- O leitor também aceita digitar: quem não tem câmera escreve o código no campo.
Resultado para quem usa o sistema: no computador, a pessoa desenha direto na área; no celular, toca em Clique para assinar e desenha em tela cheia. Nos dois, corrige com Desfazer e fecha com Confirmar. No leitor, toca no ícone, aponta a câmera e o código aparece no campo com um bipe.
Destaque
Destaque
Teste online apaga os arquivos enviados. Cada publicação completa troca a pasta do app, e os
arquivos moram nela: os registros continuam apontando para arquivos que não existem mais. Na
Hospedagem a área de arquivos fica fora da publicação e sobrevive — e entra na cópia de segurança.
6
Testar antes de entregar
Salve a tela e publique no Teste online. Confira nesta ordem:
| O que fazer | O que tem que acontecer |
|---|---|
| Soltar um arquivo e salvar | Ao reabrir o registro, o arquivo está lá com nome e botão Baixar. |
| Clicar em Baixar | O arquivo abre ou é salvo, sem página de erro. |
| Soltar um arquivo de tipo não aceito | O arquivo é recusado antes de salvar. |
| Trocar o arquivo e salvar | O novo substitui o antigo; o antigo não aparece mais. |
| Na imagem, recortar e aplicar | A foto salva já recortada, não a original. |
| No celular, tocar em assinar | A área abre em tela cheia e o desenho acompanha o dedo. |
| No leitor, apontar para um código | O campo recebe o código e o bipe toca. |
08
Problemas comuns
Anexei o arquivo, salvei, e não ficou gravado em lugar nenhum
O campo está sem Tipo de gravação. Escolha caminho no disco e informe a Pasta de upload, ou conteúdo na tabela.
O arquivo salva cortado, ou a imagem não abre
Você escolheu guardar o conteúdo na coluna e a coluna é de texto curto. Troque a coluna para texto longo no modelo de dados — ou guarde só o caminho, que cabe em qualquer coluna.
O botão Baixar dá página não encontrada
O que fica na coluna é um caminho interno, não um endereço. Use o link de download do próprio sistema: na listagem, o transformador Link de download.
A listagem mostra um caminho enorme no lugar da foto
A coluna está sendo exibida como texto. Na coluna da listagem, escolha um transformador do grupo Arquivo & Mídia: avatar, miniatura, link ou galeria.
Publiquei de novo no Teste online e os anexos sumiram
É esperado: a publicação troca a pasta do app inteira. Arquivos que precisam durar ficam na Hospedagem, onde a área de arquivos fica fora da publicação.
A câmera não abre no leitor ou na foto
O navegador só libera a câmera em endereço seguro, com cadeado. Teste online e Hospedagem já são seguros; um endereço próprio precisa de certificado.
09
Referência: painel × código
Para quem também mexe no Blade, este é o de-para entre o painel e os atributos gerados. O tamanho máximo se escreve de três jeitos conforme o campo — mais um motivo para configurar pelo painel.
| No painel | No código | Padrão |
|---|---|---|
| Nome | name | — |
| Label | label | — |
| Tipos aceitos | accept | — |
| Tamanho máximo | maxSize · max_size · max-size | 5MB |
| Tipo de gravação | storage | manual |
| Pasta de upload | folder | uploads |
| Coluna do nome | name-column | — |
| Modo de renomeação | file-name | prefix |
| Múltiplos arquivos | multiple | — |
| Modo de armazenamento | mode | comma |
| Tabela-pivô | model · foreign-key · path-column | — |
| Máximo de arquivos | max-files | — |
| Permitir câmera | camera | — |
| Permitir recorte | crop | — |
| Proporção do recorte | aspect-ratio | livre |
| Tamanho (do avatar) | size | 96px |
| Permite remover | removable | ligado |
| Altura (da assinatura) | height | 200px |
| Modos disponíveis | modes | desenhar, digitar e enviar |
| Formato (do leitor) | type | both |
| Obrigatório | required | — |
| Placeholder | placeholder | — |
| Valor padrão | default | — |
| Somente leitura | readonly | — |
| Dica | hint | — |
| Largura | width | — |
| On Change | mad:change | — |