Biblioteca de medios

La biblioteca de medios almacena imágenes, documentos, vídeos y audio reutilizables. Los editores suben un archivo una sola vez, lo seleccionan en campos de contenido y en Portable Text, y ven qué entradas de contenido hacen referencia a un elemento multimedia local.

Abre la biblioteca de medios

Selecciona Media en la barra lateral del administrador. Main library contiene carpetas y los archivos que todavía no están en ninguna carpeta. Selecciona una carpeta para explorar sus archivos y cambia entre la vista de cuadrícula y la de lista cuando lo necesites.

Si tu sitio tiene proveedores de medios externos, cada proveedor aparece como otra fuente. Las capacidades de los proveedores varían: una fuente puede admitir la exploración y la selección, pero no carpetas, edición local de imágenes ni eliminación.

Sube archivos

Subir desde la biblioteca

Las subidas empiezan en cuanto añades los archivos. Los archivos locales nuevos van a Main library, aunque hubiera otra carpeta abierta antes de subirlos.

Subir mientras editas contenido

Los campos de imagen, archivo, galería e imagen de Portable Text usan el selector de medios. Abre el campo, selecciona Upload files y elige o suelta los archivos. Las subidas completadas pasan a formar parte de la selección actual; las subidas fallidas permanecen visibles para que puedas reintentarlas o quitarlas.

En una galería, revisa Selected media y define el orden con los controles de movimiento antes de seleccionar Add images. En una sola imagen o un solo archivo, selecciona Select o Insert image cuando termine la subida.

Archivos aceptados y límites de tamaño

La biblioteca de medios local acepta de forma predeterminada estos grupos de archivos:

• imágenes PNG, JPEG, GIF, WebP y AVIF;
• formatos de vídeo habituales, como MP4, WebM y vídeo QuickTime;
• formatos de audio habituales, como MP3, WAV y audio Ogg; y
• documentos PDF.

SVG queda fuera de la lista de subida predeterminada porque los archivos SVG pueden contener contenido activo. Un campo de imagen o de archivo puede definir su propia lista de tipos de archivo aceptables cuando tu modelo de contenido necesite una selección más acotada u otros formatos. EmDash identifica cada archivo por su tipo de medio, una etiqueta como image/png o application/pdf, y vuelve a comprobar la lista del campo cuando se guarda el contenido. Cambiar el selector de archivos del navegador no evita esa comprobación del lado del servidor.

El máximo predeterminado es de 50 MB por archivo. Los desarrolladores del sitio pueden cambiarlo con maxUploadSize. Los proveedores pueden imponer restricciones adicionales de formato o de tamaño y comunican ese fallo en la fila de subida.

Encuentra y organiza archivos

La búsqueda coincide con partes del nombre de archivo. El filtro de tipo limita los resultados a imágenes, documentos, vídeos o audio. La búsqueda por nombre de archivo abarca toda la biblioteca local aunque haya una carpeta abierta; al explorar una carpeta sin buscar, solo se muestran los archivos asignados a esa carpeta.

Los editores pueden seleccionar Add new folder en Main library. Para mover un archivo local, arrastra su tarjeta o su fila a una carpeta visible, o abre el archivo, cambia Location y selecciona Save. Usa Main library como ubicación para sacar un archivo de su carpeta actual.

Los autores pueden mover los archivos locales que han subido ellos mismos. Los editores pueden mover cualquier archivo local. Los elementos de proveedores externos no se pueden asignar a carpetas de la biblioteca de medios.

Al eliminar una carpeta, sus archivos vuelven a Main library. No se eliminan archivos, no cambian sus URL ni se quitan las referencias de contenido.

Selecciona medios para el contenido

Imágenes de Portable Text

Coloca el cursor en un campo de Portable Text, abre el menú de bloques y selecciona Image. Elige o sube una imagen y luego selecciona Insert image. Después, selecciona el bloque de imagen para añadir texto alternativo, pie de foto, tamaño de visualización y alineación.

Campos de imagen y de archivo

