Biblioteca de medios

La Biblioteca de medios almacena imágenes, documentos, vídeo y audio reutilizables. Los editores pueden subir archivos una vez, seleccionarlos desde campos de contenido y Portable Text, y ver qué entradas de contenido hacen referencia a un elemento de medios local.

Abrir la Biblioteca de medios

Seleccione Media en la barra lateral de administración. La biblioteca principal contiene carpetas y archivos que no se han colocado en una carpeta. Seleccione una carpeta para examinar sus archivos, o alterne entre las vistas de cuadrícula y lista.

Si el sitio tiene proveedores de medios externos, cada proveedor aparece como otra fuente. Las capacidades del proveedor varían: una fuente puede admitir examinar y seleccionar pero no carpetas, edición local de imágenes o eliminación.

Subir archivos

Subir desde la biblioteca

Las cargas comienzan en cuanto se añaden archivos. Los archivos locales nuevos entran en la biblioteca principal, incluso si había otra carpeta abierta antes de la carga.

Subir al editar contenido

Los campos de imagen, archivo, galería e imagen de Portable Text usan un selector de medios. Abra el campo, seleccione Upload files y elija o suelte archivos. Una carga completada forma parte de la selección actual; las cargas fallidas permanecen visibles para que pueda reintentarlas o eliminarlas.

Para una galería, revise Selected media y use los controles de movimiento para establecer el orden antes de seleccionar Add images. Para una sola imagen o archivo, seleccione Select o Insert image después de que termine la carga.

Archivos aceptados y límite de tamaño

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

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

SVG está excluido de la lista de carga predeterminada porque los archivos SVG pueden contener contenido activo. Un campo de imagen o archivo puede definir su propia lista de tipos de archivo aceptados cuando el modelo de contenido necesita una selección más estrecha u otro formato. 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 al guardar el contenido. Cambiar el selector de archivos del navegador no evita esa comprobación del servidor.

El máximo predeterminado es 50 MB por archivo. Los desarrolladores del sitio pueden cambiarlo con maxUploadSize. Un proveedor puede imponer un límite adicional de formato o tamaño e informará ese fallo en la fila de carga.

Buscar y organizar archivos

La búsqueda coincide con nombres de archivo parciales. El filtro de tipo limita los resultados a imágenes, documentos, vídeo o audio. Una búsqueda por nombre de archivo cubre toda la biblioteca local, incluso con una carpeta abierta; examinar una carpeta sin búsqueda muestra solo los archivos asignados a esa carpeta.

Los editores pueden seleccionar Add new folder en la biblioteca principal. Mueva un archivo local arrastrando su tarjeta o fila a una carpeta visible, o abra el archivo, cambie Location y seleccione Save. Use Main library como ubicación para quitar un archivo de su carpeta actual.

Los autores pueden mover archivos locales que subieron. Los editores pueden mover cualquier archivo local. Los elementos de proveedores externos no se pueden asignar a carpetas de la Biblioteca de medios.

Eliminar una carpeta mueve sus archivos de vuelta a la biblioteca principal. No elimina los archivos, no cambia sus URL ni quita sus referencias de contenido.

Seleccionar medios para el contenido

Imágenes de Portable Text

Coloque el cursor en un campo Portable Text, abra el menú de bloques y seleccione Image. Elija o suba una imagen y luego seleccione Insert image. Seleccione el bloque de imagen después para añadir texto alternativo, un pie de foto, dimensiones de visualización y alineación.

Campos de imagen y archivo

Seleccione la acción del campo, como Select image o Select file, luego elija un elemento y confirme la selección. Las reglas de tipo MIME de un campo limitan qué elementos de la biblioteca y fuentes de medios aparecen.

El campo featured_image de la plantilla de blog almacena el valor de medios seleccionado con la publicación. Guardar la entrada guarda esa referencia en el borrador; publicar la hace disponible para consultas de contenido públicas.

Campos de galería

Seleccione una o más imágenes, organícelas bajo Selected media y confirme. Una galería mantiene su propio orden y texto alternativo y pie de foto por imagen, incluso cuando varias posiciones hacen referencia a elementos de la Biblioteca de medios.

Editar una imagen usada en el contenido

Una imagen local seleccionada ofrece acciones con distintos alcances:

• Replace elige un elemento diferente de la Biblioteca de medios para este campo, bloque o posición de galería. Otras 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 imagen pueden afectar 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 de medios permanece igual, por lo que cada uso de ese elemento recibe la imagen cambiada.

Las imágenes de proveedores externos y los campos de archivo ofrecen Replace y Remove pero no abren el editor de activos local.

Reemplazar una imagen local

Replace image sube nuevos bytes detrás de un elemento existente de la Biblioteca de medios. Úselo cuando todos los lugares que hacen referencia al elemento deben mostrar una nueva versión de la imagen.

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

