Saltar al contenido principal

Introducción

Sube y gestiona archivos en el almacenamiento en la nube con optimización automática.

Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/attributes/types/#File

🎯 ¿Qué hace este módulo?​

El módulo FileUploading te permite subir, recuperar y eliminar archivos en el almacenamiento en la nube de OneEntry: imágenes, PDFs, videos, documentos, cualquier tipo de archivo, con optimización automática de imágenes y entrega a través de CDN.

Piénsalo como tu gestor de almacenamiento en la nube: subes archivos una vez, y OneEntry los almacena, optimiza las imágenes automáticamente y las entrega rápidamente a través de CDN.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


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

Sube un archivo y lee el enlace de descarga devuelto:

// 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>

Luego, elimínalo por nombre de archivo (la entidad/id resuelve la carpeta de almacenamiento):

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

✨ Conceptos Clave​

¿Qué es la Carga de Archivos?​

La carga de archivos es almacenar archivos en el almacenamiento en la nube y obtener un enlace CDN permanente de vuelta:

  • Subir - enviar un File o Blob a la nube de OneEntry
  • Almacenamiento - los archivos se almacenan, organizados por entity → id → filename
  • CDN - entrega rápida desde servidores cercanos a los usuarios
  • Optimización - las imágenes pueden ser auto-comprimidas y redimensionadas
  • URL - el downloadLink de la respuesta es el enlace permanente

Tipos de archivos soportados​

Se acepta cualquier tipo de archivo. Solo las imágenes son auto-optimizadas; todo lo demás se almacena tal cual.

CategoríaTipos de ArchivosAuto-Optimización
ImágenesJPG, PNG, GIF, WebP, SVGSí (redimensionar, comprimir)
DocumentosPDF, DOC, DOCX, XLS, XLSXNo (almacenados tal cual)
VideosMP4, MOV, AVI, WebMNo (almacenados tal cual)
ArchivosZIP, RAR, TAR, GZNo (almacenados tal cual)
OtrosCualquier tipo de archivoNo (almacenados tal cual)

📋 Lo Que Necesitas Saber​

Parámetros de Carga​

upload(file, fileQuery?) toma el archivo más un 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 — el File o Blob a subir (desde una entrada o arrastrar-soltar)
  • entity — nombre de carpeta libre en el almacenamiento (por ejemplo, product, page, user, editor — ejemplos, no un enum fijo)
  • id — ID de la entidad para asociar el archivo
  • type — cadena de sugerencia de carpeta/tipo libre
  • width / height — dimensiones máximas para imágenes (se preserva la relación de aspecto)
  • compress — habilitar la compresión de imágenes

Respuesta de Carga​

upload() resuelve a un array de IUploadingReturn. Cada elemento tiene:

{
  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 — usa esta URL en etiquetas <img>, <a>, <video>
  • filename — guárdalo para eliminar el archivo más tarde
  • size — tamaño del archivo en bytes

Optimización de Imágenes​

Para imágenes puedes pasar width, height y compress. La relación de aspecto siempre se preserva: la imagen se redimensiona para ajustarse dentro de los límites dados, nunca se estira.

Eliminación de Archivos​

Pasa el nombre de archivo primero; la entidad/id/tipo viven en el objeto de consulta opcional que resuelve la carpeta de almacenamiento:

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

Recuperación de un Archivo​

getFile(id, type, entity, filename, template?) devuelve un objeto Response en crudo (no JSON parseado) — llama a .blob(), .arrayBuffer(), etc. según sea necesario.

Construyendo un Archivo desde una URL​

createFileFromUrl(url, filename, mimeType?) obtiene un recurso remoto y devuelve un File del navegador, útil para volver a subir una imagen remota existente.

📊 Tabla de Referencia Rápida - Métodos​

MétodoQué HaceCuándo Usarlo
upload()Subir archivo al almacenamiento en la nubeEl usuario sube una imagen, documento
getFile()Obtener el archivo (raw Response)Descargar un archivo almacenado
delete()Eliminar archivo del almacenamientoEliminar archivos antiguos
createFileFromUrl()Construir un File desde una URL remotaImportar una imagen remota antes de subir

Todos los métodos son públicos: no se requiere autorización del usuario.

❓ Preguntas Comunes (FAQ)​

¿Qué tipos de archivos puedo subir?​

Cualquier tipo de archivo. Solo las imágenes son auto-optimizadas (redimensionar/comprimir); otros archivos se almacenan tal cual.

¿Cuál es el tamaño máximo de archivo?​

Depende de los límites de tu plan de OneEntry. Optimiza las imágenes antes de subir para mantener los tamaños bajos.

¿Los archivos se almacenan permanentemente?​

Sí: los archivos permanecen hasta que los elimines con FileUploading.delete(). Los archivos permanecen en el almacenamiento incluso si la entidad relacionada es eliminada, así que límpialos explícitamente.

¿Puedo obtener una lista de todos los archivos subidos para una entidad?​

No directamente a través de este SDK. Haz un seguimiento de los valores de filename que recibes de upload() (por ejemplo, guárdalos en tu base de datos) para gestionar los archivos más tarde.

¿Puedo redimensionar imágenes a dimensiones exactas?​

No: la relación de aspecto siempre se preserva. width/height definen un cuadro delimitador en el que la imagen se ajusta, evitando distorsiones.

🎓 Mejores Prácticas​

  • Valida el tipo y tamaño del archivo antes de llamar a upload().
  • Pasa entity / id para que los archivos se organicen por entidad en el almacenamiento.
  • Habilita compress para imágenes web.
  • Guarda el filename devuelto para que puedas delete() el archivo más tarde.
  • Limpia explícitamente los archivos no utilizados: sobreviven a la eliminación de la entidad.
  • Maneja los errores de carga con try/catch y verifica la forma de retorno de IError.

🔗 Documentación Relacionada​