Medienbibliothek

EmDash enthält eine Medienbibliothek zur Verwaltung von Bildern, Dokumenten und anderen Dateien. Diese Anleitung behandelt das Hochladen, Finden und Verwenden von Medien in Ihren Inhalten.

Zugriff auf die Medienbibliothek

Öffnen Sie die Medienbibliothek über die Admin-Seitenleiste, indem Sie auf Medien klicken. Die Hauptbibliothek zeigt Ordner und Dateien, die keinem Ordner zugewiesen sind. Öffnen Sie einen Ordner, um seine Dateien zu sehen.

Verwendet in

Öffnen Sie eine Datei in der EmDash-Medienbibliothek, um die Inhaltseinträge zu sehen, die darauf verweisen. Während EmDash vorhandene Inhalte scannt, enthält die Liste die bisher gefundenen Verweise und kann unvollständig sein.

Mediennutzungs-Tracking aktivieren

Wenn das Mediennutzungs-Tracking deaktiviert ist, kann ein Administrator es aktivieren:

1. Beenden Sie alle Inhaltsbearbeitungen. Wenn eine andere Anwendung direkt in die Inhaltsdatenbank schreibt, pausieren Sie sie und warten Sie, bis laufende Schreibvorgänge abgeschlossen sind.
2. Öffnen Sie Einstellungen → Mediennutzungs-Tracking, wählen Sie Tracking aktivieren und bestätigen Sie.
3. Wenn die Seite Vorhandene Inhalte indizieren anzeigt, können Bearbeitungen und andere Datenbankschreibvorgänge fortgesetzt werden.
4. Lassen Sie die Seite geöffnet, bis sie Bereit anzeigt. Wenn Sie die Seite verlassen, kehren Sie zurück, um vom gespeicherten Fortschritt fortzufahren.

Sobald das Mediennutzungs-Tracking aktiviert ist, kann es nicht mehr deaktiviert werden.

Dateien hochladen

Aus der Medienbibliothek

1. Öffnen Sie Medien in der Admin-Seitenleiste.

2. Wählen Sie Dateien hochladen, dann Dateien durchsuchen, um eine oder mehrere Dateien auszuwählen. Sie können Dateien auch per Drag & Drop in die Medienbibliothek ziehen.

3. Uploads starten automatisch. Der Dialog zeigt den Status jeder Datei und ermöglicht das Abbrechen oder Wiederholen einzelner Dateien.

Aus dem Inhaltseditor

1. Öffnen Sie ein Bild-, Datei- oder Galeriefeld im Inhaltseditor.

2. Suchen Sie, filtern Sie nach Typ, durchsuchen Sie einen Ordner oder wechseln Sie zwischen den verfügbaren Medienquellen.

3. Wählen Sie vorhandene Medien aus, oder wählen Sie Dateien hochladen und wählen Sie Dateien von Ihrem Computer. Sie können auch Dateien auf den Picker ziehen. Jeder Upload erscheint in den Ergebnissen mit seinem aktuellen Status.

4. Wenn ein Upload fehlschlägt, wählen Sie Wiederholen oder Entfernen für dieses Element. Ein erfolgreicher Upload wird zu einer ausgewählten Medienkarte.

5. Verwenden Sie für eine Galerie die Pfeilsteuerung unter Ausgewählte Medien, um die Reihenfolge festzulegen.

6. Wählen Sie die Picker-Aktion, wie Auswählen, Bild einfügen oder 3 Bilder hinzufügen.

Unterstützte Dateitypen

EmDash akzeptiert standardmäßig diese Dateitypen:

Bild- und Dateifelder können andere MIME-Typen zulassen, einschließlich image/svg+xml für SVG-Dateien.

Speicher-Backends

EmDash unterstützt mehrere Speicher-Backends. Konfigurieren Sie den Speicher in Ihrer Astro-Konfiguration:

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

Wie Uploads funktionieren

Der Admin verwendet den Upload-Ziel-Flow:

1. Der Client fordert ein Upload-Ziel an, und EmDash erstellt ein ausstehendes Medienelement.

2. Der Client lädt die Datei zum zurückgegebenen Ziel hoch.

3. Der Client bestätigt den Upload.

4. EmDash validiert die gespeicherte Datei und markiert das Medienelement als bereit.

S3-kompatibler Speicher gibt eine signierte URL zurück, sodass die Datei die Anwendungsruntime umgehen kann. Lokaler Speicher und nativer R2 geben stattdessen einen Same-Origin-Streaming-Endpunkt zurück.

Medien finden

Suche

Verwenden Sie das Suchfeld, um Dateien nach Namen zu finden. Die Suche findet auch teilweise Dateinamen.

Nach Typ filtern

Verwenden Sie den Typfilter, um Bilder, Dokumente, Video- oder Audiodateien anzuzeigen.

