Pular para o conteúdo principal

Introdução

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

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/attributes/types/#File

🎯 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, qualquer tipo de arquivo - com otimização automática de imagens e entrega via CDN.

Pense nele 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.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { FileUploading } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Carregue um arquivo e leia o link de download retornado:

// upload() returns an ARRAY of uploaded files (IUploadingReturn[]).
const uploaded = await FileUploading.upload(file, {
  entity: "product",
  id: 123,
  type: "image",
  compress: true,
});

const { filename, downloadLink, size } = uploaded[0];
console.log(downloadLink); // use in <img>, <a>, <video>

Depois, exclua-o pelo nome do arquivo (a entidade/id resolve a pasta de armazenamento):

await FileUploading.delete(filename, { entity: "product", id: 123 });

✨ Conceitos Chave​

O que é Carregamento de Arquivos?​

Carregamento de arquivos é armazenar arquivos no armazenamento em nuvem e obter um link CDN permanente de volta:

  • Carregar - enviar um File ou Blob para a nuvem OneEntry
  • Armazenamento - arquivos são armazenados, organizados por entity → id → filename
  • CDN - entrega rápida a partir de servidores próximos aos usuários
  • Otimização - imagens podem ser auto-comprimidas e redimensionadas
  • URL - o downloadLink da resposta é o link permanente

Tipos de arquivos suportados​

Qualquer tipo de arquivo é aceito. Apenas imagens são auto-otimizadas; tudo o mais é armazenado como está.

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

📋 O que você precisa saber​

Parâmetros de upload​

upload(file, fileQuery?) recebe o arquivo mais um objeto de consulta opcional:

await FileUploading.upload(file, {
  entity: 'product',     // Storage folder name (optional, any string)
  id: 123,               // Entity ID (optional)
  type: 'image',         // Folder/type hint (optional, any string)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true,        // Compress images (optional)
});
  • file — o File ou Blob a ser carregado (de um input ou arrastar-soltar)
  • entity — nome da pasta livre no armazenamento (ex.: product, page, user, editor — exemplos, não um enum fixo)
  • id — ID da entidade para associar o arquivo
  • type — string de dica de pasta/tipo livre
  • width / height — dimensões máximas para imagens (a proporção é preservada)
  • compress — habilitar compressão de imagem

Resposta de upload​

upload() resolve para um array de IUploadingReturn. Cada item tem:

{
  filename: "uploads/abc123-photo.jpg",      // Filename with relative path
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size in bytes
  contentType: "image/png",                  // MIME type
}
  • downloadLink — use esta URL em <img>, <a>, <video> tags
  • filename — salve para excluir o arquivo mais tarde
  • size — tamanho do arquivo em bytes

Otimização de Imagens​

Para imagens, você pode passar width, height e compress. A proporção é sempre preservada — a imagem é redimensionada para caber dentro dos limites dados, nunca esticada.

Excluindo arquivos​

Passe o nome do arquivo primeiro; a entidade/id/tipo vivem no objeto de consulta opcional que resolve a pasta de armazenamento:

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

Recuperando um arquivo​

getFile(id, type, entity, filename, template?) retorna um objeto Response bruto (não JSON analisado) — chame .blob(), .arrayBuffer(), etc. conforme necessário.

Construindo um Arquivo a partir de uma URL​

createFileFromUrl(url, filename, mimeType?) busca um recurso remoto e retorna um File do navegador, útil para re-enviar uma imagem remota existente.

📊 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()Buscar o arquivo (raw Response)Baixar um arquivo armazenado
delete()Excluir arquivo do armazenamentoRemover arquivos antigos
createFileFromUrl()Construir um File a partir de uma URL remotaImportar uma imagem remota antes do upload

Todos os métodos são públicos — nenhuma autorização de usuário é necessária.

❓ Perguntas Comuns (FAQ)​

Quais tipos de arquivos posso carregar?​

Qualquer tipo de arquivo. Apenas imagens são auto-otimizadas (redimensionar/comprimir); outros arquivos são armazenados como estão.

Qual é o tamanho máximo do arquivo?​

Depende dos limites do seu plano OneEntry. Otimize as imagens antes do upload para manter os tamanhos baixos.

Os arquivos são armazenados permanentemente?​

Sim — os arquivos permanecem até que você os remova com FileUploading.delete(). Os arquivos permanecem no armazenamento mesmo se a entidade relacionada for excluída, então limpe-os explicitamente.

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

Não diretamente via este SDK. Acompanhe os valores de filename que você recebe de upload() (ex.: salve-os em seu banco de dados) para gerenciar arquivos depois.

Posso redimensionar imagens para dimensões exatas?​

Não — a proporção é sempre preservada. width/height definem uma caixa delimitadora na qual a imagem se encaixa, prevenindo distorção.

🎓 Melhores Práticas​

  • Valide o tipo e o tamanho do arquivo antes de chamar upload().
  • Passe entity / id para que os arquivos sejam organizados por entidade no armazenamento.
  • Habilite compress para imagens da web.
  • Salve o filename retornado para que você possa delete() o arquivo mais tarde.
  • Limpe arquivos não utilizados explicitamente — eles sobrevivem à exclusão da entidade.
  • Trate erros de upload com try/catch e verifique a forma de retorno IError.

🔗 Documentação Relacionada​