enhancement
major
minor
major
minor
major
#29546
TL-Ansichten: Farben für Aufzählungsliterale und Klassifikatorobjekte, die als „Pills“ dargestellt werden, sowie ein Fortschrittsbalken
Problem
1. Statusähnliche Werte sehen aus wie jeder andere Text
Ein Ticketstatus, eine Priorität, ein Schweregrad, eine Bezeichnung: Werte, deren Bedeutung ein Benutzer in jedem Issue-Tracker anhand der Farbe erkennt. In der Ansichtsebene (com.top_logic.layout.view) wurde ein solcher Wert überall, wo er auftrat, als reiner Text angezeigt: der schreibgeschützte Wert von ReactDropdownSelectControl in Tabellenzellen und Formularfeldern im Ansichtsmodus, ein ReactResourceCellControl, ein <text>. Das Modell hatte keine Möglichkeit, einem Aufzählungsliteral eine Farbe zuzuweisen oder die Farbe eines Objekts anhand seines Zustands zu berechnen, und die React-Steuerelemente verfügten über keine „Pill“-Darstellung für einen Wert, der eine Farbe enthält.
2. Der Fortschritt wurde nicht angezeigt
„7 von 12 geplanten Tickets abgeschlossen“ eines Meilensteins, der Abschluss eines Projekts, der Anteil einer Quote: ein Zahlenpaar oder ein Bruch, dargestellt als Balken mit einer Beschriftung. Kein React-Steuerelement zeigte dies an.
3. Eine Farbe wurde als Hex-Zeichenkette eingegeben
Eine Konfigurationseigenschaft vom Typ `java.awt.Color ` (die Farbe einer Anmerkung, einer Design-Einstellung, eines Standardwerts) wurde als Text bearbeitet: #04a38d von Hand eingegeben, obwohl ein Farbwähler vorhanden ist.
Lösung
Eine Farbe für Werte, dargestellt als Pille
- Modell (com.top_logic.model.annotate.ui, tl-core): <color value="#04a38d"/> oder <color token="support-success"/> in einem Aufzählungsliteral (TLColor) benennt die Farbe als Literal oder als Design-Token des UI-Themas, sodass ein Token dem aktiven Thema folgt. Ein Typ, dessen Instanzen eine Farbe haben, annotiert den Algorithmus, der diese berechnet: <dynamic-color> (TLDynamicColor, von Spezialisierungen geerbt) enthält einen ValueColorProvider, der in der Form <dynamic-icon> und <label> für Symbole und Beschriftungen verwendet wird. tl-model-search definiert diesen Algorithmus als TL-Script-Funktion über dem Objekt: <dynamic-color><color-by-expression color="t -> $t.get(`Ticket#status)"/></dynamic-color>` (ColorByExpression); ist ein Farbwert als Ergebnis die Farbe selbst, wird ein Aufzählungsliteral durch seine eigene <color> eingefärbt, bei jedem anderen Ergebnis bleibt das Objekt ungefärbt. AnnotationValueColorProvider.INSTANCE.colorOf(value) liefert den ValueColor eines Klassifikators, eines Objekts (über den pro Typ in TLModelOperations.getColorProvider zwischengespeicherten Provider) oder eines Farbwerts und null für alles andere; ValueColor.cssValue() ist das CSS, mit dem dieser angewendet wird.
- Darstellung. Überall dort, wo ein Modellwert mit einer Farbe schreibgeschützt angezeigt wird, wird er als „Pill“ dargestellt: die Beschriftung auf einem Hintergrund, der in der Farbe getönt ist, mit gut lesbarem Text, der mit color-mix() unter Berücksichtigung der Oberflächen- und Text-Tokens des Themes zusammengesetzt wird, sodass er sowohl auf hellen als auch auf dunklen Themes gut lesbar ist. Der Server benennt die Farbe in einem Wire-Feld (ReactValueColor.COLOR), der Client rendert sie über eine Komponente (TLPill) mit der Farbe als Inline-Custom-Property, ohne separate Klasse pro Farbe. Anwendungsbereiche: der schreibgeschützte Wert, die Optionen und die ausgewählten Chips von ReactDropdownSelectControl (Referenz- und Aufzählungsattribute in <table> -Zellen und <form> -Feldern), ReactResourceCellControl sowie <text> über einem farbigen Kanalwert. Ein <text> folgt auf einen neuen Kanalwert und eine Änderung des Objekts auf dem Kanal (über den gemeinsamen ChannelObjectObserver, #29533), sodass die Pille eines Objekts, dessen Zustand bearbeitet wurde, ihre Farbe ändert, ohne erneut ausgewählt zu werden.
Die Farbauswahl für jede Farbeigenschaft
Eine Konfigurationseigenschaft vom Typ `java.awt.Color ` wird mit der Farbauswahl bearbeitet, und zwar typbasiert und ohne eigenschaftsspezifische Annotation: dem deklarativen Formular-Editor (ValueEditor installiert ColorControlProvider) und dem React-Konfigurationseditor (ConfigControlService ordnet java.awt.Color dem ColorInputConfigProvider zu, der das ReactColorInputControl erstellt). Eine explizite @ControlProvider- bzw. @ConfigControl -Annotation hat jedoch weiterhin Vorrang. Der Wert einer <color> -Annotation wird somit aus einer Palette im Modell-Editor ausgewählt.
Ein Fortschrittsbalken
- ReactProgressControl zeigt einen auf den Bereich 0..1 begrenzten Bruch als Balken mit optionaler Beschriftung an, dessen Farbe sich nach den Theme-Tokens richtet.
- <progress> (ProgressElement): <progress input="…" fraction="x -> …"/> oder <progress input="…" done="x -> …" total="x -> …"/> (sich gegenseitig ausschließend, andernfalls ein Konfigurationsfehler; zwei Zählwerte beschriften den Balken mit 3 / 7, sofern label="x -> …" nichts anderes angibt), der Eingabekanal ist optional; der Balken folgt einem neuen Kanalwert, einer Änderung des darauf liegenden Objekts sowie Änderungen der beobachteten Typen über den gemeinsamen ChannelObjectObserver (#29533).
- Als Tabellenzelle gibt ein CellRenderer „CellContent.Raw“ zurück, wobei eine CellControlFactory ein „ReactProgressControl“ erstellt – dies ist der bestehende Weg für maßgeschneiderte Zellen; die FAQ dokumentiert dies.
Dokumentation und Demo
docs/faq/react-view-layer.md, Abschnitte „Farbige Werte“ und „Fortschritt“. com.top_logic.demo.react, Ansicht „Objektliste“: Die Literale für den Ticketstatus tragen <color token> -Annotationen und werden in der Statusspalte, im Detailformular und im Dropdown-Menü während der Bearbeitung als Pillen angezeigt; der Ticket -Typ übernimmt seine Farbe über <dynamic-color> aus seinem Status, und ein <text input="ticket"/> zeigt das ausgewählte Ticket als Pille an, die auf „Schließen“ und „Wieder öffnen“ folgt; ein <progress> oberhalb der Tabellen zeigt die Anzahl der geschlossenen Tickets an und folgt den Befehlen „Schließen“, „Wieder öffnen“ und „Erstellen“. Tests: TestValueColorProvider, TestEditorFactory (tl-core), TestColorByExpression (tl-model-search), TestConfigControlService (tl-layout-configedit), TestReactValueColor, TestReactProgressControl (tl-layout-react), TestProgressElement, TestTextElementObservation (tl-layout-view).