Medien in Ordnern organisieren

Editoren können Neuen Ordner hinzufügen aus der Hauptbibliothek wählen. Öffnen Sie einen Ordner, indem Sie seinen Namen auswählen. Ohne Suchbegriff zeigen Ordnerseiten nur die dem Ordner zugewiesenen Medien. Dateinamenssuchen durchsuchen die gesamte Bibliothek, einschließlich anderer Ordner und der Hauptbibliothek.

Um eine lokale Datei in einen sichtbaren Ordner zu verschieben, ziehen Sie ihre Rasterkarte oder Listenzeile auf den Ordner. Sie können auch Mediendetails öffnen, einen Standort wählen und Speichern auswählen. Verwenden Sie Standort, um eine Datei in die Hauptbibliothek zurückzubringen oder sie ohne Ziehen zu verschieben.

Autoren können lokale Dateien verschieben, die sie hochgeladen haben. Editoren können jede lokale Datei verschieben. Dateien von externen Anbietern können nicht Ordnern zugewiesen werden.

Uploads landen in der Hauptbibliothek. Verschieben Sie sie nach dem Upload mit einer der oben genannten Methoden in einen Ordner.

Das Löschen eines Ordners gibt seine Medien an die Hauptbibliothek zurück. Die Mediendateien, URLs und Inhaltsverweise bleiben unverändert.

Medien in Inhalten verwenden

Im Rich-Text-Editor

1. Setzen Sie den Cursor an die Stelle, an der Sie das Bild einfügen möchten

2. Klicken Sie auf die Bildschaltfläche in der Werkzeugleiste

3. Finden Sie ein Bild im Picker oder laden Sie ein neues hoch.

4. Wählen Sie Bild einfügen.

5. Fügen Sie Alt-Text in den Bildeinstellungen hinzu.

Als Featured Image

1. Öffnen Sie einen Inhaltseintrag im Editor

2. Finden Sie das Feld Featured Image in der Seitenleiste

3. Klicken Sie auf Bild auswählen

4. Wählen Sie ein Bild aus dem Picker oder laden Sie eines hoch.

5. Wählen Sie Auswählen, dann Speichern.

In benutzerdefinierten Feldern

Für Felder, die als Bild- oder Dateitypen konfiguriert sind, wählen Sie die Feldaktion, um denselben Medien-Picker zu öffnen. Die MIME-Typ-Regeln des Feldes begrenzen die verfügbaren Quellen und Dateien.

Ein ausgewähltes Bild-Asset bearbeiten

Lokale Bildfelder, Rich-Text-Bilder und Galeriebilder bieten drei Aktionen:

• Ersetzen ändert das im aktuellen Feld, Block oder in der Galerieposition verwendete Bild.
• Asset bearbeiten öffnet die Mediendetails für das ausgewählte Medienbibliothek-Element. Sie können Alt-Text, Bildunterschrift, Fokuspunkt oder Zuschnitt aktualisieren, während Sie im Inhaltseditor bleiben.
• Entfernen löscht die aktuelle Inhaltsreferenz. Das Medienbibliothek-Element bleibt verfügbar.

Zugeschnittene Kopie erstellen wählt die neue Kopie für die aktuelle Verwendung aus. Rich-Text- und Galeriebilder behalten ihren nutzungsspezifischen Alt-Text, die Bildunterschrift, das Layout und die Position. Original ersetzen behält dieselbe Medienreferenz bei und ändert das Bild überall dort, wo dieses Asset verwendet wird.

Bilder von externen Anbietern und Dateifelder bieten Ersetzen und Entfernen, aber nicht Asset bearbeiten.

Ein Bild ersetzen

Verwenden Sie Bild ersetzen, um die Datei hinter einem vorhandenen lokalen Medienelement zu aktualisieren. Autoren können von ihnen hochgeladene Bilder ersetzen, und Editoren können jedes lokale Bild ersetzen. Die Aktion ist für JPEG-, PNG- und WebP-Bilder verfügbar, die auf lokaler Festplatte, Cloudflare R2 oder S3-kompatiblem Speicher gespeichert sind.

1. Öffnen Sie Medien und wählen Sie ein Bild aus der lokalen Bibliothek.
2. Bleiben Sie bei Details und wählen Sie Bild ersetzen.
3. Wählen Sie ein nicht-leeres Bild im selben Format wie die vorhandene Datei.
4. Überprüfen Sie die Warnung und wählen Sie Bild ersetzen zur Bestätigung.

Der Ersatz kann andere Abmessungen oder ein anderes Seitenverhältnis als das vorhandene Bild verwenden. EmDash behält die Medien-ID, den Dateinamen, die URL, den Alt-Text, die Bildunterschrift und den Standort bei, sodass jede vorhandene Referenz den Ersatz verwendet. Das Ersetzen der Datei löscht ihren Fokuspunkt.