Selecciona la acción del campo, por ejemplo Select image o Select file, elige un elemento y confirma la selección. Las reglas de tipo MIME del campo limitan qué elementos de la biblioteca y qué fuentes de medios se muestran.

El campo featured_image de la plantilla de blog guarda el valor multimedia seleccionado junto con la publicación. Al guardar la entrada, esa referencia se guarda en el borrador; al publicar, queda disponible para las consultas públicas de contenido.

Campos de galería

Selecciona una o más imágenes, ordénalas en Selected media y confirma. La galería conserva su propio orden y el texto alternativo y el pie de foto de cada imagen, aunque varias posiciones hagan referencia al mismo elemento de la biblioteca de medios.

Edita una imagen usada en el contenido

Una imagen local seleccionada ofrece acciones con alcances diferentes:

• Replace elige otro elemento de la biblioteca de medios para este campo, bloque o posición de galería. Las demás entradas que usan el elemento original no cambian.
• Edit asset abre el elemento subyacente de la biblioteca de medios. Los cambios de metadatos y los cambios destructivos de la imagen pueden afectar a otros usos de ese elemento.
• Remove borra esta referencia de contenido. El elemento de la biblioteca de medios sigue disponible.

Cuando Edit asset crea una copia recortada, el selector elige la nueva copia para el uso actual. Las imágenes de Portable Text y de galería conservan el texto alternativo, el pie de foto, el diseño y la posición de ese uso. Cuando Edit asset reemplaza el original, el ID del medio no cambia, de modo que cada uso de ese elemento recibe la imagen modificada.

Los campos de imagen y de archivo de proveedores externos ofrecen Replace y Remove, pero no abren el editor local de recursos.

Reemplaza una imagen local

Replace image sube nuevos bytes detrás de un elemento existente de la biblioteca de medios. Úsalo cuando todos los lugares que hacen referencia a ese elemento deban mostrar la nueva versión de la imagen.

La acción está disponible para elementos JPEG, PNG y WebP que estén listos. Los autores pueden reemplazar las imágenes que han subido ellos mismos; los editores pueden reemplazar cualquier imagen local.

EmDash conserva el ID del medio, el nombre de archivo, la URL, el texto alternativo, el pie de foto y la carpeta. Por eso, las referencias de contenido existentes siguen funcionando y muestran la imagen reemplazada. El reemplazo borra el punto focal guardado porque sus coordenadas podrían no ser válidas para la nueva imagen.

Si solo hay que cambiar un campo o un bloque de imagen, usa Replace en el editor de contenido.

Define un punto focal

Un punto focal marca la parte de una imagen que debe seguir visible cuando un diseño recorta la imagen a una forma cuadrada, apaisada, vertical u otra forma fija.

Selecciona Reset para quitar el punto personalizado. Cuando seleccionas una imagen para un campo o una galería, EmDash copia el punto focal actual del recurso en ese valor de contenido. El contenido que ya usa la imagen conserva su punto guardado hasta que vuelvas a seleccionar la imagen. Cuando abres Edit asset desde un campo de contenido, el punto que guardas actualiza ese uso actual.

Recorta una imagen local

El recorte está disponible para imágenes JPEG, PNG y WebP que estén almacenadas en EmDash y listas. Las imágenes de proveedores externos no se pueden recortar en el editor local de recursos.

Replace original solo está disponible con la relación de aspecto Original. Para Freeform y otras proporciones, usa Create cropped copy. Las copias recortadas se guardan en la misma carpeta que su elemento de origen y reciben un nombre de archivo único.

Recortar un WebP animado produce un WebP estático. La animación no se conserva en el resultado recortado.

Consulta dónde se usa un archivo

Abre un archivo local y selecciona Used in para ver las entradas de contenido y los ajustes del sitio que hacen referencia a él. Cada resultado de contenido indica la colección y el campo que contienen la referencia, y abre la entrada para editarla. Las entradas que están en la papelera se identifican en la lista. Un resultado de Site Settings indica el ajuste que selecciona el archivo: Logo, Favicon o Default Social Image.

Used in comprueba estas referencias:

