numolus/documentation/konzept-formelhilfe.md

Formelhilfe: Argumenthinweis und Formelassistent

Stand: 23.10.2026 · Status: Optionen, nicht beschlossen

Dieses Papier hält zwei Ausbaustufen fest, die beim Eingeben von Formeln helfen sollen. Option A ist klein und für sich nützlich, Option B baut auf ihr auf.

Ausgangslage

• Beim Tippen eines Funktionsnamens zeigt eine Liste passende Funktionen mit ihrer Signatur, z. B. IF(Bedingung; Dann; Sonst?) (composables/useFormulaAutocomplete.ts, components/FormulaSuggest.vue).
• Sobald die öffnende Klammer steht, verschwindet die Liste. Danach zeigt nichts mehr an, welches Argument gerade eingegeben wird oder was es bedeutet.
• Die Signaturen der 36 eingebauten Funktionen liegen als Freitext in BUILTIN_SIGNATURES (engine/functions.ts). Deutsche Kurzbeschreibungen stehen in FUNCTION_DESCRIPTIONS (data/codeReference.ts), werden bisher aber nur in der Befehlsreferenz des Makro- und Funktionseditors angezeigt.
• Eigene Funktionen des Dokuments haben benannte Parameter (FunctionDef.params).
• Es gibt keine Funktion, die eine Formel auswertet, ohne sie in eine Zelle zu schreiben.

Option A: Argumenthinweis

Verhalten

Steht der Cursor innerhalb eines Funktionsaufrufs, erscheint unter dem Editor eine Zeile wie in Excel:

IF(Bedingung; Dann; Sonst?) Liefert Dann, wenn die Bedingung wahr ist, sonst Sonst.

