Libreria media

La Libreria media memorizza immagini, documenti, video e audio riutilizzabili. Gli editor possono caricare i file una sola volta, selezionarli dai campi di contenuto e dal Portable Text e vedere quali voci di contenuto fanno riferimento a un elemento media locale.

Aprire la Libreria media

Seleziona Media nella barra laterale di amministrazione. La libreria principale contiene cartelle e file non collocati in una cartella. Seleziona una cartella per sfogliarne i file, oppure passa tra le viste a griglia e a elenco.

Se il sito ha provider di media esterni, ogni provider appare come un’altra origine. Le capacità dei provider variano: un’origine può supportare navigazione e selezione ma non cartelle, modifica locale delle immagini o eliminazione.

Caricare file

Caricare dalla libreria

I caricamenti iniziano non appena vengono aggiunti i file. I nuovi file locali entrano nella libreria principale, anche se prima del caricamento era aperta un’altra cartella.

Caricare durante la modifica del contenuto

I campi immagine, file, galleria e immagine Portable Text usano un selettore media. Apri il campo, seleziona Upload files e scegli o rilascia i file. Un caricamento completato diventa parte della selezione corrente; i caricamenti non riusciti restano visibili così puoi riprovare o rimuoverli.

Per una galleria, rivedi Selected media e usa i controlli di spostamento per impostare l’ordine prima di selezionare Add images. Per una singola immagine o file, seleziona Select o Insert image dopo che il caricamento è terminato.

File accettati e limite di dimensione

La Libreria media locale accetta questi gruppi di file per impostazione predefinita:

• immagini PNG, JPEG, GIF, WebP e AVIF;
• formati video comuni come MP4, WebM e video QuickTime;
• formati audio comuni come MP3, WAV e audio Ogg; e
• documenti PDF.

SVG è escluso dall’elenco di caricamento predefinito perché i file SVG possono contenere contenuto attivo. Un campo immagine o file può definire il proprio elenco di tipi di file accettati quando il modello di contenuto richiede una selezione più ristretta o un altro formato. EmDash identifica ogni file in base al suo tipo di media, un’etichetta come image/png o application/pdf, e ricontrolla l’elenco del campo quando il contenuto viene salvato. Modificare il selettore file del browser non aggirà quel controllo lato server.

Il massimo predefinito è 50 MB per file. Gli sviluppatori del sito possono modificarlo con maxUploadSize. Un provider può imporre un limite aggiuntivo di formato o dimensione e segnalerà quell’errore nella riga di caricamento.

Trovare e organizzare i file

La ricerca corrisponde a nomi di file parziali. Il filtro tipo limita i risultati a immagini, documenti, video o audio. Una ricerca per nome file copre l’intera libreria locale, anche con una cartella aperta; sfogliare una cartella senza ricerca mostra solo i file assegnati a quella cartella.

Gli editor possono selezionare Add new folder nella libreria principale. Sposta un file locale trascinando la sua scheda o riga su una cartella visibile, oppure apri il file, cambia Location e seleziona Save. Usa Main library come posizione per rimuovere un file dalla cartella corrente.

Gli autori possono spostare i file locali che hanno caricato. Gli editor possono spostare qualsiasi file locale. Gli elementi dei provider esterni non possono essere assegnati alle cartelle della Libreria media.

Eliminare una cartella sposta i suoi file nella libreria principale. Non elimina i file, non cambia i loro URL e non rimuove i loro riferimenti di contenuto.

Selezionare i media per il contenuto

Immagini Portable Text

Posiziona il cursore in un campo Portable Text, apri il menu dei blocchi e seleziona Image. Scegli o carica un’immagine, poi seleziona Insert image. Seleziona poi il blocco immagine per aggiungere testo alternativo, didascalia, dimensioni di visualizzazione e allineamento.

Campi immagine e file

Seleziona l’azione del campo, come Select image o Select file, poi scegli un elemento e conferma la selezione. Le regole MIME-type di un campo limitano quali elementi della libreria e origini media compaiono.

Il campo featured_image del template blog memorizza il valore media selezionato con il post. Salvare la voce salva quel riferimento nella bozza; pubblicare lo rende disponibile alle query di contenuto pubbliche.

Campi galleria

Seleziona una o più immagini, organizzale sotto Selected media e conferma. Una galleria mantiene il proprio ordine e testo alternativo e didascalia per immagine, anche quando più posizioni fanno riferimento a elementi della Libreria media.

Modificare un’immagine usata nel contenuto

Un’immagine locale selezionata offre azioni con ambiti diversi:

• Replace sceglie un elemento diverso della Libreria media per questo campo, blocco o posizione della galleria. Le altre voci che usano l’elemento originale non cambiano.
• Edit asset apre l’elemento sottostante della Libreria media. Le modifiche ai metadati e le modifiche distruttive all’immagine possono interessare altri usi di quell’elemento.
• Remove cancella questo riferimento di contenuto. L’elemento della Libreria media resta disponibile.

Quando Edit asset crea una copia ritagliata, il selettore seleziona la nuova copia per l’uso corrente. Le immagini Portable Text e di galleria mantengono testo alternativo, didascalia, layout e posizione di quell’uso. Quando Edit asset sostituisce l’originale, l’ID media resta lo stesso, così ogni uso di quell’elemento riceve l’immagine modificata.

Le immagini di provider esterni e i campi file offrono Replace e Remove ma non aprono l’editor di asset locale.

Sostituire un’immagine locale

Replace image carica nuovi byte dietro un elemento esistente della Libreria media. Usalo quando ogni luogo che fa riferimento all’elemento deve mostrare una nuova versione dell’immagine.

L’azione è disponibile per elementi JPEG, PNG e WebP pronti. Gli autori possono sostituire le immagini che hanno caricato; gli editor possono sostituire qualsiasi immagine locale.