• campos de imagen y de archivo
• campos de imagen dentro de repetidores
• campos de imagen, archivo y Portable Text dentro de campos blocks
• bloques de imagen y de galería en campos de Portable Text
• el logotipo del sitio, el favicon y la imagen social predeterminada

Cuando la cobertura del uso es completa y el archivo no tiene ninguna de estas referencias, la lista muestra No tracked references found. Antes de que la cobertura sea completa, una lista vacía muestra No usage to show yet.

El seguimiento del uso de medios debe estar habilitado para que los resultados de contenido puedan ser completos. Los ajustes del sitio se enumeran tanto si el seguimiento está habilitado como si no. Un administrador habilita el seguimiento una sola vez para el sitio:

Una vez habilitado, el seguimiento del uso de medios no se puede desactivar. Los cambios de contenido nuevos se rastrean una vez que la captura está activa; el análisis en segundo plano añade las referencias de las entradas que ya existían.

Si la vista Used in informa de que la indexación está en curso, desactualizada, parcial o fallida, trata sus resultados como incompletos. Los administradores pueden volver a Media usage tracking para ver el estado actual y las indicaciones de recuperación.

Renderiza imágenes en plantillas

Un campo de imagen devuelve un valor multimedia, no una URL simple. Renderiza ese valor con Image de emdash/ui para que las imágenes locales y las proporcionadas por proveedores usen la URL, las dimensiones, el punto focal, las variantes responsivas y el marcador de posición de baja calidad adecuados:

---
import { getEmDashEntry } from "emdash";
import { Image } from "emdash/ui";

const { entry: post, error } = await getEmDashEntry("posts", Astro.params.slug);
if (error) return new Response("Unable to load post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

{post.data.featured_image && (
  <Image image={post.data.featured_image} width={1200} height={675} priority />
)}

Usa priority solo para la imagen principal visible en la parte superior de la página. Solicita carga inmediata y le da al navegador una indicación de prioridad de descarga alta. Las demás imágenes deben conservar la carga diferida que es el valor predeterminado del componente.

Si el campo tiene una imagen para modo oscuro, Image renderiza ambas fuentes y elige una según el esquema de color del visitante. Consulta Variantes oscuras de imagen para configurar el campo y la plantilla.

Las plantillas reciben los metadatos del medio que se guardan junto con la referencia de contenido sin volver a consultar la biblioteca de medios. Si una integración personalizada necesita los metadatos más recientes del proveedor, solicita ese elemento de forma explícita y evita consultar al proveedor por cada imagen en las páginas de colección. La referencia de tipos de campo describe los valores guardados de archivo e imagen.

Configura el almacenamiento y los proveedores

La biblioteca local almacena los archivos mediante el adaptador de almacenamiento configurado para el sitio. Los sitios Node.js pueden usar disco local o almacenamiento compatible con S3; los sitios Cloudflare suelen usar un binding de R2. El adaptador decide dónde viven los bytes, y la biblioteca de medios mantiene el mismo flujo de trabajo de edición. Consulta Elegir el almacenamiento de medios para la configuración y los requisitos de persistencia en producción.

Cloudflare Images y Cloudflare Stream se pueden registrar como proveedores de medios externos. Aparecen como fuentes en el selector, y Image entiende los valores de imagen proporcionados por proveedores. Los elementos del proveedor siguen siendo gestionados por ese servicio, por lo que las carpetas locales, los puntos focales, el recorte y el reemplazo no están disponibles para esos elementos en el editor de recursos de EmDash.

Elimina medios de forma segura

Abre el archivo en la biblioteca de medios, selecciona Delete y confirma la eliminación permanente. Los autores pueden eliminar los archivos locales que han subido ellos mismos; los editores pueden eliminar cualquier archivo local. Los elementos de un proveedor solo se eliminan del proveedor cuando la fuente expone la eliminación y el usuario actual tiene permiso.

Para la automatización de subidas y la gestión de medios, consulta la referencia de los endpoints de medios o los comandos de medios de la CLI. Continúa con Trabajar con contenido para publicar entradas que usen los medios seleccionados.