Bild ersetzen lädt eine andere Datei von Ihrem Computer hoch. Um das aktuelle Bild zuzuschneiden, wählen Sie Original ersetzen aus dem Zuschnitt-Editor.

Fokuspunkt setzen

Ein Fokuspunkt hält den wichtigen Teil eines lokalen Bildes sichtbar, wenn ein Karten-, Galerie- oder anderes Layout es auf eine feste Form zuschneidet.

1. Öffnen Sie Medien und wählen Sie ein Bild aus der lokalen Bibliothek, oder wählen Sie Asset bearbeiten für ein lokales Bild im Inhaltseditor.
2. Wählen Sie Bild bearbeiten, dann Fokuspunkt.
3. Klicken oder ziehen Sie die Markierung auf den wichtigen Teil des Bildes. Sie können auch die Pfeiltasten verwenden.
4. Überprüfen Sie die quadratischen, Querformat- und Hochformat-Vorschauen und wählen Sie dann Speichern.

Wählen Sie Zurücksetzen, um einen benutzerdefinierten Fokuspunkt zu entfernen. Der gespeicherte Punkt wird kopiert, wenn Sie das Bild für ein Inhaltsfeld oder eine Galerie auswählen. Andere Inhalte, die das Bild bereits verwenden, behalten ihren gespeicherten Punkt, bis Sie das Bild erneut auswählen. Wenn Sie ein Asset aus einem Inhaltsfeld oder einer Galerie bearbeiten, wird die aktuelle Verwendung mit dem gespeicherten Fokuspunkt aktualisiert.

Ein Bild zuschneiden

Zuschneiden ist für JPEG-, PNG- und WebP-Bilder verfügbar, die zu EmDash hochgeladen wurden. Es funktioniert mit lokalem Speicher, Cloudflare R2 und S3-kompatiblem Speicher. Bilder von externen Medienanbietern können in der Medienbibliothek nicht zugeschnitten werden.

1. Öffnen Sie Medien und wählen Sie ein Bild aus der lokalen Bibliothek.
2. Wählen Sie Bild bearbeiten, dann Zuschneiden.
3. Wählen Sie Original, Freiform oder ein gängiges Seitenverhältnis. Feste Verhältnisse bleiben beim Ändern der Größe gesperrt. Freiform ermöglicht es Ihnen, Breite und Höhe unabhängig zu ändern.
4. Bewegen Sie den Zuschneiderahmen über das Bild. Für ein festes Verhältnis ziehen Sie eine Ecke, um die Größe zu ändern. Freiform bietet auch vier Kantengriffe. Das Drittelregel-Raster bleibt sichtbar. Sie können den Rahmen oder einen Griff fokussieren und die Pfeiltasten verwenden. Halten Sie Shift für größere Schritte.
5. Wählen Sie eine der Zuschneideaktionen:
   • Zugeschnittene Kopie erstellen erstellt ein separates Medienelement und lässt das Original unverändert. Wählen Sie die zugeschnittene Kopie in jedem Inhaltseintrag, in dem Sie sie verwenden möchten.
   • Original ersetzen ersetzt das Bild überall, wo das Medienelement verwendet wird. Vorhandene Inhaltseinträge behalten dieselbe Medienreferenz und werden nicht umgeschrieben oder erneut veröffentlicht.

Das Zuschneiden einer WebP-Datei erzeugt ein statisches WebP-Bild. Wenn die Quelle animiert ist, behält das zugeschnittene Ergebnis die Animation nicht bei.

Medien in Templates anzeigen

Greifen Sie über Ihre Inhaltsdaten auf Medien-URLs zu:

---
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 ?? ""}
  />
)}

Responsive Bilder

Verwenden Sie für EmDash-Medienfelder die Image-Komponente aus 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 ist für das primäre Above-the-Fold-Bild. Es setzt loading="eager" und fetchpriority="high": loading steuert, ob das Laden verzögert wird, und fetchpriority gibt dem Browser einen Prioritätshinweis für die Anfrage.

Wenn der Feldwert ein Dark-Gegenstück enthält, rendert Image beide und zeigt dasjenige an, das zum Farbschema des Besuchers passt. Dunkelmodus behandelt das Aktivieren des Slots für ein Feld und die <html>-Klassenkonvention, auf die die Komponente angewiesen ist.

EmDash installiert einen Bild-Endpunkt, der die verkleinerten Varianten auf Anfrage erzeugt. Auf Cloudflare Workers verwendet dieser Endpunkt das IMAGES-Binding. Bildtransformation behandelt, woher das Binding kommt und was passiert, wenn es fehlt.

Medien löschen

1. Wählen Sie die Datei(en), die Sie löschen möchten

2. Klicken Sie auf Löschen

