Medienbibliothek

Die Medienbibliothek speichert wiederverwendbare Bilder, Dokumente, Videos und Audiodateien. Redakteure laden eine Datei einmal hoch, wählen sie in Inhaltsfeldern und in Portable Text aus und sehen, welche Inhaltseinträge ein lokales Medienelement referenzieren.

Die Medienbibliothek öffnen

Wählen Sie in der Seitenleiste des Admin-Bereichs Media. Die Main library enthält Ordner sowie Dateien, die noch in keinem Ordner liegen. Wählen Sie einen Ordner, um seine Dateien zu durchsuchen, und wechseln Sie bei Bedarf zwischen Raster- und Listenansicht.

Wenn Ihre Site externe Medienanbieter hat, erscheint jeder Anbieter als weitere Quelle. Die Fähigkeiten der Anbieter unterscheiden sich: Eine Quelle unterstützt möglicherweise Durchsuchen und Auswählen, aber keine Ordner, keine lokale Bildbearbeitung und kein Löschen.

Dateien hochladen

Aus der Bibliothek hochladen

Uploads beginnen sofort, wenn Sie Dateien hinzufügen. Neue lokale Dateien landen in der Main library, auch wenn vor dem Upload ein anderer Ordner geöffnet war.

Beim Bearbeiten von Inhalten hochladen

Bild-, Datei-, Galerie- und Portable-Text-Bildfelder verwenden die Medienauswahl. Öffnen Sie das Feld, wählen Sie Upload files und wählen Sie Dateien aus oder legen Sie sie ab. Abgeschlossene Uploads werden Teil der aktuellen Auswahl; fehlgeschlagene Uploads bleiben sichtbar, damit Sie sie erneut versuchen oder entfernen können.

Prüfen Sie bei einer Galerie Selected media und legen Sie die Reihenfolge mit den Verschiebe-Steuerelementen fest, bevor Sie Add images wählen. Wählen Sie bei einem einzelnen Bild oder einer einzelnen Datei Select oder Insert image, sobald der Upload abgeschlossen ist.

Akzeptierte Dateien und Größenlimits

Die lokale Medienbibliothek akzeptiert standardmäßig diese Dateigruppen:

• PNG-, JPEG-, GIF-, WebP- und AVIF-Bilder
• gängige Videoformate wie MP4, WebM und QuickTime-Video
• gängige Audioformate wie MP3, WAV und Ogg-Audio
• PDF-Dokumente

SVG ist in der Standardliste für Uploads nicht enthalten, weil SVG-Dateien aktive Inhalte enthalten können. Ein Bild- oder Dateifeld kann eine eigene Liste zulässiger Dateitypen definieren, wenn Ihr Inhaltsmodell eine engere Auswahl oder andere Formate braucht. EmDash erkennt jede Datei an ihrem Medientyp, einem Label wie image/png oder application/pdf, und prüft die Liste des Feldes beim Speichern von Inhalten erneut. Eine Änderung am Dateidialog des Browsers umgeht diese serverseitige Prüfung nicht.

Das Standardmaximum beträgt 50 MB pro Datei. Site-Entwickler können es mit maxUploadSize ändern. Anbieter können zusätzliche Format- oder Größenbeschränkungen auferlegen und melden diesen Fehler in der Upload-Zeile.

Dateien finden und organisieren

Die Suche findet Teile von Dateinamen. Mit dem Typfilter schränken Sie die Ergebnisse auf Bilder, Dokumente, Videos oder Audiodateien ein. Die Suche nach Dateinamen umfasst die gesamte lokale Bibliothek, auch wenn ein Ordner geöffnet ist; beim Durchsuchen eines Ordners ohne Suche werden nur die diesem Ordner zugewiesenen Dateien angezeigt.

Redakteure können in der Main library Add new folder wählen. Um eine lokale Datei zu verschieben, ziehen Sie ihre Karte oder Zeile auf einen sichtbaren Ordner, oder öffnen Sie die Datei, ändern Sie Location und wählen Sie Save. Verwenden Sie Main library als Speicherort, um eine Datei aus ihrem aktuellen Ordner zu entfernen.

