Pular para o conteúdo principal

Introdução

Carregue e gerencie arquivos no armazenamento em nuvem com otimização automática.

🎯 O que este módulo faz?​

O módulo FileUploading permite que você carregue, recupere e exclua arquivos no armazenamento em nuvem OneEntry - imagens, PDFs, vídeos, documentos e qualquer tipo de arquivo com otimização automática e entrega via CDN.

Pense nisso como seu gerenciador de armazenamento em nuvem - você carrega arquivos uma vez, e o OneEntry os armazena, otimiza as imagens automaticamente e as entrega rapidamente via CDN.

📖 Explicação Simples​

Imagine que você está construindo um aplicativo onde os usuários podem:

  • 📸 Carregar fotos de perfil - redimensionamento e otimização automáticos
  • 📄 Carregar documentos - armazenar PDFs, DOCs com segurança
  • 🖼️ Carregar imagens de produtos - várias imagens por produto
  • 🎥 Carregar vídeos - armazenar e transmitir conteúdo de vídeo
  • 📎 Carregar anexos - qualquer tipo de arquivo

Em vez de gerenciar seu próprio armazenamento:

  • ✅ Carregue arquivos na nuvem OneEntry
  • ✅ Otimização automática de imagens (redimensionar, comprimir)
  • ✅ Entrega rápida via CDN em todo o mundo
  • ✅ Organize por tipo de entidade (produto, usuário, página)
  • ✅ Obtenha URLs de download instantaneamente
  • ✅ Exclua arquivos quando não forem mais necessários

Exemplo do mundo real:

Sem FileUploading (manual):
- Configurar bucket AWS S3 ❌
- Configurar CDN ❌
- Escrever código de otimização de imagem ❌
- Gerenciar permissões de arquivo ❌
- Gerar URLs assinadas ❌

Com FileUploading (automático):
- Carregar arquivo → Obter URL de download ✅
- Imagens otimizadas automaticamente ✅
- Entrega via CDN integrada ✅
- Gerenciamento de arquivos fácil ✅

✨ Conceitos Chave​

O que é Carregamento de Arquivos?​

Carregamento de arquivos é armazenar arquivos no armazenamento em nuvem:

  • Carregar - Enviar arquivo para a nuvem OneEntry
  • Armazenamento - Arquivos armazenados com segurança na nuvem
  • CDN - Entrega rápida a partir de servidores próximos aos usuários
  • Otimização - Imagens automaticamente compactadas e redimensionadas
  • URL - Obter link de download permanente

Tipos de Arquivos Suportados​

Carregue qualquer tipo de arquivo:

CategoriaTipos de ArquivosOtimização Automática
ImagensJPG, PNG, GIF, WebP, SVGSim (redimensionar, comprimir)
DocumentosPDF, DOC, DOCX, XLS, XLSXNão (armazenados como estão)
VídeosMP4, MOV, AVI, WebMNão (armazenados como estão)
ArquivosZIP, RAR, TAR, GZNão (armazenados como estão)
OutrosQualquer tipo de arquivoNão (armazenados como estão)

Otimização de Imagens​

Ao carregar imagens, o OneEntry pode:

  • 📐 Redimensionar - Reduzir dimensões (por exemplo, largura máxima de 1920px)
  • 🗜️ Comprimir - Reduzir o tamanho do arquivo (menor, mais rápido)
  • 🖼️ Formato - Converter para formato ideal (WebP)
  • 📱 Responsivo - Criar múltiplos tamanhos

Exemplo:

Original: 5MB, 4000x3000px
↓ (otimização automática)
Otimizado: 200KB, 1920x1440px

📋 O que você precisa saber​

Parâmetros de Carregamento​

Ao carregar arquivos, você pode especificar:

await FileUploading.upload(file, {
  entity: 'product',     // Tipo de entidade (obrigatório)
  id: 123,               // ID da entidade (opcional)
  type: 'image',         // Dica de tipo de arquivo (opcional)
  width: 1920,           // Largura máxima para imagens (opcional)
  height: 1080,          // Altura máxima para imagens (opcional)
  compress: true         // Comprimir imagens (opcional)
});

Parâmetros explicados:

  • file - O objeto de arquivo (do input ou arrastar e soltar)
  • entity - Categoria: product, page, block, user, form, general
  • id - ID da entidade para associar o arquivo (por exemplo, ID do produto)
  • type - Dica de tipo de arquivo (geralmente detectado automaticamente)
  • width - Largura máxima em pixels (apenas imagens)
  • height - Altura máxima em pixels (apenas imagens)
  • compress - Habilitar compressão (apenas imagens)

Resposta de Carregamento​

Após o carregamento, você recebe:

{
  filename: "abc123-photo.jpg",              // Nome de arquivo único
  downloadLink: "https://cdn.../photo.jpg",  // URL da CDN
  size: 204800,                              // Tamanho do arquivo (bytes)
}

Campos importantes:

  • downloadLink - Use esta URL em <img>, <a>, <video> tags
  • filename - Salve isso para excluir o arquivo mais tarde
  • size - Tamanho do arquivo em bytes (204800 bytes = 200KB)

Melhores Práticas de Organização de Arquivos​

Organize arquivos por tipo de entidade

Opções de Otimização de Imagens​

Controle como as imagens são otimizadas:

