Libreria media

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

Accedere alla libreria media

Apri la libreria media dalla barra laterale admin cliccando su Media. La libreria mostra tutti i file caricati con anteprime, nomi dei file e date di caricamento.

Caricare file

Dalla libreria media

1. Clicca su Media nella barra laterale admin

2. Clicca su Upload o trascina i file nell’area di caricamento

3. Seleziona uno o più file dal tuo computer

4. Attendi il completamento dei caricamenti

Dall’editor di contenuto

1. Nell’editor di testo ricco, clicca sul pulsante immagine

2. Clicca su Upload nel selettore media

3. Seleziona un file dal tuo computer

4. Aggiungi testo alternativo e clicca su Inserisci

Tipi di file supportati

EmDash supporta i tipi di file web comuni:

Backend di storage

EmDash supporta più backend di storage. Configura lo storage 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

EmDash utilizza URL firmate per caricamenti sicuri:

1. Il client richiede un URL di caricamento dall’API

2. Il server genera un URL firmato con scadenza

3. Il client carica direttamente nello storage usando l’URL firmato

4. Il server registra i metadati del file nel database

Questo approccio mantiene i file grandi fuori dal tuo server applicativo e abilita i caricamenti diretti allo storage cloud.

Organizzare i media

Cartelle

Crea cartelle per organizzare i tuoi media:

1. Clicca su New Folder nella libreria media

2. Inserisci un nome per la cartella

3. Clicca su Crea

4. Trascina i file nelle cartelle per organizzarli

Ricerca

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

Filtri

Filtra i media per:

• Tipo - Immagini, Documenti, Video, Audio
• Data - Intervallo di date di caricamento
• Cartella - Cartella specifica

Usare i media nei contenuti

Nell’editor di testo ricco

1. Posiziona il cursore dove vuoi l’immagine

2. Clicca sul pulsante immagine nella barra degli strumenti

3. Seleziona un’immagine dalla libreria media o caricane una nuova

4. Inserisci il testo alternativo

5. Clicca su Inserisci

Come immagine in evidenza

1. Apri una voce di contenuto nell’editor

2. Trova il campo Featured Image nella barra laterale

3. Clicca su Seleziona immagine

4. Scegli dalla libreria media o carica

5. Clicca su Salva

Nei campi personalizzati

Per i campi configurati come tipi immagine o file, clicca sul campo per aprire il selettore media.

Visualizzare i media nei template

Accedi agli URL dei media dai dati del tuo 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 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.

Eliminare media

1. Seleziona il/i file che vuoi eliminare

2. Clicca su Elimina

3. Conferma l’eliminazione

API dei media

Accedi ai media programmaticamente usando l’API di amministrazione.

Caricare un file

Carica media come dati di form multipart:

POST /_emdash/api/media
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_TOKEN

file=<binary file data>

Un caricamento riuscito restituisce l’elemento media memorizzato:

{
	"success": true,
	"data": {
		"item": {
			"id": "01ABC123",
			"filename": "hero-image.jpg",
			"mime_type": "image/jpeg",
			"storage_key": "media/abc123/hero-image.jpg",
			"width": 1200,
			"height": 800
		}
	}
}

Elencare i media

La seguente richiesta elenca i media sotto un prefisso:

GET /_emdash/api/media?prefix=images/&limit=20
Authorization: Bearer YOUR_API_TOKEN

Eliminare media

La seguente richiesta elimina un file memorizzato:

DELETE /_emdash/api/media/images/hero.jpg
Authorization: Bearer YOUR_API_TOKEN

Provider di media

Oltre allo storage locale, EmDash supporta provider di media esterni per hosting specializzato di immagini e video. I provider di media appaiono come schede nel selettore media, permettendo agli editor di scegliere da più fonti.

Provider disponibili

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

export default defineConfig({
  integrations: [
    emdash({
      // ... configurazione database, storage
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          // Opzionale: dominio di consegna 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, storage
      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ù provider

Puoi configurare più provider. Ognuno appare come una scheda nel selettore media:

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 media locale (scheda “Library”) è sempre disponibile insieme a qualsiasi provider configurato.

Renderizzare i media del provider

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 provider dal valore memorizzato
• Renderizza un elemento <img> ottimizzato
• Applica ottimizzazioni specifiche del provider (es. trasformazioni Cloudflare Images)

Tipo MediaValue

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

interface MediaValue {
  provider?: string;    // ID del provider, predefinito "local"
  id: string;           // ID specifico del provider
  src?: string;         // URL diretto (per media locali o valori stringa semplice)
  previewUrl?: string;  // URL di anteprima per visualizzazione admin (provider esterni)
  filename?: string;    // Nome file originale
  mimeType?: string;    // Tipo MIME
  width?: number;       // Larghezza immagine/video
  height?: number;      // Altezza immagine/video
  alt?: string;         // Testo alternativo
  meta?: Record<string, unknown>; // Metadati specifici del provider
}

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