Autoren können lokale Dateien verschieben, die sie selbst hochgeladen haben. Redakteure können jede lokale Datei verschieben. Elemente externer Anbieter lassen sich keinen Ordnern der Medienbibliothek zuweisen.

Wenn Sie einen Ordner löschen, wandern seine Dateien zurück in die Main library. Dadurch werden weder Dateien gelöscht noch ihre URLs geändert, noch Inhaltsreferenzen entfernt.

Medien für Inhalte auswählen

Portable-Text-Bilder

Setzen Sie den Cursor in ein Portable-Text-Feld, öffnen Sie das Blockmenü und wählen Sie Image. Wählen Sie ein Bild aus oder laden Sie eines hoch und wählen Sie dann Insert image. Wählen Sie anschließend den Bildblock, um Alternativtext, Bildunterschrift, Anzeigegröße und Ausrichtung hinzuzufügen.

Bild- und Dateifelder

Wählen Sie die Feldaktion, zum Beispiel Select image oder Select file, wählen Sie ein Element aus und bestätigen Sie die Auswahl. Die MIME-Typ-Regeln des Feldes begrenzen, welche Bibliothekselemente und Medienquellen angezeigt werden.

Das Feld featured_image der Blog-Vorlage speichert den gewählten Medienwert zusammen mit dem Beitrag. Beim Speichern des Eintrags wird diese Referenz im Entwurf gespeichert; mit der Veröffentlichung wird sie für öffentliche Inhaltsabfragen verfügbar.

Galeriefelder

Wählen Sie ein oder mehrere Bilder aus, ordnen Sie sie unter Selected media an und bestätigen Sie. Die Galerie behält ihre eigene Reihenfolge sowie den Alternativtext und die Bildunterschrift jedes Bildes bei, auch wenn mehrere Stellen dasselbe Element der Medienbibliothek referenzieren.

Ein in Inhalten verwendetes Bild bearbeiten

Ein ausgewähltes lokales Bild bietet Aktionen mit unterschiedlicher Reichweite:

• Replace wählt für dieses Feld, diesen Block oder diese Galerieposition ein anderes Element der Medienbibliothek aus. Andere Einträge, die das ursprüngliche Element verwenden, bleiben unverändert.
• Edit asset öffnet das zugrunde liegende Element der Medienbibliothek. Änderungen an Metadaten und destruktive Bildänderungen können auch andere Stellen betreffen, an denen dieses Element verwendet wird.
• Remove löscht diese Inhaltsreferenz. Das Element der Medienbibliothek bleibt verfügbar.

Wenn Edit asset eine zugeschnittene Kopie erstellt, wählt die Auswahl die neue Kopie für die aktuelle Verwendung aus. Bilder in Portable Text und in Galerien behalten den Alternativtext, die Bildunterschrift, das Layout und die Position dieser Verwendung bei. Wenn Edit asset das Original ersetzt, bleibt die Medien-ID gleich, sodass jede Verwendung dieses Elements das geänderte Bild erhält.

Bild- und Dateifelder externer Anbieter bieten Replace und Remove, öffnen aber nicht den lokalen Asset-Editor.

Ein lokales Bild ersetzen

Replace image lädt neue Bytes hinter einem vorhandenen Element der Medienbibliothek hoch. Verwenden Sie es, wenn jede Stelle, die dieses Element referenziert, die neue Version des Bildes zeigen soll.

Die Aktion ist für JPEG-, PNG- und WebP-Elemente im Status „bereit“ verfügbar. Autoren können Bilder ersetzen, die sie selbst hochgeladen haben; Redakteure können jedes lokale Bild ersetzen.

EmDash behält die Medien-ID, den Dateinamen, die URL, den Alternativtext, die Bildunterschrift und den Ordner bei. Vorhandene Inhaltsreferenzen funktionieren daher weiter und zeigen das ersetzte Bild. Beim Ersetzen wird ein gespeicherter Fokuspunkt gelöscht, weil seine Koordinaten möglicherweise nicht zum neuen Bild passen.

Wenn nur ein Feld oder ein Bildblock geändert werden muss, verwenden Sie stattdessen Replace im Inhaltseditor.

Einen Fokuspunkt festlegen

