E EmDash CMS Everything Guides, use cases, plugins, templates
Italiano

Libreria Media

In questa pagina

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 dell’amministratore cliccando su Media. La libreria mostra tutti i file caricati con anteprime, nomi di file e date di caricamento.

Libreria media EmDash che mostra griglia di immagini con pulsante di caricamento

Caricare File

Dalla Libreria Media

  1. Clicca su Media nella barra laterale dell’amministratore

  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 Contenuti

  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 il testo alternativo e clicca su Insert

Tipi di File Supportati

EmDash supporta i tipi di file web comuni:

CategoriaEstensioni
Immagini.jpg, .jpeg, .png, .gif, .webp, .avif, .svg
Documenti.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx
Video.mp4, .webm, .mov
Audio.mp3, .wav, .ogg

Backend di Archiviazione

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

Local Storage

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",
      }),
    }),
  ],
});

I file vengono archiviati nella directory ./uploads. Adatto per lo sviluppo e le distribuzioni su server singolo.

Cloudflare R2

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",
      }),
    }),
  ],
});

Richiede un bucket R2 configurato in wrangler.jsonc:

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

S3-Compatible

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",
      }),
    }),
  ],
});

Funziona con Cloudflare R2 (tramite API S3), MinIO e altri servizi compatibili con S3.

Come Funzionano i Caricamenti

EmDash utilizza URL firmati 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 nell’archiviazione utilizzando l’URL firmato

  4. Il server registra i metadati del file nel database

Questo approccio mantiene i file di grandi dimensioni fuori dal tuo server applicativo e abilita i caricamenti diretti nell’archiviazione cloud.

Organizzare i Media

Cartelle

Crea cartelle per organizzare i tuoi media:

  1. Clicca su New Folder nella libreria media

  2. Inserisci un nome di cartella

  3. Clicca su Create

  4. Trascina i file nelle cartelle per organizzarli

Ricerca

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

Filtri

Filtra i media per:

  • Type - Immagini, Documenti, Video, Audio
  • Date - Intervallo di date di caricamento
  • Folder - Cartella specifica

Utilizzare 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 Insert

Come Immagine in Evidenza

  1. Apri una voce di contenuto nell’editor

  2. Trova il campo Featured Image nella barra laterale

  3. Clicca su Select Image

  4. Scegli dalla libreria media o carica

  5. Clicca su Save

Nei Campi Personalizzati

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

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 le immagini responsive, usa il componente Image di Astro con URL esterni:

---
import { Image } from "astro:assets";
import { getEmDashEntry } from "emdash";

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

{post?.data.featured_image && (
  <Image
    src={post.data.featured_image}
    alt={post.data.featured_image_alt ?? ""}
    width={800}
    height={450}
  />
)}

Eliminare i Media

  1. Seleziona il/i file che desideri eliminare

  2. Clicca su Delete

  3. Conferma l’eliminazione

API Media

Accedi ai media in modo programmatico utilizzando l’API di amministrazione.

Caricare un File

Carica i media come dati del modulo 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 archiviato:

{
	"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 i Media

La seguente richiesta elimina un file archiviato:

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

Provider di Media

Oltre all’archiviazione locale, EmDash supporta provider di media esterni per l’hosting specializzato di immagini e video. I provider di media appaiono come schede nel selettore media, permettendo agli editori di scegliere da più fonti.

Provider Disponibili

Cloudflare Images

Cloudflare Images fornisce hosting di immagini con ottimizzazione automatica, ridimensionamento e conversione del formato.

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

export default defineConfig({
  integrations: [
    emdash({
      // ... database, storage config
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          // Optional: custom delivery domain
          deliveryDomain: "images.example.com",
        }),
      ],
    }),
  ],
});

Funzionalità:

  • Sfoglia e carica immagini direttamente dall’admin
  • Ottimizzazione automatica delle immagini e conversione del formato
  • Trasformazioni basate su URL (ridimensiona, ritaglia, formato)
  • Varianti flessibili per immagini responsive

Cloudflare Stream

Cloudflare Stream fornisce hosting video con streaming adattivo HLS/DASH.

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

export default defineConfig({
  integrations: [
    emdash({
      // ... database, storage config
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          // Optional: player settings
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

Funzionalità:

  • Sfoglia, cerca e carica video dall’admin
  • Streaming adattivo HLS e DASH
  • Generazione automatica di miniature
  • Caricamento diretto per file di grandi dimensioni

Utilizzare 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 tutti i provider configurati.

Rendering dei Media dei Provider

Usa il componente Image per il rendering dei 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 archiviato
  • Renderizza un elemento <img> ottimizzato
  • Applica le ottimizzazioni specifiche del provider (es. trasformazioni Cloudflare Images)

Tipo MediaValue

I campi media archiviano un oggetto MediaValue contenente le informazioni del provider:

interface MediaValue {
  provider?: string;    // Provider ID, defaults to "local"
  id: string;           // Provider-specific ID
  src?: string;         // Direct URL (for local media or plain-string values)
  previewUrl?: string;  // Preview URL for admin display (external providers)
  filename?: string;    // Original filename
  mimeType?: string;    // MIME type
  width?: number;       // Image/video width
  height?: number;      // Image/video height
  alt?: string;         // Alt text
  meta?: Record<string, unknown>; // Provider-specific metadata
}

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

Prossimi Passi