EmDash conserva l’ID media, il nome file, l’URL, il testo alternativo, la didascalia e la cartella. I riferimenti di contenuto esistenti continuano quindi a funzionare e mostrano la sostituzione. La sostituzione cancella il punto focale salvato perché le sue coordinate potrebbero non descrivere la nuova immagine.

Usa invece Replace nell’editor di contenuto quando solo un campo o un blocco immagine deve cambiare.

Impostare un punto focale

Un punto focale contrassegna la parte di un’immagine che deve restare visibile quando un layout ritaglia l’immagine per riempire un quadrato, un paesaggio, un ritratto o un’altra forma fissa.

Seleziona Reset per rimuovere il punto personalizzato. Quando scegli un’immagine per un campo o una galleria, EmDash copia il punto focale corrente dell’asset in quel valore di contenuto. Il contenuto che già usa l’immagine conserva il punto memorizzato finché non selezioni di nuovo l’immagine. Aprire Edit asset da un campo di contenuto aggiorna quell’uso corrente con il punto che salvi.

Ritagliare un’immagine locale

Il ritaglio è disponibile per immagini JPEG, PNG e WebP pronte memorizzate da EmDash. Le immagini di provider esterni non possono essere ritagliate nell’editor di asset locale.

Replace original è disponibile solo con il rapporto di aspetto Original. Usa Create cropped copy per Freeform e gli altri rapporti. Una copia ritagliata resta nella stessa cartella della sorgente e riceve un nome file univoco.

Ritagliare un WebP animato crea un WebP statico. Il risultato ritagliato non conserva l’animazione.

Vedere dove viene usato un file

Apri un file locale e seleziona Used in per elencare le voci di contenuto e le impostazioni del sito che vi fanno riferimento. Ogni risultato di contenuto indica la collezione e i campi che contengono il riferimento e può aprire la voce per la modifica. Le voci nel cestino sono identificate nell’elenco. Un risultato Site Settings indica le impostazioni che selezionano il file: Logo, Favicon o Default Social Image.

Used in controlla questi riferimenti:

• campi immagine e file
• campi immagine nei repeater
• campi immagine, file e Portable Text nei campi blocks
• blocchi immagine e galleria nei campi Portable Text
• il logo del sito, il favicon e l’immagine social predefinita

Quando la copertura d’uso è completa e il file non ha nessuno di questi riferimenti, l’elenco mostra No tracked references found. Finché la copertura non è completa, un elenco vuoto mostra No usage to show yet.

Il tracciamento dell’uso dei media deve essere attivo prima che i risultati di contenuto possano essere completi. Le impostazioni del sito sono elencate indipendentemente dal fatto che il tracciamento sia attivo. Un amministratore attiva il tracciamento una volta per il sito:

Una volta abilitato, il tracciamento dell’uso dei media non può essere disattivato. Le nuove modifiche di contenuto vengono tracciate dopo che la cattura diventa attiva; la scansione in background aggiunge riferimenti dalle voci già esistenti.

Se la vista Used in segnala che l’indicizzazione è in corso, obsoleta, parziale o non riuscita, tratta i suoi risultati come incompleti. Un amministratore può tornare a Media usage tracking per lo stato corrente e le indicazioni di ripristino.

Renderizzare un’immagine in un template

I campi immagine restituiscono un valore media anziché un URL semplice. Renderizza quel valore con Image da emdash/ui così che le immagini locali e quelle basate sul provider usino URL, dimensioni, punto focale, varianti responsive e placeholder a bassa qualità appropriati:

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

Usa priority solo per l’immagine principale visibile in cima alla pagina. Richiede il caricamento eager e dà al browser un hint di alta priorità di fetch. Le altre immagini devono mantenere il lazy-loading predefinito del componente.

Se il campo ha una controparte in modalità scura, Image renderizza entrambe le origini e ne seleziona una dallo schema colori del visitatore. Vedi Immagini in modalità scura per la configurazione del campo e del template.

Il template riceve i metadati media memorizzati con il riferimento di contenuto senza un’altra query alla Libreria media. Se un’integrazione personalizzata richiede i metadati più recenti del provider, richiedi quell’elemento esplicitamente ed evita una ricerca provider per immagine su una pagina di collezione. Il riferimento ai tipi di campo descrive i valori file e immagine memorizzati.

Configurare archiviazione e provider

La libreria locale memorizza i file tramite l’adapter di archiviazione configurato del sito. I siti Node.js possono usare disco locale o archiviazione compatibile S3; i siti Cloudflare usano comunemente un binding R2. L’adapter decide dove vengono memorizzati i byte, mentre la Libreria media mantiene lo stesso flusso di authoring. Vedi Archiviazione media per la configurazione e i requisiti di persistenza in produzione.

Cloudflare Images e Cloudflare Stream possono essere registrati come provider di media esterni. Compaiono come origini nel selettore e Image comprende i valori immagine basati sul provider. Gli elementi del provider restano gestiti da quel servizio, quindi cartelle locali, punti focali, ritaglio e sostituzione non sono disponibili per quegli elementi nell’editor di asset EmDash.

Eliminare i media in sicurezza

Apri un file nella Libreria media, seleziona Delete e conferma l’eliminazione permanente. Gli autori possono eliminare i file locali che hanno caricato; gli editor possono eliminare qualsiasi file locale. Un elemento provider viene eliminato dal suo provider solo quando quell’origine espone l’eliminazione e l’utente corrente ha l’autorizzazione.

Per caricamenti automatizzati e gestione dei media, vedi il riferimento agli endpoint media o i comandi media della CLI. Continua con Lavorare con i contenuti per pubblicare voci che usano i media selezionati.