Libreria multimediale

EmDash include una libreria multimediale per gestire immagini, documenti e altri file. Questa guida copre il caricamento, la ricerca e l’utilizzo dei media nei tuoi contenuti.

Accesso alla libreria multimediale

Apri la libreria multimediale dalla barra laterale dell’admin cliccando su Media. La libreria principale mostra cartelle e file che non sono assegnati a una cartella. Apri una cartella per vedere i suoi file.

Utilizzato in

Apri un file nella libreria multimediale di EmDash per vedere le entry di contenuto che lo referenziano. Mentre EmDash scansiona il contenuto esistente, la lista include i riferimenti trovati finora e potrebbe essere incompleta.

Attivare il tracciamento dell’uso dei media

Se il tracciamento dell’uso dei media è disattivato, un amministratore può attivarlo:

1. Completa qualsiasi modifica di contenuto. Se un’altra applicazione scrive direttamente nel database dei contenuti, mettila in pausa e attendi che le scritture in corso terminino.
2. Apri Impostazioni → Tracciamento uso media, seleziona Abilita tracciamento, poi conferma.
3. Quando la pagina mostra Indicizzazione contenuto esistente, le modifiche e altre scritture nel database possono riprendere.
4. Mantieni la pagina aperta fino a quando mostra Pronto. Se esci, torna per continuare dal progresso salvato.

Una volta attivato il tracciamento dell’uso dei media, non può essere disattivato.

Caricare file

Dalla libreria multimediale

1. Apri Media nella barra laterale dell’admin.

2. Seleziona Carica file, poi Sfoglia file per scegliere uno o più file. Puoi anche trascinare file ovunque nella libreria multimediale.

3. I caricamenti iniziano automaticamente. La finestra di dialogo mostra lo stato di ogni file e permette di annullare o riprovare singoli file.

Dall’editor di contenuto

1. Apri un campo immagine, file o galleria nell’editor di contenuto.

2. Cerca, filtra per tipo, naviga in una cartella o passa tra le sorgenti media disponibili.

3. Seleziona media esistenti, o seleziona Carica file e scegli file dal tuo computer. Puoi anche rilasciare file sul picker. Ogni caricamento appare nei risultati con il suo stato attuale.

4. Se un caricamento fallisce, seleziona Riprova o Rimuovi su quell’elemento. Un caricamento riuscito diventa una scheda media selezionata.

5. Per una galleria, usa i controlli freccia sotto Media selezionati per impostare l’ordine.

6. Seleziona l’azione del picker, come Seleziona, Inserisci immagine o Aggiungi 3 immagini.

Tipi di file supportati

EmDash accetta questi tipi di file per impostazione predefinita:

I campi immagine e file possono consentire altri tipi MIME, incluso image/svg+xml per file SVG.

Backend di archiviazione

EmDash supporta più backend di archiviazione. Configura l’archiviazione nella tua configurazione Astro:

