Eingabefelder: Button

1. Übersicht und Zweck

Status: [Live] — widgets::button() plus .wk-btn-Basis-CSS. Herkunft und ARIA-Vertrag der Zeile „Button„ im Basis-Widget-Katalog (role=„button“/aria-pressed/aria-disabled, Zustände disabled/hover/focus/checked). Referenz: DevExpress ASPxButton (RenderMode-Enum Button/Link/Secondary/Outline/Danger).

2. Voraussetzungen

Gemeinsamer Feld-Kontrakt bereits verstanden.

3. Konzepte

ASPxButton.RenderMode deckt sich fast wörtlich mit der bereits etablierten Contract-v3-Farbsemantik dieser Bibliothek (weiß/blau/rot, s. Massenaktionen → Buttons) — Vertrag übernimmt diese Semantik, statt eine vierte Farbskala zu erfinden.

4. Erste Schritte

echo $widgets->button([
    'name'  => 'do',
    'value' => 'delete',
    'label' => 'Verbindung löschen',
    'variant' => 'danger',
]);

Falsch: variant ⇒ 'danger' ohne vorgeschalteten Bestätigungsdialog einsetzen (s. Abschnitt 7, Sicherheit).

5. Verwendung

Ton und Darstellungsart sind zwei Achsen

Seit dem 5. August 2026 trägt eine Schaltfläche zwei unabhängige Angaben: der Ton sagt, wie wichtig oder wie gefährlich die Aktion ist, die Darstellungsart, wie laut sie gezeichnet wird.

`$opts['tone']`	Bedeutung
`neutral` (Vorgabe)	gewöhnliche, nicht-destruktive Aktion
`primary`	Hauptaktion eines Formulars oder Dialogs
`danger`	destruktive Aktion — erfordert Bestätigung
`success`	Aktion, die etwas abschließt oder bestätigt

`$opts['appearance']`	Bedeutung
`filled` (Vorgabe)	gefüllte Fläche im Ton
`outline`	nur Rahmen und Schrift im Ton, Fläche bleibt die Umgebung
`link`	textartig, kein Schaltflächen-Chrome

Beide sind frei kombinierbar. „Destruktiv, aber zurückhaltend“ ist damit ausdrückbar (tone ⇒ 'danger' zusammen mit appearance ⇒ 'outline') — vorher war es das nicht, weil Ton und Darstellungsart in einer Liste lagen.

Die Kurzform ''variant'' gilt weiter

Jeder ihrer Werte ist ein Paar aus Ton und Darstellungsart. Das erzeugte Markup ist für alle fünf unverändert; ausdrücklich gesetzte Achsen stechen die Kurzform.

`$opts['variant']`	entspricht	Einsatz
`primary`	`tone=primary`, `appearance=filled`	Hauptaktion eines Formulars/Dialogs
`secondary`	`tone=neutral`, `appearance=filled`	gewöhnliche, nicht-destruktive Aktion
`outline`	`tone=neutral`, `appearance=outline`	zurückhaltende Nebenaktion
`danger`	`tone=danger`, `appearance=filled`	destruktive Aktion — erfordert Bestätigung
`link`	`tone=neutral`, `appearance=link`	Aktion in Fließtext-Kontext
`success`	`tone=success`, `appearance=filled`	neu am 5. August 2026

Die Vorgabe hat sich geändert und lautet jetzt sachlich. Bis zum 5. August 2026 bekam eine Schaltfläche ohne Angabe — und eine mit einem falsch geschriebenen Namen — die lauteste Stufe des Systems. Das ist die falsche Richtung zum Scheitern: ein unbekannter Name heißt, dass die Absicht des Aufrufers unbekannt ist, und die sichere Darstellung einer unbekannten Absicht ist die leise.

Der Wechsel war folgenlos, und das ist vorher gemessen worden, nicht angenommen: alle 19 Aufrufer im Haus geben ihren Ton ausdrücklich an, keiner verließ sich auf die Vorgabe.

