Workflow/tasks/excel_lesen.md

excel_lesen — gezielt aus xlsx in den Context lesen

Zweck: Liest präzise aus einer Excel-Datei: bestimmtes Blatt, bestimmter Bereich, optional erste Zeile als Feldnamen (→ Zeilen als Objekte), sowie einzelne Zellen → benannte Context-Variablen. Basis: PhpSpreadsheet.

Parameter

Name	Pflicht?	Default	Beschreibung
datei	ja	—	Serverpfad zur xlsx (z.B. {{upload_pfad}}).
blatt	nein	aktiv	Name oder 1-basierter Index.
bereich	nein	belegte Fläche	Zellbereich, z.B. A2:C100.
kopfzeile	nein	0	1 = erste Zeile = Feldnamen → Zeilen als Objekte {Feld:Wert}.
zellen	nein	—	JSON {"vkz":"B1","stichtag":"B2"} — Zelle → benannte Context-Var.
output_var	nein	excel	Ergebnis-Präfix.

Ausgangswerte

{{<prefix>_zeilen}} (Array — Objekte bei kopfzeile, sonst Zahlen-Arrays; für loop_foreach), {{<prefix>_json}}, {{<prefix>_anzahl}}, {{<prefix>_kopf}} (Feldnamen). Einzelzellen als die in zellen genannten Variablen.

Beispiel

<task type="excel_lesen" id="einlesen">
  <config>
    <datei>{{upload_pfad}}</datei>
    <blatt>Gemeinden</blatt>
    <bereich>A3:B100</bereich>
    <kopfzeile>1</kopfzeile>
    <zellen>{"titel":"A1"}</zellen>
    <output_var>tab</output_var>
  </config>
</task>
<!-- danach: {{#tab_zeilen}}{{Gemeinde}} / {{Art}}{{/tab_zeilen}} , {{titel}} , {{tab_anzahl}} -->

Hinweise

• Leere Zeilen werden übersprungen. setReadDataOnly (schnell; keine Formate).
• Feldnamen = Kopfzeilen-Text (Spalten mit leerem Titel werden ausgelassen).
• Gegenstück: excel_schreiben. Lib: PhpSpreadsheet in comp/vendor.