OpçãoO que fazExemplo
widthLargura máxima (mantém a proporção)width: 1920
heightAltura máxima (mantém a proporção)height: 1080
compressReduzir o tamanho do arquivocompress: true

A proporção é preservada:

Original: 4000x3000 (proporção 4:3)
Com largura: 800
Resultado: 800x600 (ainda 4:3)

Excluindo Arquivos​

Sempre forneça entidade, id e nome do arquivo para excluir:

await FileUploading.delete({
  entity: 'product',
  id: productId,
  filename: 'abc123-photo.jpg'
});

Por que todos os três? Os arquivos são organizados por entidade → id → nome do arquivo.

📊 Tabela de Referência Rápida - Métodos​

MétodoO que fazQuando usar
upload()Carregar arquivo para armazenamento em nuvemO usuário carrega imagem, documento
getFile()Obter informações do arquivo (tamanho, tipo, URL)Verificar se o arquivo existe
delete()Excluir arquivo do armazenamentoRemover arquivos antigos

❓ Perguntas Comuns (FAQ)​

Quais tipos de arquivos posso carregar?​

Qualquer tipo de arquivo é suportado:

  • Imagens: JPG, PNG, GIF, WebP, SVG, BMP, TIFF
  • Documentos: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT
  • Vídeos: MP4, MOV, AVI, WebM, MKV
  • Arquivos: ZIP, RAR, TAR, GZ
  • Outros: Qualquer tipo de arquivo

Apenas imagens são otimizadas automaticamente. Outros arquivos são armazenados como estão.

Qual é o tamanho máximo do arquivo?​

Verifique os limites do seu plano OneEntry. Normalmente:

  • Plano gratuito: 5MB por arquivo
  • Planos pagos: 50MB - 100MB por arquivo

Melhor prática: Otimize as imagens antes do upload para reduzir o tamanho.

Os arquivos são armazenados permanentemente?​

Sim, os arquivos são armazenados até que você os exclua manualmente usando FileUploading.delete().

Importante: Limpe arquivos não utilizados para economizar espaço de armazenamento.

Posso carregar arquivos do frontend (navegador)?​

Sim! Use input de arquivo ou arraste e solte.

Como faço para validar arquivos antes do upload?​

Verifique o tipo e o tamanho do arquivo.

Posso obter uma lista de todos os arquivos carregados para uma entidade?​

Não diretamente com este SDK. Você precisa:

  1. Rastrear nomes de arquivos ao carregar (salvar no banco de dados)
  2. Usar a API Admin do OneEntry para listar arquivos

Melhor prática: Salve os nomes dos arquivos carregados no seu banco de dados.

Como lido com erros de upload?​

Sempre use try/catch.

Posso carregar arquivos diretamente para a CDN?​

Não, os uploads passam pela API do OneEntry, que:

  1. Valida o arquivo
  2. Otimiza as imagens (se habilitado)
  3. Armazena na nuvem
  4. Retorna a URL da CDN

Isso garante segurança e otimização.

O que acontece com os arquivos se eu excluir uma entidade (produto, usuário)?​

Os arquivos permanecem no armazenamento mesmo se a entidade for excluída.

Melhor prática: Exclua arquivos antes de excluir a entidade.

Posso redimensionar imagens para dimensões exatas?​

Não, a proporção é sempre preservada para evitar distorções.

Como funciona:

  • Você define width: 800, height: 600
  • A imagem é redimensionada para caber dentro de 800x600
  • A proporção é preservada

Exemplo:

Original: 1000x500 (proporção 2:1)
Com largura: 800, altura: 600
Resultado: 800x400 (ainda 2:1, cabe dentro de 800x600)

💡 Notas Importantes​

Segurança de Arquivos​

Os arquivos carregados são acessíveis publicamente via CDN:

  • ✅ Ótimo para imagens, documentos públicos
  • ⚠️ Não carregue arquivos sensíveis (senhas, dados privados)

Para arquivos privados:

  • Use a API Admin do OneEntry com autenticação
  • Ou implemente seu próprio controle de acesso

Limites de Armazenamento​

Monitore seu uso de armazenamento:

  • Cada plano tem limites de armazenamento
  • Limpe arquivos não utilizados regularmente
  • Comprimir imagens antes do upload

Dicas de Otimização de Imagens​

Para melhores resultados:

  • ✅ Carregue originais de alta qualidade (deixe o OneEntry otimizar)
  • ✅ Use compress: true para imagens da web
  • ✅ Defina dimensões apropriadas (por exemplo, 1920px para imagens principais, 500px para miniaturas)
  • ❌ Não carregue imagens já comprimidas (perda de qualidade)

Tamanhos recomendados:

  • Fotos de perfil: 500x500
  • Imagens de produtos: 1920x1920
  • Banners principais: 1920x1080
  • Miniaturas: 300x300

🎓 Melhores Práticas​

  • Valide o tipo e o tamanho do arquivo antes do upload
  • Associe arquivos com IDs de entidades para organização
  • Habilite a compressão para imagens da web
  • Lide com erros de upload de forma elegante
  • Salve nomes de arquivos para excluir arquivos mais tarde
  • Limpe arquivos não utilizados regularmente
  • Mostre o progresso do upload para os usuários

Definição do módulo FileUploading​


const { FileUploading } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada​