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 illustra caricamento, organizzazione e uso dei media nei contenuti.

Accedere alla libreria media

Apri la libreria dalla barra laterale dell’admin con Media. Vedrai tutti i file caricati con anteprima, nomi e date di caricamento.

Libreria media EmDash con griglia di immagini e pulsante di caricamento

Caricare file

Dalla libreria media

  1. Fai clic su Media nella barra laterale dell’admin

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

  3. Seleziona uno o più file sul computer

  4. Attendi il completamento dei caricamenti

Dall’editor dei contenuti

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

  2. Nel selettore media, fai clic su Upload

  3. Seleziona un file sul computer

  4. Aggiungi il testo alternativo e fai clic su Insert

Tipi di file supportati

EmDash supporta tipi di file comuni per il web:

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. Configurali in 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 sono salvati in ./uploads. Adatto allo sviluppo e ai deploy su server singolo.

Cloudflare R2

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

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 (API S3), MinIO e altri servizi compatibili S3.

Come funzionano i caricamenti

EmDash usa URL firmate per caricamenti sicuri:

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

  2. Il server genera un URL firmato con scadenza

  3. Il client carica direttamente nello storage tramite quell’URL

  4. Il server registra i metadati del file nel database

I file grandi non passano dal server applicativo; il caricamento diretto nel cloud è possibile.

Organizzare i media

Cartelle

Crea cartelle per organizzare:

  1. Fai clic su New Folder nella libreria media

  2. Inserisci il nome della cartella

  3. Fai clic su Create

  4. Trascina i file nelle cartelle

Ricerca

Usa la casella di ricerca per trovare file per nome. La ricerca corrisponde a parti del nome file.

Filtri

Filtra per:

  • Type — Immagini, documenti, video, audio
  • Date — Intervallo di date di caricamento
  • Folder — Cartella specifica

Usare i media nei contenuti

Nell’editor di testo ricco

  1. Posiziona il cursore dove vuoi l’immagine

  2. Fai clic sul pulsante immagine nella barra

  3. Scegli un’immagine dalla libreria o caricane una nuova

  4. Inserisci il testo alternativo

  5. Fai clic su Insert

Come immagine in evidenza

  1. Apri una voce nell’editor

  2. Individua il campo Featured Image nella barra laterale

  3. Fai clic su Select Image

  4. Scegli dalla libreria o carica

  5. Fai clic su Save

In campi personalizzati

Per campi configurati come immagine o file, fai clic sul campo per aprire il selettore media.

Mostrare i media nei template

Accedi agli URL dai dati del 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 immagini responsive, usa il componente Image di Astro con URL esterni:

Immagini responsive

Per 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 i file da eliminare

  2. Fai clic su Delete

  3. Conferma l’eliminazione

API media

Accedi ai media programmaticamente tramite l’API di amministrazione.

Caricare un file

Carica come multipart/form-data:

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

file=<binary file data>

Risposta:

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

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

Eliminare i media

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

Provider media

Oltre allo storage locale, EmDash supporta provider esterni per hosting specializzato di immagini e video. Compaiono come schede nel selettore media.

Provider disponibili

Cloudflare Images

Cloudflare Images offre hosting immagini con ottimizzazione, ridimensionamento e conversione 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 dall’admin
  • Ottimizzazione e conversione formato automatiche
  • Trasformazioni basate su URL (dimensione, ritaglio, formato)
  • Varianti flessibili per immagini responsive

Cloudflare Stream

Cloudflare Stream offre 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 delle miniature
  • Caricamento diretto per file grandi

Più provider

Puoi configurarne più di uno; ognuno compare come scheda nel selettore:

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 locale (scheda «Library») è sempre disponibile insieme ai provider configurati.

Renderizzare i media dei provider

Usa il componente Image per il rendering:

---
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:

  • rileva il provider dal valore memorizzato
  • renderizza un <img> ottimizzato
  • applica ottimizzazioni specifiche del provider (es. Cloudflare Images)

Tipo MediaValue

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

interface MediaValue {
  provider?: string;    // Provider ID, defaults to "local"
  id: string;           // Provider-specific ID
  src?: string;         // Direct URL (for local media or legacy data)
  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
}

EmDash può così renderizzare correttamente i media indipendentemente dall’hosting.

Passi successivi