Libreria multimediale

La libreria multimediale archivia immagini, documenti, video e audio riutilizzabili. Gli editor caricano un file una sola volta, lo selezionano nei campi dei contenuti e in Portable Text, e vedono quali voci di contenuto fanno riferimento a un elemento multimediale locale.

Aprire la libreria multimediale

Seleziona Media nella barra laterale dell’amministrazione. La Main library contiene le cartelle e i file che non sono ancora in nessuna cartella. Seleziona una cartella per sfogliarne i file e passa dalla vista a griglia alla vista a elenco quando serve.

Se il tuo sito ha provider di media esterni, ogni provider compare come un’altra sorgente. Le funzionalità dei provider variano: una sorgente può supportare la navigazione e la selezione, ma non le cartelle, la modifica locale delle immagini o l’eliminazione.

Caricare i file

Caricare dalla libreria

I caricamenti iniziano non appena aggiungi i file. I nuovi file locali vanno nella Main library, anche se prima del caricamento era aperta un’altra cartella.

Caricare durante la modifica dei contenuti

I campi immagine, file, galleria e immagine Portable Text usano il selettore multimediale. Apri il campo, seleziona Upload files, poi scegli o rilascia i file. I caricamenti completati diventano parte della selezione corrente; i caricamenti non riusciti restano visibili così puoi riprovarli o rimuoverli.

Per una galleria, controlla Selected media e imposta l’ordine con i controlli di spostamento prima di selezionare Add images. Per una singola immagine o un singolo file, seleziona Select o Insert image al termine del caricamento.

File accettati e limiti di dimensione

La libreria multimediale locale accetta per impostazione predefinita questi gruppi di file:

• 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 un proprio elenco di tipi di file accettabili quando il tuo modello di contenuto richiede una selezione più ristretta o altri formati. 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. Cambiare il selettore di file del browser non aggira questo controllo lato server.

Il massimo predefinito è 50 MB per file. Gli sviluppatori del sito possono modificarlo con maxUploadSize. I provider possono imporre ulteriori restrizioni di formato o dimensione e segnalano l’errore nella riga di caricamento.

Trovare e organizzare i file

La ricerca trova corrispondenze in parti del nome del file. Il filtro per tipo limita i risultati a immagini, documenti, video o audio. La ricerca per nome file copre l’intera libreria locale anche quando una cartella è aperta; sfogliando una cartella senza cercare, vengono mostrati solo i file assegnati a quella cartella.

Gli editor possono selezionare Add new folder nella Main library. Per spostare un file locale, trascina la sua scheda o la sua riga su una cartella visibile, oppure apri il file, cambia Location e seleziona Save. Usa Main library come posizione per portare un file fuori dalla sua cartella attuale.

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

L’eliminazione di una cartella riporta i suoi file nella Main library. Non elimina i file, non cambia i loro URL e non rimuove i loro riferimenti di contenuto.

Selezionare i media per i contenuti

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 quindi il blocco immagine per aggiungere testo alternativo, didascalia, dimensione di visualizzazione e allineamento.

Campi immagine e file

Seleziona l’azione del campo, ad esempio Select image o Select file, scegli un elemento e conferma la selezione. Le regole del tipo MIME del campo limitano gli elementi della libreria e le sorgenti multimediali mostrati.

Il campo featured_image del template del blog salva il valore multimediale selezionato insieme all’articolo. Salvando la voce, quel riferimento viene memorizzato nella bozza; la pubblicazione lo rende disponibile per le query pubbliche dei contenuti.

Campi galleria

Seleziona una o più immagini, disponile in Selected media e conferma. La galleria mantiene un proprio ordine e il testo alternativo e la didascalia di ciascuna immagine, anche quando più posizioni fanno riferimento allo stesso elemento della libreria multimediale.

Modificare un’immagine usata nei contenuti

Un’immagine locale selezionata offre azioni con ambiti diversi:

• Replace sceglie un altro elemento della libreria multimediale 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 multimediale. Le modifiche ai metadati e le modifiche distruttive all’immagine possono influire sugli altri usi di quell’elemento.
• Remove cancella questo riferimento di contenuto. L’elemento della libreria multimediale resta disponibile.

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

I campi immagine e file dei provider esterni offrono Replace e Remove, ma non aprono l’editor locale delle risorse.

Sostituire un’immagine locale

Replace image carica nuovi byte dietro un elemento esistente della libreria multimediale. Usalo quando ogni posto che fa riferimento a quell’elemento deve mostrare la nuova versione dell’immagine.

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

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

Se deve cambiare solo un campo o un blocco immagine, usa invece Replace nell’editor dei contenuti.

Impostare un punto focale

Un punto focale indica la parte di un’immagine che deve restare visibile quando un layout ritaglia l’immagine in una forma quadrata, orizzontale, verticale o in un’altra forma fissa.

Seleziona Reset per rimuovere il punto personalizzato. Quando selezioni un’immagine per un campo o una galleria, EmDash copia il punto focale attuale della risorsa in quel valore di contenuto. I contenuti che usano già l’immagine mantengono il punto salvato finché non selezioni di nuovo l’immagine. Quando apri Edit asset da un campo di contenuto, il punto che salvi aggiorna quell’uso corrente.

Ritagliare un’immagine locale

Il ritaglio è disponibile per le immagini JPEG, PNG e WebP pronte e archiviate da EmDash. Le immagini dei provider esterni non possono essere ritagliate nell’editor locale delle risorse.

Replace original è disponibile solo con le proporzioni Original. Per Freeform e le altre proporzioni, usa Create cropped copy. Le copie ritagliate vengono salvate nella stessa cartella dell’elemento di origine e ricevono un nome di file univoco.