Ein Fokuspunkt markiert den Teil eines Bildes, der sichtbar bleiben soll, wenn ein Layout das Bild auf ein Quadrat, ein Querformat, ein Hochformat oder eine andere feste Form zuschneidet.

Wählen Sie Reset, um den benutzerdefinierten Punkt zu entfernen. Wenn Sie ein Bild für ein Feld oder eine Galerie auswählen, kopiert EmDash den aktuellen Fokuspunkt des Assets in diesen Inhaltswert. Inhalte, die das Bild bereits verwenden, behalten ihren gespeicherten Punkt, bis Sie das Bild erneut auswählen. Wenn Sie Edit asset aus einem Inhaltsfeld öffnen, aktualisiert Ihr gespeicherter Punkt diese aktuelle Verwendung.

Ein lokales Bild zuschneiden

Das Zuschneiden ist für JPEG-, PNG- und WebP-Bilder verfügbar, die in EmDash gespeichert und bereit sind. Bilder externer Anbieter lassen sich im lokalen Asset-Editor nicht zuschneiden.

Replace original ist nur beim Seitenverhältnis Original verfügbar. Verwenden Sie für Freeform und andere Verhältnisse Create cropped copy. Zugeschnittene Kopien liegen im selben Ordner wie ihr Quellelement und erhalten einen eindeutigen Dateinamen.

Das Zuschneiden eines animierten WebP erzeugt ein statisches WebP. Die Animation bleibt im zugeschnittenen Ergebnis nicht erhalten.

Sehen, wo eine Datei verwendet wird

Öffnen Sie eine lokale Datei und wählen Sie Used in, um die Inhaltseinträge und Site-Einstellungen aufzulisten, die auf sie verweisen. Jedes Inhaltsergebnis nennt die Sammlung und das Feld mit der Referenz und öffnet den Eintrag zur Bearbeitung. Einträge im Papierkorb sind in der Liste gekennzeichnet. Ein Site Settings-Ergebnis nennt die Einstellung, die die Datei auswählt: Logo, Favicon oder Default Social Image.

Used in prüft diese Referenzen:

• Bild- und Dateifelder
• Bildfelder in Repeatern
• Bild-, Datei- und Portable-Text-Felder in blocks-Feldern
• Bild-, Galerie- und Videoblöcke in Portable-Text-Feldern
• das Site-Logo, das Favicon und das Standard-Social-Bild

Wenn die Abdeckung der Nutzung vollständig ist und die Datei keine dieser Referenzen hat, zeigt die Liste No tracked references found. Bevor die Abdeckung vollständig ist, zeigt eine leere Liste No usage to show yet.

Die Nachverfolgung der Mediennutzung muss aktiviert sein, damit Inhaltsergebnisse vollständig sein können. Site-Einstellungen werden aufgelistet, unabhängig davon, ob die Nachverfolgung aktiviert ist. Ein Administrator aktiviert die Nachverfolgung einmalig für die Site:

Nach der Aktivierung lässt sich die Nachverfolgung der Mediennutzung nicht mehr deaktivieren. Neue Inhaltsänderungen werden nachverfolgt, nachdem die Erfassung aktiv ist; der Hintergrund-Scan ergänzt Referenzen aus Einträgen, die bereits vorhanden waren.

Wenn die Ansicht Used in meldet, dass die Indizierung läuft, veraltet, teilweise vorhanden oder fehlgeschlagen ist, behandeln Sie ihre Ergebnisse als unvollständig. Administratoren können zu Media usage tracking zurückkehren, um den aktuellen Status und Hinweise zur Wiederherstellung zu sehen.

Bilder in Vorlagen rendern

Ein Bildfeld gibt einen Medienwert zurück, keine einfache URL. Rendern Sie diesen Wert mit Image aus emdash/ui, damit lokale und von Anbietern bereitgestellte Bilder die passende URL, Abmessungen, den Fokuspunkt, responsive Varianten und einen Platzhalter in niedriger Qualität verwenden:

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

