Doku-Vollausbau: 62 Seiten (Projekt/Admin/Anwender/Referenz), Hook-Referenz mit Signaturen, Corporate-Screenshots, Coverage-Inventar

- Einstieg: Schnellstart + Neues Projekt aus Starter-Skill, Was-ist-Tibi mit Backend/Website-Trennung - Projekt: Sammlungen, Felder, Abfragen, Rechte, Hooks, Dateien, i18n, Suche, SSR, Pagebuilder, Jobs, Audit, Deploy, LLM, MCP - Hook-Referenz: 66 Symbole mit Signatur + Beispiel + Fehlerfall (5 Kapitel) - Admin: Ansichten, Editor, Medien, Exporte, Aktionen, Rechte, KI, Setup, Customizing - Anwender: 11 Anleitungen im professionellen Du-Ton, 30 Corporate-Screenshots - Referenz: Schemas, Token-Köpfe, Fehlerbilder, Shortcuts, OpenAPI-Platzhalter - ADR-0001 bis 0003, Coverage-Skript (282 Items) + Map, Plan-Dateien
2026-10-16 22:49:07 +00:00
1 parent acb1d32355
commit 1897bb50d9
@@ -0,0 +1,85 @@
+---
+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 Tabellenkalkulation, 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)