---
title: 'Exporte'
description: 'CSV, XLSX, JSON aus Listen, vordefinierte und eigene Skript-Exporte.'
---

import { Aside, Tabs, TabItem, Steps, Card, CardGrid, Badge } from '@astrojs/starlight/components';

Du exportierst Einträge einer Sammlung im **tibi-admin** (Verwaltungs-Backend, Release Nova) direkt aus der [Liste](/admin/ansichten-listen/): als Datei für Tabellen­kalkulation, Datenaustausch oder eigene Berichte. Exportiert wird, was du siehst — Filter und Suche der Liste gelten auch für den Export.

## Listen-Export

<Steps>

1. Liste filtern und sortieren, bis sie zeigt, was du brauchst.
2. Export-Knopf über der Liste klicken.
3. Format wählen: `JSON`, `CSV` oder `XLSX`.
4. Spalten per Checkbox anhaken (Vorauswahl: sichtbare Tabellenspalten; `object[]`-Felder erscheinen einmal und werden beim Schreiben aufgefächert).
5. Herunterladen — der Dateiname enthält Sammlung und Datum.

</Steps>

| Format | Technik | Wofür |
|---|---|---|
| `JSON` | Rohdatensätze als Datei | Weiterverarbeitung, Sicherung, Import anderswo |
| `CSV` | Tabellenzeilen aus der `xlsx-js-style`-Bibliothek | Excel-, Numbers- oder Skript-Import |
| `XLSX` | Arbeitsmappe aus derselben Bibliothek (Zell-Stile möglich) | Formatierte Weitergabe an Menschen |

<Aside type="note">
`xlsx-js-style` (SheetJS-Fork mit Zell-Stilen) ist die einzige Tabellen-Bibliothek im Admin — beide Tabellenformate kommen aus ihr (`json_to_sheet` für XLSX, `sheet_to_csv` für CSV).
</Aside>

- **Große Mengen:** Vor dem Laden schätzt der Admin die Trefferzahl über `GET …/<sammlung>/_count` (gleicher Filter wie die Liste, Suche als Obergrenze) und warnt dich vor sehr großen Exporten.
- **Dynamische Spalten:** Wachsen Arrays unterschiedlich lang, fragt der Dialog nach, ob er die Spalten auffächern soll — brichst du ab, bleibt der Dialog offen.

## Vordefinierte Skript-Exporte

Stehen im Export-Dialog eigene Reiter **vor** dem Standard-Tab, hat das Projekt fertige Berichte in `collection.meta.exports` hinterlegt (Name, Datei, optional Dateiname mit `{date}`-Platzhalter). Ein Klick führt das Skript mit dem aktuellen Listenfilter aus — inklusive Fortschrittsbalken.

```yaml title="Export-Definition in der Sammlungs-Config"
# Beispiel-Eintrag in der Sammlungs-Config
exports:
  - name: bestellreport
    label: { de: "Bestellreport", en: "Order report" }
    file: "_/assets/exports/reports.mjs"
    filename: "bestellreport-{date}.xlsx"
```

## Eigenes Skript

Projekt-Entwickler legen eigene Exporte als ES-Modul unter `meta.exports[].file` ab (Pfad mit `_/`-Präfix = projekt-relativ, empfohlen). Das Modul exportiert **eine Standard-Funktion**, die Kontext (Filter, Auswahl, Fortschritt) bekommt und genau ein Ergebnis zurückgibt:

| Rückgabe | Inhalt |
|---|---|
| `workbook` | XLSX-Arbeitsmappe (wird als `.xlsx` gespeichert) |
| `blob` | Fertiger `Blob` (z. B. aus Fremd-Lib) |
| `text` | Text wie CSV oder HTML |
| `bytes` | Binärdaten wie PDF (`Uint8Array`/`ArrayBuffer`) |

Dazu Pflicht: `filename` und `contentType` (z. B. `text/csv`, `application/pdf`) — ohne `contentType` wirft der Admin einen Fehler. Genau ein Payload pro Ergebnis.

```js title="reports.mjs (vereinfacht)"
// reports.mjs — stark vereinfacht
export default async function (ctx) {
  const rows = await ctx.db.loadAll({ filter: ctx.filter });
  ctx.progress(1, 1, "Fertig");
  const wb = ctx.xlsx.utils.json_to_sheet(rows);
  return { workbook: { SheetNames: ["Report"], Sheets: { Report: wb } }, filename: "bestellreport-{date}.xlsx", contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" };
}
```

Details für Entwickler (Kontext-Felder, Dateinamen-Platzhalter, Sanitizing) stehen in der Admin-Repo-Doku `custom-export-script.md` — im Zweifel gilt der Code (`utils/load-custom-export.ts`, `utils/custom-export-context.ts`, `utils/export.ts`).

## Häufige Fehler

| Fehlerbild | Ursache | Lösung |
|---|---|---|
| Export enthält „falsche“ Einträge | Listenfilter (Reiter, Feld-Filter, Suche) enger als gedacht | Filter in der Liste prüfen — der Export übernimmt sie eins zu eins |
| Spalten-Warnung erscheint | Arrays ungleicher Länge brauchen aufgefächerte Spalten | Auffächern bestätigen oder Spaltenauswahl verkleinern |
| Eigener Reiter fehlt | `meta.exports`-Eintrag ohne `name` oder `file` | Projekt-Config ergänzen (beide Pflicht), Admin neu laden |
| Skript-Fehler im Dialog | Modul ohne Standard-Export oder Laufzeitfehler | Browser-Konsole lesen, Modul-Export und Rückgabeformat prüfen |
| Leere Datei trotz Treffern | Leserecht auf Zielfelder fehlt | Rechte unter [Rechte und Tokens](/projekt/rechte-tokens/) klären |

<!-- Screenshot-Platzhalter (T-SHOTS): Export-Dialog mit Formatwahl und Spaltenliste, Alt-Text deutsch, max. 200 KB unter src/assets/. -->

Verifiziert am 2b091d89 2026-10-13 (tibi-admin-nova)