Zum Inhalt springen
Tibi Doku

Dateien und Bilder

Dateien liegen in der Sammlung medialib. Du lädst sie per POST hoch, verknüpfst sie per ID und zeigst sie nur über die Komponente MedialibImage an. Suchbegriffe: Datei hochladen, Bild anzeigen, Bildfilter.

Upload-Format

Abschnitt betitelt „Upload-Format“

  1. Lege einen medialib-Eintrag mit einem file-Objekt an — src als Data-URI, path als Dateiname:

    Upload per POST (Data-URI)
    POST /api/v1/_/<namespace>/medialib
    {"title": "Demo Hero", "active": true, "file": {"src": "data:image/jpeg;base64,…", "path": "demo-hero-1200.jpg"}}

  2. Prüfe die Antwort: file.src beginnt danach mit <feld>/, zum Beispiel file/demo-hero-1200.jpg.

  3. Lies Listen immer ohne Datei-Bytes:

    Liste ohne Datei-Bytes lesen
    GET …/medialib?select=title,alt,tags
Richtig Falsch
{src: 'data:…;base64,…', path: 'name.jpg'} (path optional) {filename, data}-Format
file als Objekt file als reiner String
file.src nach dem Speichern beginnt mit file/ ?filter= an Data-URIs hängen

Grenzen aus medialib.yml: file ist Pflicht, max. 50MB, Downscale auf max. 2048 px beim Upload (downscale.maxWidth/maxHeight).

Speicherformat

Abschnitt betitelt „Speicherformat“

Gespeichert wird {src: '<feld>/name.jpg', path, type} — also relativer Pfad plus erkannter MIME-Typ. Die Widgets file, file[] und foreignFile schreiben dieses Format; foreignMedia in content.yml (blocks.heroImage.image, blocks.image) verweist per Medialib-ID darauf.

Anzeige-Regel: nur MedialibImage

Abschnitt betitelt „Anzeige-Regel: nur MedialibImage“

Baue Bild-URLs nie von Hand. Die Komponente frontend/src/widgets/MedialibImage.svelte nimmt id oder entry, löst file.src auf und wählt den Filter nach Breite.

Bild-URL mit Filter (Beispiel)
/api/medialib/<entryId>/file/<name>?filter=l-webp

So nutzen es die Blöcke: HeroBlock.svelte löst block.heroImage?._lookup?.image (Fallback block._lookup["heroImage.image"]) auf und rendert bei fehlendem Bild einen Verlauf statt eines Bildes. RichtextBlock.svelte nutzt block._lookup?.image — ohne aufgelösten Lookup bleibt das Bild unsichtbar.

Hero-Lookups (immer gemeinsam)
GET …/content?lookup=blocks.heroImage.image:medialib,blocks.image:medialib

Beide Lookups immer gemeinsam anfordern (Empfehlung aus content.yml).

Filter

Abschnitt betitelt „Filter“

Die Größen stehen in api/collections/lib/imageFilter.yml (imageFilter-Block in content.yml und medialib.yml):

Filter Breite Qualität Ausgabe
xs-webp 100 px (100×100, fit) 60 webp
s-webp 300 px 70 webp
m-webp 600 px 76 webp
l-webp 1200 px 80 webp
xl-webp 2000 px 84 webp
xxl-webp 2800 px 88 webp

MedialibImage wählt automatisch (minWidth-Messung, Standard l-webp); du kannst filter auch fest setzen, z. B. ?filter=l-webp. ?filter= wirkt nur auf gespeicherte Dateien per URL — nicht auf Data-URIs.

Fehlerbilder

Abschnitt betitelt „Fehlerbilder“
Symptom Ursache Lösung
Nur IDs, kein _lookup lookup=…:medialib fehlt in der Abfrage Lookup-Parameter ergänzen (siehe Lesen und suchen)
_lookup öffentlich leer, mit Token voll active:true fehlt am Medialib-Dokument active:true speichern
Hero zeigt Verlauf statt Bild Lookup unaufgelöst (file.src fehlt) Eintrag + active:true + Lookup prüfen
Richtext-Bild verschwindet öffentlich Gleicher Grund Gleicher Fix
Riesige Antworten file.data mitgelesen select ohne Dateifelder nutzen
Dateien bleiben nach Löschen übrig? Reste bleiben nur bei Fehlern liegen — beim Löschen räumt der Server das Upload-Verzeichnis automatisch weg warning in Delete-Antwort bzw. Server-Log prüfen, Rest per Dateisuche im Upload-Pfad löschen. Details: Betrieb

Weiter: Lesen und suchen, Rechte und Tokens, Sammlungen anlegen.

Verifiziert am e3f92eb 2026-10-17 (tibi-svelte-starter)