const { entry: post, error } = await getEmDashEntry("posts", Astro.params.slug);
if (error) return new Response("Unable to load post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

{post.data.featured_image && (
  <Image image={post.data.featured_image} width={1200} height={675} priority />
)}

Verwenden Sie priority nur für das sichtbare Hauptbild am Seitenanfang. Es fordert Eager Loading an und gibt dem Browser einen Hinweis auf eine hohe Fetch-Priorität. Andere Bilder sollten das Lazy Loading als Standard der Komponente beibehalten.

Wenn das Feld ein Bild für den Dunkelmodus hat, rendert Image beide Quellen und wählt anhand des Farbschemas des Besuchers eine davon aus. Informationen zur Einrichtung von Feld und Vorlage finden Sie unter Dunkle Bildvarianten.

Vorlagen erhalten die Medien-Metadaten, die zusammen mit der Inhaltsreferenz gespeichert sind, ohne die Medienbibliothek erneut abzufragen. Wenn eine benutzerdefinierte Integration die neuesten Metadaten des Anbieters benötigt, fordern Sie dieses Element explizit an und vermeiden Sie es, auf Sammlungsseiten für jedes Bild den Anbieter abzufragen. Die Referenz zu Feldtypen beschreibt die gespeicherten Datei- und Bildwerte.

Eine Datei in einer Vorlage rendern

Ein Dateifeldwert aus der Medienbibliothek enthält keine fertige URL. Übergeben Sie sein meta.storageKey an Astro.locals.emdash.getPublicMediaUrl(). Die Funktion gibt die öffentliche URL zurück und berücksichtigt eine konfigurierte öffentliche R2- oder S3-Domain, ohne die Medientabelle abzufragen. Ältere Werte ohne Storage-Key behalten ihre URL in url, und per URL hinzugefügte Dateien (mit provider: "external" gespeichert) behalten sie in src.

Bei einer Datei eines registrierten Medienanbieters, etwa Cloudflare Stream, enthält src ein Vorschaubild statt der Datei selbst. Dieses Vorgehen gilt dafür daher nicht.

Die folgende Seite rendert ein Video, das in einem Dateifeld namens video gespeichert ist:

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

const { entry, error } = await getEmDashEntry("videos", Astro.params.slug);
if (error) return new Response("Unable to load video", { status: 500 });
if (!entry) return Astro.rewrite("/404");

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

{url && <video src={url} controls preload="metadata" />}

Dieselbe URL funktioniert für einen Download-Link oder jedes andere Element, das die Adresse der Datei benötigt. Dateiname, MIME-Typ und Größe im Wert sind die beim Auswählen der Datei gespeicherten.

Speicher und Anbieter konfigurieren

Die lokale Bibliothek speichert Dateien über den für die Site konfigurierten Speicheradapter. Node.js-Sites können lokalen Datenträger oder S3-kompatiblen Speicher verwenden; Cloudflare-Sites verwenden üblicherweise ein R2-Binding. Der Adapter entscheidet, wo die Bytes liegen, und die Medienbibliothek behält denselben Redaktions-Workflow bei. Informationen zu Konfiguration und Anforderungen an die Persistenz in der Produktion finden Sie unter Medienspeicher auswählen.

Cloudflare Images und Cloudflare Stream lassen sich als externe Medienanbieter registrieren. Sie erscheinen als Quellen in der Auswahl, und Image versteht von Anbietern bereitgestellte Bildwerte. Die Elemente des Anbieters werden weiterhin von diesem Dienst verwaltet, daher stehen lokale Ordner, Fokuspunkte, Zuschneiden und Ersetzen für diese Elemente im Asset-Editor von EmDash nicht zur Verfügung.

Medien sicher löschen

Öffnen Sie die Datei in der Medienbibliothek, wählen Sie Delete und bestätigen Sie das dauerhafte Löschen. Autoren können lokale Dateien löschen, die sie selbst hochgeladen haben; Redakteure können jede lokale Datei löschen. Elemente von Anbietern werden nur dann beim Anbieter gelöscht, wenn die Quelle das Löschen anbietet und der aktuelle Benutzer dazu berechtigt ist.

Informationen zu automatisierten Uploads und zur Medienverwaltung finden Sie in der Referenz zu den Medien-Endpunkten oder bei den CLI-Medienbefehlen. Fahren Sie mit Mit Inhalten arbeiten fort, um Einträge zu veröffentlichen, die die gewählten Medien verwenden.