Frühere Fassungen dieser Seite nannten die Töne bei ihren Farben („blau„, „rot“). Das ist seit der Paletten-Überarbeitung nicht mehr zutreffend — der Akzent ist kein Blau mehr, und er ändert sich zudem mit dem gewählten Farbschema und der Markenfarbe. Maßgeblich ist die Rolle, nicht der Farbwert.

6. API-Referenz

Methode button(array $opts): string in helper_plugin_wkfluentui_widgets.

7. Parameter, Optionen und Zustände

Schlüssel	Typ	Bedeutung
`tone`	string	s. Abschnitt 5, Default `neutral`
`appearance`	string	s. Abschnitt 5, Default `filled`
`variant`	string	Kurzform für ein Paar aus beidem, s. Abschnitt 5. Default: `neutral`/`filled` — auch bei einem unbekannten Wert
`type`	`'submit'\|'button'\|'reset'`	natives Button-`type`-Attribut, Default `submit`
`icon`	string	optionales Icon-Markup vor dem Label (vertrauenswürdiges HTML, wie `controlHtml` bei `propertyGrid()`)
`confirm`	string	falls gesetzt: nativer `data-wk-confirm`-Text, den `scripts/formfields.js` vor dem Formular-Submit als `modal()`-Bestätigung zeigt — No-JS-Fallback: Submit erfolgt sofort, Server-Handler bleibt die verbindliche Prüfinstanz

Sicherheit: wie bei destruktiven Massenaktionen (Massenaktionen) muss ein roter Button entweder selbst einen modal()-Bestätigungsdialog auslösen oder Teil eines Formulars sein, dessen Server-Handler die Aktion erneut prüft — nie eine destruktive Aktion ohne Rückfrage direkt auf Klick ausführen. Der confirm-Text ist reine Client-Bequemlichkeit, keine Sicherheitsgrenze.

8. Vollständige Beispiele

echo $widgets->button([
    'name'    => 'do',
    'value'   => 'save',
    'label'   => 'Speichern',
    'variant' => 'primary',
    'type'    => 'submit',
]);

9. Einschränkungen und Randfälle

Zustände

Zustand	Gefüllter Ton	`outline` und `link`
`hover`	benannter Hover-Wert (`primary`) bzw. Helligkeitsstufe	aus den Flächentokens gemischter Grund
`active`	Helligkeitsstufe `--wk-state-press-dim`	Mischung mit `--wk-state-press-tint`
`disabled`	`opacity`	`opacity`

Warum zwei Mechanismen. Eine Schaltfläche mit eigener Farbe (Hauptaktion, Gefahr, Erfolg) wird beim Drücken abgedunkelt; ihre eigene Schrift hineinzumischen würde sie im hellen Schema heller machen, während ihr Hover-Wert sie dunkler macht — eine Geste, zwei Richtungen. Eine Schaltfläche, die die Umgebungsfläche erbt (sachlich, umrandet, textartig), hat keine eigene Farbe zum Abdunkeln und nimmt deshalb dieselbe Mischung wie die Eingabefelder.

Bis zum 5. August 2026 zeichnete kein einziges Bauteil des Hauses einen Druckzustand. Ein Klick wurde allein durch das bestätigt, was danach passierte — bei einem Formular-Absenden also durch einen Seitenaufbau, auf den der Benutzer noch wartete.

10. Accessibility und Kompatibilität

Vollständiger Überblick: Accessibility.

11. Troubleshooting

Entfällt.

12. Verwandte Themen

Demo-Übersicht — alle Kategorien
FluentUI: Basis-Widget-Katalog — Tier-2-CSS-/ARIA-Vorstufe
Styles-Contract (--wk-*) — Farbsemantik, der variant folgt
DataGrid: Data Editing (Massenaktionen) — Live-Vorbild für destruktive Bestätigung