import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: local({
        directory: "./uploads",
        baseUrl: "/_emdash/api/media/file",
      }),
    }),
  ],
});

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      storage: r2({
        binding: "MEDIA_BUCKET",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

{
	"r2_buckets": [
		{
			"binding": "MEDIA_BUCKET",
			"bucket_name": "my-media-bucket",
		},
	],
}

import { defineConfig } from "astro/config";
import emdash, { s3 } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: s3({
        endpoint: "https://s3.amazonaws.com",
        bucket: "my-media-bucket",
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
        region: "us-east-1",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

Come funzionano i caricamenti

L’admin usa il flusso di destinazione caricamento:

1. Il client richiede una destinazione di caricamento, e EmDash crea un elemento multimediale in sospeso.

2. Il client carica il file nella destinazione restituita.

3. Il client conferma il caricamento.

4. EmDash valida il file archiviato e contrassegna l’elemento multimediale come pronto.

L’archiviazione compatibile S3 restituisce un URL firmato affinché il file possa bypassare il runtime dell’applicazione. L’archiviazione locale e R2 nativo restituiscono invece un endpoint di streaming same-origin.

Trovare media

Ricerca

Usa la casella di ricerca per trovare file per nome. La ricerca corrisponde a nomi di file parziali.

Filtrare per tipo

Usa il filtro per tipo per mostrare immagini, documenti, file video o audio.

Organizzare i media in cartelle

Gli editor possono selezionare Aggiungi nuova cartella dalla libreria principale. Apri una cartella selezionando il suo nome. Senza un termine di ricerca, le pagine delle cartelle mostrano solo i media assegnati a quella cartella. Le ricerche per nome file coprono l’intera libreria, incluse altre cartelle e la libreria principale.

Per spostare un file locale in una cartella visibile, trascina la sua scheda griglia o riga elenco sulla cartella. Puoi anche aprire Dettagli media, scegliere una Posizione e selezionare Salva. Usa Posizione per riportare un file nella libreria principale o per spostarlo senza trascinare.

Gli autori possono spostare i file locali che hanno caricato. Gli editor possono spostare qualsiasi file locale. I file da fornitori esterni non possono essere assegnati a cartelle.

I caricamenti entrano nella libreria principale. Spostali in una cartella dopo il caricamento usando uno dei metodi sopra.

L’eliminazione di una cartella restituisce i suoi media alla libreria principale. I file multimediali, gli URL e i riferimenti al contenuto rimangono invariati.

Usare i media nel contenuto

Nell’editor di testo ricco

1. Posiziona il cursore dove vuoi l’immagine

2. Clicca il pulsante immagine nella barra degli strumenti

3. Trova un’immagine nel picker o caricane una nuova.

4. Seleziona Inserisci immagine.

5. Aggiungi testo alternativo nelle impostazioni dell’immagine.

Come immagine in evidenza

1. Apri un’entry di contenuto nell’editor

2. Trova il campo Immagine in evidenza nella barra laterale

3. Clicca su Seleziona immagine

4. Scegli un’immagine dal picker o caricane una.

5. Seleziona Seleziona, poi Salva.

Nei campi personalizzati

Per i campi configurati come tipi immagine o file, seleziona l’azione del campo per aprire lo stesso picker multimediale. Le regole del tipo MIME del campo limitano le sorgenti e i file che puoi scegliere.

Modificare un asset immagine selezionato

I campi immagine locali, le immagini di testo ricco e le immagini di galleria forniscono tre azioni:

• Sostituisci cambia l’immagine usata nel campo, blocco o posizione di galleria corrente.
• Modifica asset apre i Dettagli media per l’elemento selezionato della Libreria multimediale. Puoi aggiornare il suo testo alternativo, didascalia, punto focale o ritaglio restando nell’editor di contenuto.
• Rimuovi cancella il riferimento al contenuto corrente. L’elemento della Libreria multimediale rimane disponibile.

Crea copia ritagliata seleziona la nuova copia per l’uso corrente. Le immagini di testo ricco e galleria mantengono il loro testo alternativo, didascalia, layout e posizione per uso. Sostituisci originale mantiene lo stesso riferimento multimediale e cambia l’immagine ovunque quell’asset sia usato.

Le immagini di fornitori esterni e i campi file forniscono Sostituisci e Rimuovi, ma non Modifica asset.

Sostituire un’immagine

Usa Sostituisci immagine per aggiornare il file dietro un elemento multimediale locale esistente. Gli autori possono sostituire le immagini che hanno caricato, e gli editor possono sostituire qualsiasi immagine locale. L’azione è disponibile per immagini JPEG, PNG e WebP archiviate su disco locale, Cloudflare R2 o archiviazione compatibile S3.

1. Apri Media, poi seleziona un’immagine dalla libreria locale.
2. Resta su Dettagli, poi seleziona Sostituisci immagine.
3. Scegli un’immagine non vuota nello stesso formato del file esistente.
4. Verifica l’avvertimento, poi seleziona Sostituisci immagine per confermare.

La sostituzione può usare dimensioni diverse o un rapporto d’aspetto diverso dall’immagine esistente. EmDash mantiene l’ID del media, il nome file, l’URL, il testo alternativo, la didascalia e la posizione, quindi ogni riferimento esistente usa la sostituzione. Sostituire il file cancella il suo punto focale.

Sostituisci immagine carica un altro file dal tuo computer. Per ritagliare l’immagine corrente, seleziona Sostituisci originale dall’editor di Ritaglio.

Impostare un punto focale

Un punto focale mantiene visibile la parte importante di un’immagine locale quando una scheda, galleria o altro layout la ritaglia per riempire una forma fissa.

1. Apri Media e seleziona un’immagine dalla libreria locale, o seleziona Modifica asset per un’immagine locale nell’editor di contenuto.
2. Seleziona Modifica immagine, poi Punto focale.
3. Clicca o trascina il marcatore sulla parte importante dell’immagine. Puoi anche usare i tasti freccia.
4. Controlla le anteprime quadrata, orizzontale e verticale, poi seleziona Salva.

Seleziona Reimposta per rimuovere un punto focale personalizzato. Il punto salvato viene copiato quando selezioni l’immagine per un campo di contenuto o galleria. Altro contenuto che già usa l’immagine mantiene il suo punto memorizzato fino a quando selezioni l’immagine di nuovo. Quando modifichi un asset da un campo di contenuto o galleria, quell’uso corrente si aggiorna con il punto focale salvato.

Ritagliare un’immagine

Il ritaglio è disponibile per immagini JPEG, PNG e WebP caricate su EmDash. Funziona con archiviazione locale, Cloudflare R2 e archiviazione compatibile S3. Le immagini da fornitori di media esterni non possono essere ritagliate nella Libreria multimediale.

1. Apri Media, poi seleziona un’immagine dalla libreria locale.
2. Seleziona Modifica immagine, poi Ritaglia.
3. Seleziona Originale, Forma libera o un rapporto d’aspetto comune. I rapporti fissi restano bloccati durante il ridimensionamento. Forma libera ti permette di cambiare larghezza e altezza indipendentemente.
4. Sposta il riquadro di ritaglio sull’immagine. Per un rapporto fisso, trascina un angolo per ridimensionare. Forma libera fornisce anche quattro maniglie di bordo. La griglia dei terzi resta visibile. Puoi focalizzare il riquadro o una maniglia e usare i tasti freccia. Tieni premuto Shift per passi più grandi.
5. Seleziona una delle azioni di ritaglio:
   • Crea copia ritagliata crea un elemento multimediale separato e lascia l’originale invariato. Seleziona la copia ritagliata in ogni entry di contenuto dove vuoi usarla.
   • Sostituisci originale sostituisce l’immagine ovunque l’elemento multimediale sia usato. Le entry di contenuto esistenti mantengono lo stesso riferimento multimediale e non vengono riscritte o ripubblicate.

Il ritaglio di un file WebP produce un’immagine WebP statica. Se la sorgente è animata, il risultato ritagliato non mantiene l’animazione.

Visualizzare i media nei template

Accedi agli URL dei media dai tuoi dati di contenuto:

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

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <img
    src={post.data.featured_image}
    alt={post.data.featured_image_alt ?? ""}
  />
)}

Immagini responsive

Per i campi media di EmDash, usa il componente Image da emdash/ui:

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

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    image={post.data.featured_image}
    width={800}
    height={450}
    priority
  />
)}