Il ritaglio di un WebP animato produce un WebP statico. L’animazione non viene conservata nel risultato ritagliato.

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 lo referenziano. Ogni risultato di contenuto indica la collezione e il campo che contengono il riferimento e apre la voce per la modifica. Le voci nel cestino sono identificate nell’elenco. Un risultato Site Settings indica l’impostazione che seleziona il file: Logo, Favicon o Default Social Image.

Used in controlla questi riferimenti:

• campi immagine e file
• campi immagine all’interno dei ripetitori
• campi immagine, file e Portable Text all’interno dei campi blocks
• blocchi immagine, galleria e video nei campi Portable Text
• il logo del sito, la favicon e l’immagine social predefinita

Quando la copertura dell’utilizzo è completa e il file non ha nessuno di questi riferimenti, l’elenco mostra No tracked references found. Prima che la copertura sia completa, un elenco vuoto mostra No usage to show yet.

Il tracciamento dell’utilizzo dei media deve essere abilitato perché i risultati dei contenuti possano essere completi. Le impostazioni del sito vengono elencate sia che il tracciamento sia abilitato sia che non lo sia. Un amministratore abilita il tracciamento una sola volta per il sito:

Una volta abilitato, il tracciamento dell’utilizzo dei media non può essere disabilitato. Le nuove modifiche ai contenuti vengono tracciate dopo che l’acquisizione è attiva; la scansione in background aggiunge i riferimenti dalle voci che esistevano già.

Se la vista Used in segnala che l’indicizzazione è in corso, obsoleta, parziale o non riuscita, considera i suoi risultati incompleti. Gli amministratori possono tornare a Media usage tracking per vedere lo stato attuale e le indicazioni di ripristino.

Renderizzare le immagini nei template

Un campo immagine restituisce un valore multimediale, non un semplice URL. Renderizza quel valore con Image da emdash/ui in modo che le immagini locali e quelle fornite dai provider usino l’URL, le dimensioni, il punto focale, le varianti responsive e il segnaposto 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.rewrite("/404");
---

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

Usa priority solo per l’immagine principale visibile nella parte superiore della pagina. Richiede il caricamento immediato e dà al browser un suggerimento di priorità di fetch alta. Le altre immagini dovrebbero mantenere il caricamento differito, che è il valore predefinito del componente.

Se il campo ha un’immagine per la modalità scura, Image renderizza entrambe le sorgenti e ne sceglie una in base allo schema di colori del visitatore. Consulta Varianti scure delle immagini per la configurazione del campo e del template.

I template ricevono i metadati del media memorizzati insieme al riferimento di contenuto senza interrogare di nuovo la libreria multimediale. Se un’integrazione personalizzata ha bisogno dei metadati più recenti del provider, richiedi esplicitamente quell’elemento ed evita di interrogare il provider per ogni immagine nelle pagine delle collezioni. Il riferimento ai tipi di campo descrive i valori di file e immagine memorizzati.

Renderizzare un file in un template

Il valore di un campo file della libreria multimediale non contiene un URL già pronto. Passa il suo meta.storageKey a Astro.locals.emdash.getPublicMediaUrl(), che restituisce l’URL pubblico e rispetta un dominio pubblico R2 o S3 configurato senza interrogare la tabella dei media. I valori meno recenti senza chiave di archiviazione mantengono il loro URL in url, e i file aggiunti tramite URL (salvati con provider: "external") lo mantengono in src.

Per un file di un provider di media registrato, come Cloudflare Stream, src contiene un’immagine di anteprima anziché il file stesso, quindi questo approccio non si applica.

La pagina seguente renderizza un video salvato in un campo file video:

---
import { getEmDashEntry } from "emdash";

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

const file = entry.data.video;
const storageKey = typeof file?.meta?.storageKey === "string" ? file.meta.storageKey : undefined;
const url = storageKey
  ? Astro.locals.emdash?.getPublicMediaUrl?.(storageKey)
  : file?.provider === "external"
    ? file.src
    : file?.url;
---

{url && <video src={url} controls preload="metadata" />}

Lo stesso URL funziona per un link di download o per qualsiasi altro elemento che abbia bisogno dell’indirizzo del file. Il nome del file, il tipo MIME e la dimensione nel valore sono quelli salvati quando il file è stato selezionato.

Configurare archiviazione e provider

La libreria locale archivia i file tramite l’adattatore di archiviazione configurato per il sito. I siti Node.js possono usare il disco locale o un’archiviazione compatibile con S3; i siti Cloudflare di solito usano un binding R2. L’adattatore decide dove risiedono i byte, e la libreria multimediale mantiene lo stesso flusso di lavoro di creazione. Consulta Scegliere l’archiviazione dei 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 sorgenti nel selettore, e Image comprende i valori di immagine forniti dai provider. Gli elementi del provider restano gestiti da quel servizio, quindi cartelle locali, punti focali, ritaglio e sostituzione non sono disponibili per questi elementi nell’editor delle risorse di EmDash.

Eliminare i media in sicurezza

Apri il file nella libreria multimediale, seleziona Delete e conferma l’eliminazione definitiva. Gli autori possono eliminare i file locali che hanno caricato loro stessi; gli editor possono eliminare qualsiasi file locale. Gli elementi di un provider vengono eliminati dal provider solo quando la sorgente espone l’eliminazione e l’utente corrente ha il permesso.

Per l’automazione dei caricamenti e la gestione dei media, consulta il riferimento agli endpoint media o i comandi media della CLI. Prosegui con Lavorare con i contenuti per pubblicare le voci che usano i media selezionati.