• Das Argument, in dem der Cursor steht, ist fett. Gezählt wird über die ; auf der Ebene dieser Funktion.
• Bei verschachtelten Aufrufen gilt die innerste Funktion um den Cursor: In =IF(SUM(A1;| wird SUM angezeigt.
• Bei Argumenten, die sich wiederholen dürfen (Zahl1; Zahl2; …), bleibt ab dem zweiten Argument der letzte Platzhalter hervorgehoben.
• Gilt im Zelleditor und in der Formelleiste, für eingebaute und für eigene Funktionen.
• Die Vervollständigungsliste hat Vorrang. Ist sie offen, wird der Hinweis ausgeblendet.
• Innerhalb einer Zeichenkette ("…") und außerhalb jedes Aufrufs wird nichts angezeigt. Escape schließt den Hinweis, bis der Cursor in einen anderen Aufruf wechselt.

Umsetzung

• Engine: functionCallAtCaret(formula, caret) liefert { name, argIndex } oder null. Dazu wird der Text bis zum Cursor zerlegt und ein Stapel der offenen Klammern mit Funktionsnamen und Anzahl der ; geführt. Der Aufbau entspricht den vorhandenen Hilfen currentIdentifierAtCaret und cycleReferenceLocks in engine/refs.ts.
• Signatur zerlegen: Die Parameter werden aus dem Hinweistext gelesen (? = optional, … = Wiederholung). Bei eigenen Funktionen kommen sie aus FunctionDef.params.
• Oberfläche: Eine kleine Komponente ArgumentHint.vue, die Zelleditor (TableGrid.vue) und Formelleiste (FormulaBar.vue) gleich einbinden, wie heute schon FormulaSuggest.vue.
• Tests für functionCallAtCaret (Verschachtelung, Zeichenketten, leere Argumente, …) und für das Zerlegen der Signaturen.

Aufwand

Klein, ungefähr ein Tag einschließlich Tests.

Option B: Formelassistent

Ablauf

1. Ein Klick auf „fx“ in der Formelleiste öffnet den Assistenten. Als Tastenkürzel bietet sich Umschalt+F3 an (wie „Funktion einfügen“ in Excel). Ohne laufende Bearbeitung beginnt die Formel in der aktiven Zelle.
2. Funktion wählen: Suchfeld und Kategorien (Mathematik, Statistik, Text, Logik, Datum & Zeit, Nachschlagen, eigene Funktionen). Zu jeder Funktion werden Signatur und Beschreibung angezeigt.
3. Argumente eingeben: Für jeden Parameter gibt es ein Feld mit Namen, kurzer Erklärung und der Kennzeichnung „optional“. Wiederholbare Argumente bekommen ein neues Feld, sobald das letzte gefüllt ist. Neben jedem Feld steht sein aktueller Wert, im Fehlerfall die Meldung.
4. Bezüge übernehmen: Ist ein Feld aktiv, übernimmt ein Klick oder Ziehen in der Tabelle den Bezug, ebenso die Pfeiltasten. Dafür meldet sich das Feld als Formeleditor an (registerFormulaEditor). Der Zeigemodus, die farbigen Bezüge und die Zieh-Griffe funktionieren so ohne Änderung.
5. Vorschau: Unten stehen die fertige Formel und ihr Ergebnis, laufend aktualisiert.
6. Übernehmen fügt den Aufruf an der Cursorstelle ein, Abbrechen lässt die Formel unverändert.

Steht der Cursor beim Öffnen in einem bestehenden Aufruf, öffnet der Assistent genau diese Funktion mit ihren Argumenten in den Feldern. „Übernehmen“ ersetzt dann nur diesen Aufruf. Dafür wird der Helfer aus Option A um die Textgrenzen des Aufrufs und seiner Argumente erweitert.

Voraussetzungen

• Parameter genauer beschreiben: Statt des Hinweistextes eine strukturierte Beschreibung je Funktion, z. B. { name, category, description, params: [{ name, description, optional, repeat }] }. BUILTIN_SIGNATURES und die Befehlsreferenz werden daraus erzeugt, damit es nur eine Quelle gibt. Heute ist der Hinweistext teils ungenau: XLOOKUP(Suchwert; Suchbereich; Rückgabebereich; …) verschweigt die optionalen Argumente WennNichtGefunden und Vergleichsmodus.
• Formel ohne Zelle auswerten: Neue Store-Funktion, die einen Formeltext im Zusammenhang einer Zelle (Tabelle, Spalte, Zeile) auswertet, ohne das Dokument zu ändern, kein markDirty(), kein Eintrag im Rückgängig- Verlauf. Wird für die Vorschau und die Werte der einzelnen Felder gebraucht.

Umsetzung

• FormulaWizard.vue als Dialog auf Basis von BaseModal.vue, der aber die Tabelle nicht verdeckt (seitlich oder verschiebbar), damit Bezüge gewählt werden können.
• Store: Auswertung ohne Zelle (siehe oben), sonst nur vorhandene Schnittstellen (registerFormulaEditor, pointClick/pointDrag, formulaRefs).
• Die Argumentfelder brauchen die gleiche Verarbeitung wie die Formelleiste (Zeigemodus mit Pfeiltasten, Vervollständigung, F4). Diese wird dafür aus FormulaBar.vue herausgelöst, damit sie nicht ein drittes Mal entsteht.
• Tests: strukturierte Beschreibung vollständig für alle Funktionen in FUNCTIONS, Zusammensetzen und Zerlegen eines Aufrufs, Auswertung ohne Zelle verändert das Dokument nicht.

Aufwand

Mittel bis groß, ungefähr drei bis fünf Tage. Davon entfällt etwa ein Tag auf die Beschreibungen der Parameter aller Funktionen.

Reihenfolge

A zuerst. Der Helfer functionCallAtCaret und das Zerlegen der Signaturen werden in B wiederverwendet. Die strukturierte Beschreibung aus B kann nachträglich auch den Hinweis in A verbessern (Erklärung je Argument statt nur je Funktion).

Festlegung: deutsche und englische Funktionsnamen

Funktionen können deutsch oder englisch eingegeben werden (=SUMME(A1:A5) oder =SUM(A1:A5)). Gespeichert wird immer der englische Name. Der deutsche Name ist nur ein Alias für die Eingabe.

• Umwandlung beim Übernehmen: Beim Bestätigen der Eingabe (Enter, Tab, Verlassen des Feldes) werden deutsche Funktionsnamen durch die englischen ersetzt, an derselben Stelle wie das Schließen fehlender Klammern (completeFormula). Ersetzt wird nur ein Name direkt vor (, nie in Zeichenketten, Tabellen- oder Blattnamen oder benannten Bereichen. Groß- und Kleinschreibung spielt keine Rolle.
• Dateiformat und Engine bleiben unverändert: .num/.json, Export, Zusammenarbeit und Auswertung sehen nur englische Namen. Ältere Dokumente brauchen keine Umstellung.
• Zuordnung: Eine Tabelle deutscher Aliasse je Funktion, angelehnt an die deutschen Excel-Namen, z. B. SUMME→SUM, MITTELWERT→AVERAGE, ANZAHL→COUNT, ANZAHL2→COUNT2, VERKETTEN→CONCATENATE, TEXTKETTE→CONCAT, WENN→IF, UND→AND, ODER→OR, NICHT→NOT, DATUM→DATE, ZEIT→TIME, HEUTE→TODAY, JETZT→NOW, JAHR→YEAR, MONAT→MONTH, TAG→DAY, STUNDE→HOUR, SEKUNDE→SECOND, WOCHENTAG→WEEKDAY, ISOKALENDERWOCHE→ISOWEEKNUM, KALENDERWOCHE→WEEKNUM, EDATUM→EDATE, MONATSENDE→EOMONTH, TAGE→DAYS, NETTOARBEITSTAGE→NETWORKDAYS, ARBEITSTAG→WORKDAY, DATWERT→DATEVALUE, ZEITWERT→TIMEVALUE, XVERWEIS→XLOOKUP. Gleichnamige (MIN, MAX, MINUTE, DATEDIF) brauchen keinen Alias. Ein Test stellt sicher, dass jedes Alias auf eine vorhandene Funktion zeigt und kein Alias einem englischen Namen gleicht.
• Vervollständigung, Hinweis und Assistent: Die Vorschlagsliste findet eine Funktion über beide Namen (Tippen von SUM oder SUMME schlägt dieselbe Funktion vor) und zeigt den deutschen Namen mit dem englischen daneben. Argumenthinweis (Option A) und Assistent (Option B) erkennen beide Schreibweisen.
• Eigene Funktionen: Sie haben nur den Namen, den der Benutzer ihnen gibt. Es gibt für sie keinen Alias, und ihr Name wird weder bei der Eingabe noch bei der Anzeige umgewandelt.
• Keine Überschneidung mit eingebauten Namen: Der Name einer eigenen Funktion darf weder einem englischen Funktionsnamen noch einem deutschen Alias gleichen, ohne Rücksicht auf Groß- und Kleinschreibung (Sum, SUMME, wenn sind alle abgewiesen). Sonst wäre unklar, welche Funktion gemeint ist. Die Prüfung gehört dorthin, wo heute schon englische Namen abgewiesen werden (hasFunction beim Anlegen und Umbenennen in store/document.ts), und wird um die deutschen Aliasse erweitert. Bestehende Dokumente können schon eine eigene Funktion enthalten, die wie ein neuer deutscher Alias heißt (z. B. WENN). Für diesen Fall braucht es beim Öffnen einen Hinweis mit der Aufforderung, sie umzubenennen. Bis dahin gewinnt die eigene Funktion, damit sich vorhandene Ergebnisse nicht ändern.
• Anzeige deutsch: Überall, wo der Benutzer eine Formel sieht oder bearbeitet (Zelleditor, Formelleiste), stehen die deutschen Namen. Die Umwandlung englisch→deutsch geschieht nur für die Anzeige, beim Öffnen des Editors und beim Füllen der Formelleiste. Beim Übernehmen wird wieder englisch gespeichert. Wird eine Formel nur geöffnet und unverändert bestätigt, ergibt die Rückumwandlung denselben Text, das Dokument gilt dann nicht als geändert. Export und Kopieren in andere Programme liefern den gespeicherten, englischen Text.
• Nicht in Makros und Funktionen mit Schleife: Deren Code kennt nur die englischen Namen. Dort wird nichts umgewandelt, und die Befehlsreferenz in diesen Editoren zeigt weiterhin englische Namen. Ein deutscher Name wird dort wie jeder andere unbekannte Funktionsname behandelt.

Offene Fragen

• Einzeilige eigene Funktionen: Gilt die deutsche Eingabe auch für den Rumpf einer eigenen Funktion ohne Schleife (kind: 'expression')? Der Rumpf ist eine einzelne Formel, wird aber im Funktionseditor bearbeitet, nicht in einer Zelle.

• Kategorien: Die Einteilung oben ist ein Vorschlag. Heute gehören alle Funktionen zur Kategorie „Formelfunktionen“.

• Nur lesen: Bei Dokumenten ohne Schreibrecht sollen Hinweis und Assistent zum Nachschlagen verfügbar sein, „Übernehmen“ aber nicht.

• Zusammenhang mit einer Hilfe in der App: Eine Hilfe mit Tastenkürzeln und Funktionsliste (bisher nur angedacht) könnte dieselbe strukturierte Beschreibung nutzen.