priority è per l’immagine principale above-the-fold. Imposta loading="eager" e fetchpriority="high": loading controlla se il caricamento è differito, e fetchpriority dà al browser un suggerimento di priorità per la richiesta.

Quando il valore del campo porta una controparte scura, Image renderizza entrambe e mostra quella corrispondente allo schema di colori del visitatore. Modalità scura copre l’abilitazione dello slot su un campo e la convenzione di classe <html> su cui il componente si basa.

EmDash installa un endpoint immagine che produce le varianti ridimensionate su richiesta. Su Cloudflare Workers quell’endpoint usa il binding IMAGES. Trasformazione immagini copre da dove proviene il binding e cosa succede quando è assente.

Eliminare media

1. Seleziona il/i file che vuoi eliminare

2. Clicca Elimina

3. Conferma l’eliminazione

API dei media

Usa l’API REST per caricare, elencare, aggiornare, eliminare e organizzare i media locali. Il riferimento degli endpoint dei media documenta il caricamento multipart diretto e i flussi di destinazione caricamento, parametri di richiesta, forme di risposta, permessi e operazioni sulle cartelle.

Fornitori di media

Oltre all’archiviazione locale, EmDash supporta fornitori di media esterni per hosting specializzato di immagini e video. I fornitori di media appaiono come tab nel picker multimediale, permettendo agli editor di scegliere da più sorgenti.

