enhancement
major
minor
major
minor
minor
#29550
React-Kontrollen nutzen die „radius“- und „surface“-Tokens des Themes nicht einheitlich; ein „flat“-Theme erfordert CSS-Überschreibungen auf Komponentenebene
Betrifft 8.0.0-alpha8 (tl-layout-react, tl-react-controls-css).
Das Problem
Ein in UIThemeService deklariertes Theme, das „default“ erweitert und Folgendes festlegt:
{{{#!xml <length name="corner-radius" value="0"/> <length name="border-radius-02" value="0"/> }}}
wird in der App-Leiste, der Seitenleiste und deren Elementen, Panels, Schaltflächen, Feldern, Fenstern, Karten, der Tabellenansicht, Registerkarten und geteilten Panels weiterhin mit abgerundeten Ecken dargestellt. Um ein flaches Design zu erzielen, muss die Anwendung ein Stylesheet mit folgendem Inhalt hinzufügen:
{{{#!css .tlAppBar, .tlSidebar, .tlSidebar__item, .tlPanel, .tlReactButton, .tlField, .tlWindow, .tlCard, .tlTableView, .tlTab, .tlSplitPanel { border-radius: 0; } }}}
Dies ist eine Liste von Framework-Klassennamen, von denen die Anwendung nun abhängt, und in der später hinzugefügte Steuerelemente stillschweigend nicht berücksichtigt werden.
Das Gleiche gilt für eine Handvoll Oberflächenfarben, die überhaupt kein Token haben, sodass sie nur über einen Klassenselektor geändert werden können:
- Hintergrund der Seitenleiste und deren rechter Rand,
- Hintergrund und Rahmenfarbe des Panels,
- Fensterhintergrund und -schatten,
- Farbe der Tabellenüberschrift und der Zellgitterlinien.
Das Theme definiert bereits „layer-01“, „border-subtle“, „shadow-menu“ und die Radiuswerte; die Steuerelemente lesen diese Werte jedoch nicht überall aus.
Vorgeschlagene Korrektur
- Überprüfen Sie „tl-react-controls-css“ auf fest codierte „border-radius“-Werte und leiten Sie diese jeweils über die Radius-Tokens des Themes weiter (ein Token für Steuerelemente, eines für Oberflächen, wie die beiden vorhandenen Längen nahelegen).
- Überprüfen Sie dasselbe Stylesheet auf fest codierte Hintergründe, Rahmen und Schatten bei den oben genannten Containern und verknüpfen Sie diese mit den vorhandenen Farb-Tokens.
- Wenn für einen Container kein passendes Token vorhanden ist, fügen Sie eines hinzu (sidebar-background, sidebar-border, table-grid-line) mit einem Standardwert, der die aktuelle Darstellung reproduziert, damit sich bestehende Themes nicht ändern.
Eine kurze Überprüfung des Ergebnisses: Ein Design, bei dem beide Radiuslängen auf 0 gesetzt und alle Oberflächen-Tokens festgelegt sind, muss den „Flat“-Look ohne jegliches Anwendungs-CSS erzeugen.
Lösung
Eine Überprüfung der React-Stylesheets im Master-Zweig zeigt, dass die Hintergründe und Rahmen von Sidebar, Panel, Window, App-Leiste, Card, Tabs, Split-Panel und den Tabellenrasterlinien bereits an layer-01, layer-02 und border-subtle gebunden sind; es werden keine zusätzlichen Oberflächenfarb-Tokens benötigt. Die Lücken betrafen Radien, Schatten, Hintergründe und Verweise auf Tokens, die kein Theme definiert. Jedes Stylesheet der React-Benutzeroberfläche verwendet nun ein Token als einfache Variable (var(--name)) ohne Fallback, sodass ein im Theme fehlendes Token sichtbar wird, anstatt überdeckt zu werden.
Radius-Stufen. Die beiden Radius-Token haben eine dokumentierte Bedeutung und werden in jedem React-Stylesheet (tlReactControls.css, Code-Editor, Skript-Editor, Diagramm, WYSIWYG-Editor) konsistent angewendet:
- corner-radius — Steuerelemente: Schaltflächen, Eingabefelder, Umschalter, Zellen, kleine Chips, Griffelemente, Scrollbalken-Schieberegler.
- border-radius-02 – Oberflächen: Panels, Karten, Fenster, Menüs, Popups, Tooltips, Dashboard-Kacheln, Formulargruppen.
Eingabefelder wurden von der Oberflächenebene in die Steuerungsebene verschoben (Standardradius 0,5 rem → 0,25 rem). Kreise (50 %) und Pills (999 px) sind Formen, keine Eckenstile, und bleiben unverändert, sodass ein Badge in einem flachen Design weiterhin eine Pill bleibt.
Token für „Elevation“ und „Overlay“. Neben dem bestehenden „shadow-menu“ (Popups, Flyouts, Dropdowns, Tooltips) definiert das Standard-Theme „shadow-raised“ (erhöhte App-Leiste und Karten, eingefrorene Tabellenspalten), „shadow-dialog“ (Fenster, Drawers, Snackbars) und „overlay“ (Hintergründe für Dialoge und Seitenleisten). Ihre Standardwerte geben die bisherige Darstellung der Hauptoberfläche der jeweiligen Ebene wieder. Jeder fest codierte Schatten und jedes Gitter ist an eines dieser Elemente gebunden; Fokusringe und versetzte Schaltflächenrahmen gehören nicht zur „Elevation“ und behalten ihre Werte bei.
Hängende Token-Referenzen. var() -Referenzen auf Token, für die kein Design definiert ist (--field-01, --border-radius, --border-radius-sm, --border-subtle-00, --color-primary, --layer-accent-01, die --surface* -Eigenschaften des Diagramms / --error-color, die --tl-*- Eigenschaften des WYSIWYG-Editors) werden auf vorhandene Tokens umgeleitet; font-family-mono und heading-03-font-size werden dem Standard-Theme hinzugefügt, wobei der bisherige Fallback als Wert verwendet wird. Die Dashboard-Kachel verwendet „border-subtle“ / „layer-01“ anstelle der Alias-Token.
Test. test.com.top_logic.layout.react.theme.ThemeTokenAudit (tl-layout-react test-jar) lädt die mitgelieferte Theme-Konfiguration und ein Stylesheet und meldet jede var() -Referenz auf ein undefiniertes Token sowie jeden literalen border-radius-Wert, der nicht den Shape-Werten entspricht. „AbstractStylesheetTokenTest“ führt den Test über die Stylesheets durch, die eine Unterklasse auflistet: tl-layout-react, tl-layout-react-codeedit, tl-layout-react-chartjs, tl-model-search-react, tl-layout-react-wysiwyg und tl-react-flow-server prüfen jeweils ihre eigenen Stylesheets. Die Spezifikation ist in docs/faq/react-theme-tokens.md dokumentiert.
Demo. Die React-Demoanwendung (tl-demo-react) definiert ein flaches Theme (erweitert „default“, beide Radien 0, alle drei Schatten deaktiviert), das im Benutzermenü ausgewählt werden kann; darunter wird jedes React-Steuerelement ohne Anwendungs-CSS mit einem Radius von 0 und ohne Erhebungsschatten gerendert.