EmDash conserva el ID de medios, el nombre de archivo, la URL, el texto alternativo, el pie de foto y la carpeta. Por tanto, las referencias de contenido existentes siguen funcionando y muestran el reemplazo. El reemplazo borra el punto focal guardado porque sus coordenadas pueden no describir la nueva imagen.

Use Replace en el editor de contenido en su lugar cuando solo deba cambiar un campo o bloque de imagen.

Establecer un punto focal

Un punto focal marca la parte de una imagen que debe permanecer visible cuando un diseño recorta la imagen para llenar un cuadrado, paisaje, retrato u otra forma fija.

Seleccione Reset para quitar el punto personalizado. Al elegir una imagen para un campo o galería, EmDash copia el punto focal actual del activo en ese valor de contenido. El contenido que ya usa la imagen conserva su punto almacenado hasta que seleccione la imagen de nuevo. Abrir Edit asset desde un campo de contenido actualiza ese uso actual con el punto que guarda.

Recortar una imagen local

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

Replace original solo está disponible con la relación de aspecto Original. Use Create cropped copy para Freeform y las demás proporciones. Una copia recortada permanece en la misma carpeta que su fuente y recibe un nombre de archivo único.

Recortar un WebP animado crea un WebP estático. El resultado recortado no conserva la animación.

Ver dónde se usa un archivo

Abra un archivo local y seleccione Used in para listar las entradas de contenido y la configuración del sitio que hacen referencia a él. Cada resultado de contenido nombra la colección y los campos que contienen la referencia y puede abrir la entrada para editarla. Las entradas en la papelera se identifican en la lista. Un resultado Site Settings nombra la configuración que selecciona el archivo: Logo, Favicon o Default Social Image.

Used in comprueba estas referencias:

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

Cuando la cobertura de uso está completa y el archivo no tiene ninguna de estas referencias, la lista muestra No tracked references found. Hasta que la cobertura esté completa, una lista vacía muestra No usage to show yet.

El seguimiento de uso de medios debe estar activo antes de que los resultados de contenido puedan estar completos. La configuración del sitio se lista tanto si el seguimiento está activo como si no. Un administrador activa el seguimiento una vez para el sitio:

Una vez habilitado, el seguimiento de uso de medios no se puede desactivar. Los nuevos cambios de contenido se rastrean después de que la captura se active; el escaneo en segundo plano añade referencias de entradas que ya existían.

Si la vista Used in informa que la indexación está en ejecución, obsoleta, parcial o fallida, trate sus resultados como incompletos. Un administrador puede volver a Media usage tracking para el estado actual y la orientación de recuperación.

Renderizar una imagen en una plantilla

Los campos de imagen devuelven un valor de medios en lugar de una URL simple. Renderice ese valor con Image de emdash/ui para que las imágenes locales y respaldadas por proveedores usen la URL, dimensiones, punto focal, variantes responsivas y 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.redirect("/404");
---

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

Use priority solo para la imagen principal visible en la parte superior de la página. Solicita carga eager y da al navegador una pista de alta prioridad de obtención. Otras imágenes deben conservar el valor predeterminado de carga diferida del componente.

Si el campo tiene una contraparte en modo oscuro, Image renderiza ambas fuentes y selecciona una según el esquema de color del visitante. Consulte Imágenes en modo oscuro para la configuración del campo y la plantilla.

La plantilla recibe los metadatos de medios almacenados con la referencia de contenido sin otra consulta a la Biblioteca de medios. Si una integración personalizada requiere los metadatos más recientes del proveedor, solicite ese elemento explícitamente y evite una búsqueda por proveedor por imagen en una página de colección. La referencia de tipos de campo describe los valores de archivo e imagen almacenados.

Configurar almacenamiento y proveedores

La biblioteca local almacena archivos a través del adaptador de almacenamiento configurado del sitio. Los sitios Node.js pueden usar disco local o almacenamiento compatible con S3; los sitios Cloudflare suelen usar un binding R2. El adaptador decide dónde se almacenan los bytes, mientras que la Biblioteca de medios mantiene el mismo flujo de autoría. Consulte Almacenamiento de medios para la configuración y los requisitos de persistencia en producción.

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

Eliminar medios de forma segura

Abra un archivo en la Biblioteca de medios, seleccione Delete y confirme la eliminación permanente. Los autores pueden eliminar archivos locales que subieron; los editores pueden eliminar cualquier archivo local. Un elemento de proveedor se elimina de su proveedor solo cuando esa fuente expone la eliminación y el usuario actual tiene permiso.

Para cargas automatizadas y gestión de medios, consulte la referencia de endpoints de medios o los comandos de medios de la CLI. Continúe con Trabajar con contenido para publicar entradas que usen los medios seleccionados.