Fornitori disponibili

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      // ... configurazione database, archiviazione
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          // Opzionale: dominio di distribuzione personalizzato
          deliveryDomain: "images.example.com",
        }),
      ],
    }),
  ],
});

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      // ... configurazione database, archiviazione
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          // Opzionale: impostazioni del player
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

Usare più fornitori

Puoi configurare più fornitori. Ognuno appare come un tab nel picker multimediale:

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages, cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      database: d1({ binding: "DB" }),
      storage: r2({ binding: "MEDIA" }),
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
        }),
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
        }),
      ],
    }),
  ],
});

La libreria multimediale locale (tab “Libreria”) è sempre disponibile insieme a qualsiasi fornitore configurato.

Renderizzare i media dei fornitori

Usa il componente Image per renderizzare i media:

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

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    image={post.data.featured_image}
    width={800}
    height={450}
  />
)}

Il componente automaticamente:

• Rileva il fornitore dal valore memorizzato
• Renderizza un elemento <img> ottimizzato
• Applica ottimizzazioni specifiche del fornitore (es: trasformazioni Cloudflare Images)

Valori file e metadati attuali

Un campo file memorizza un riferimento e un’istantanea di metadati. I campi in cache come url, filename, mimeType e size sono opzionali perché i valori persistiti potrebbero ometterli:

interface FileValue {
  id: string;
  url?: string;        // URL in cache legacy
  src?: string;        // URL diretto da un fornitore esterno
  filename?: string;  // Nome file originale in cache
  mimeType?: string;  // Tipo MIME in cache
  size?: number;       // Dimensione in cache, quando disponibile
  provider?: string;   // Default "local"
  meta?: Record<string, unknown>;
}

getEmDashEntry() e getEmDashCollection() restituiscono questo valore memorizzato senza una query media aggiuntiva. Per metadati attuali, usa esplicitamente il metodo get() del fornitore configurato. Usa getEmbed() per l’URL di rendering specifico del fornitore:

---
const file = post.data.attachment;
const provider = file
  ? Astro.locals.emdash?.getMediaProvider(file.provider ?? "local")
  : undefined;
const current = file ? await provider?.get?.(file.id) : null;
const embed = file && provider ? await provider.getEmbed(file) : null;
---

I client HTTP autenticati possono effettuare la stessa ricerca esplicita tramite GET /_emdash/api/media/:id per media locali o GET /_emdash/api/media/providers/:providerId/:itemId per un altro fornitore.

Per un URL di file locale, usa il meta.storageKey memorizzato con l’helper URL pubblico. Questo rispetta un dominio pubblico R2 o S3 configurato senza interrogare la tabella dei media:

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

Le ricerche dei fornitori possono comportare lavoro di rete o database. Evita una ricerca per file nelle pagine di raccolta non autenticate; usa l’istantanea memorizzata e i componenti di rendering a meno che la richiesta non necessiti di metadati aggiornati.

Tipo MediaValue

I campi media memorizzano un oggetto MediaValue contenente informazioni sul fornitore:

interface MediaValue {
  provider?: string;    // ID del fornitore, default "local"
  id: string;           // ID specifica del fornitore
  src?: string;         // URL diretto (per media locali o valori stringa semplici)
  previewUrl?: string;  // URL di anteprima per visualizzazione admin (fornitori esterni)
  filename?: string;    // Nome file originale
  mimeType?: string;    // Tipo MIME
  width?: number;       // Larghezza immagine/video
  height?: number;      // Altezza immagine/video
  focalX?: number;      // Posizione focale orizzontale da 0 a 1
  focalY?: number;      // Posizione focale verticale da 0 a 1
  alt?: string;         // Testo alternativo
  meta?: Record<string, unknown>; // Metadati specifici del fornitore
}

Questo permette a EmDash di renderizzare i media correttamente indipendentemente da dove sono ospitati.

Prossimi passi

• Lavorare con i contenuti - Usare i media nei tuoi contenuti
• Creare un blog - Aggiungere immagini ai post del blog
• Interrogare i contenuti - Visualizzare i media nei template