3. Bestätigen Sie das Löschen

Medien-API

Verwenden Sie die REST-API zum Hochladen, Auflisten, Aktualisieren, Löschen und Organisieren lokaler Medien. Die Medien-Endpunkt-Referenz dokumentiert den direkten Multipart-Upload und Upload-Ziel-Flows, Anfrageparameter, Antwortformate, Berechtigungen und Ordneroperationen.

Medienanbieter

Zusätzlich zum lokalen Speicher unterstützt EmDash externe Medienanbieter für spezialisiertes Bild- und Video-Hosting. Medienanbieter erscheinen als Tabs im Medien-Picker, sodass Editoren aus mehreren Quellen wählen können.

Verfügbare Anbieter

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

export default defineConfig({
  integrations: [
    emdash({
      // ... Datenbank-, Speicher-Konfiguration
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          // Optional: benutzerdefinierte Bereitstellungsdomain
          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({
      // ... Datenbank-, Speicher-Konfiguration
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          // Optional: Player-Einstellungen
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

Mehrere Anbieter verwenden

Sie können mehrere Anbieter konfigurieren. Jeder erscheint als Tab im Medien-Picker:

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

Die lokale Medienbibliothek (Tab “Bibliothek”) ist neben allen konfigurierten Anbietern immer verfügbar.

Anbieter-Medien rendern

Verwenden Sie die Image-Komponente zum Rendern von Medien:

---
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}
  />
)}

Die Komponente erkennt automatisch:

• Den Anbieter aus dem gespeicherten Wert
• Rendert ein optimiertes <img>-Element
• Wendet anbieterspezifische Optimierungen an (z.B. Cloudflare Images Transformationen)

Dateiwerte und aktuelle Metadaten

Ein Dateifeld speichert eine Referenz und einen Metadaten-Snapshot. Gecachte Felder wie url, filename, mimeType und size sind optional, da persistierte Werte sie möglicherweise auslassen:

interface FileValue {
  id: string;
  url?: string;        // Legacy-gecachte URL
  src?: string;        // Direkte URL von einem externen Anbieter
  filename?: string;  // Gecachter Originaldateiname
  mimeType?: string;  // Gecachter MIME-Typ
  size?: number;       // Gecachte Größe, wenn verfügbar
  provider?: string;   // Standardmäßig "local"
  meta?: Record<string, unknown>;
}

getEmDashEntry() und getEmDashCollection() geben diesen gespeicherten Wert ohne zusätzliche Medienabfrage zurück. Für aktuelle Metadaten verwenden Sie explizit die get()-Methode des konfigurierten Anbieters. Verwenden Sie getEmbed() für die anbieterspezifische Render-URL:

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

Authentifizierte HTTP-Clients können dieselbe explizite Abfrage über GET /_emdash/api/media/:id für lokale Medien oder GET /_emdash/api/media/providers/:providerId/:itemId für einen anderen Anbieter durchführen.

Für eine lokale Datei-URL verwenden Sie den gespeicherten meta.storageKey mit dem öffentlichen URL-Helfer. Dies respektiert eine konfigurierte R2- oder S3-öffentliche Domain, ohne die Medientabelle abzufragen:

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

Anbieter-Abfragen können Netzwerk- oder Datenbankarbeit erfordern. Vermeiden Sie eine Abfrage pro Datei auf ausgeloggten Sammlungsseiten; verwenden Sie den gespeicherten Snapshot und Rendering-Komponenten, es sei denn, die Anfrage benötigt frische Metadaten.

MediaValue-Typ

Medienfelder speichern ein MediaValue-Objekt mit Anbieterinformationen:

interface MediaValue {
  provider?: string;    // Anbieter-ID, standardmäßig "local"
  id: string;           // Anbieterspezifische ID
  src?: string;         // Direkte URL (für lokale Medien oder einfache String-Werte)
  previewUrl?: string;  // Vorschau-URL für Admin-Anzeige (externe Anbieter)
  filename?: string;    // Originaler Dateiname
  mimeType?: string;    // MIME-Typ
  width?: number;       // Bild-/Video-Breite
  height?: number;      // Bild-/Video-Höhe
  focalX?: number;      // Horizontale Fokusposition von 0 bis 1
  focalY?: number;      // Vertikale Fokusposition von 0 bis 1
  alt?: string;         // Alt-Text
  meta?: Record<string, unknown>; // Anbieterspezifische Metadaten
}

Dies ermöglicht EmDash, Medien korrekt zu rendern, unabhängig davon, wo sie gehostet werden.

Nächste Schritte

• Mit Inhalten arbeiten - Medien in Ihren Inhalten verwenden
• Einen Blog erstellen - Bilder zu Blogbeiträgen hinzufügen
• Inhalte abfragen - Medien in Templates anzeigen