Zum Hauptinhalt springen

Theming-Implementierung

Jutro verfügt über einen Theming-Mechanismus, der für ein einheitliches Styling in der gesamten Anwendung sorgt. Während der Design-Teil über Design-Token erledigt wird, benötigt die Anwendung CSS-Variablen, um die Stildefinition zu verarbeiten. Diese CSS-Variablen sind das Ergebnis der Umwandlung von Design-Token in CSS-Variablen. Es sind auch einige zusätzliche Anpassungsoptionen verfügbar.

Sie können Design-Token auch mit benutzerdefinierten Komponenten verwenden. Sie müssen entweder neue Design-Token für diese benutzerdefinierten Komponenten definieren oder eine Zuordnungsdatei von vorhandenen Token zu neuen CSS-Variablen zur Umwandlungskonfiguration hinzufügen. Weitere Informationen zur Konfiguration benutzerdefinierter Komponenten finden Sie hier.

Note: Der alte Theming-Mechanismus, der auf der manuellen Definition der --GW--CSS-Variablenüberschreibungen basierte, wurde abgekündigt, ist aber immer noch verfügbar und wird für legacy-Komponenten unterstützt. Wechseln Sie zu einer Version der Dokumentation, die älter als 10.0 ist, um mehr Details zu diesem Mechanismus anzuzeigen, oder gehen Sie zur Legacy-Theming-Seite, um herauszufinden, wie Sie zur Verwendung von Design-Token wechseln können.

Funktionsweise des Jutro-Theming​

Die Anpassung des Jutro-Themings wird als Teil der NPM-Pakete @jutro/theme, @jutro/theme-styles und @jutro/design-tokens implementiert. In den meisten Fällen müssen Sie jedoch nicht direkt auf sie verweisen.

Normalerweise erstellen Sie Ihre Anwendung mit der Methode start() aus @jutro/app. Dieser Launcher umfasst Ihre Anwendung mit einer Root-Komponente <ThemeProvider> zur Anwendung der Themes. Wenn Sie der Methode start() keine Konfiguration zur Anpassung des Themings übergeben, wird das Standard-Theme (Enterprise) verwendet.

Das Theming auf der Implementierungsebene basiert auf CSS-Variablen mit globalem Umfang, die allgemeine CSS-Werte für verschiedene Aspekte des Erscheinungsbildes definieren. Einige gelten für einzelne Komponenten, andere für ganze Gruppen von Komponenten. Diese Variablenwerte werden während des Umwandlungsprozesses aus den definierten Design-Token zugeordnet.

Jede der von Jutro bereitgestellten Variablen wird nach einer dieser beiden Konventionen benannt (alles in Großbuchstaben):


# CSS variables generated from design tokens
--JDS-[<CATEGORY>]-[<PROPERTY>]-[<MODIFIER>]

# legacy option still applied in many components
--GW-[<OPTIONAL-COMPONENT-OR-GROUP-NAME>]-<STYLING-ASPECT>-[<OPTIONAL-VARIANT>]

Beispiele:

  • --JDS-COLOR-BACKGROUND-BRAND
  • --JDS-COLOR-BACKGROUND-ERROR-SUBTLE
  • --GW-ACCORDION-BORDER-FOCUS
  • --GW-FOCUS-ERROR-COLOR-DARK
Warning: Keine Guidewire-definierten --JDS--CSS-Variablen verwenden, um benutzerdefinierte Komponenten zu formatieren. CSS-Variablen, die aus Tokens unter dem Namensraum „jds“ generiert werden, sind NICHT Teil der API-Oberfläche und werden NICHT von der NBC-Richtlinie (Non-Breaking Changes) abgedeckt. Das bedeutet, dass alle CSS-Variablen, die mit --JDS- beginnen, ihre Benennung/Werte zwischen den Versionen ändern können, daher raten wir dringend davon ab, sie zur Gestaltung von Anwendungen zu verwenden. Verwenden Sie stattdessen eine der hier genannten Methoden.

Do's und Don'ts des Themings​

Wenn Sie die auf dieser Seite beschriebenen Leitplanken befolgen, ist Ihr Theme einfacher zu pflegen und zu aktualisieren. Nachfolgend finden Sie eine Zusammenfassung der Leitplanken:

  1. Um Jutro-Stile global anzupassen, verwenden Sie Design-Token.
  2. Verwenden Sie nur Teile von Jutro Design System, die zu unserer API-Oberfläche gehören
  3. Ändern Sie keine der generierten CSS-Variablendefinitionen manuell.
  4. Verwenden Sie keine --JDS--CSS-Variablen, um benutzerdefinierte Komponenten zu gestalten, sondern befolgen Sie die empfohlenen Ansätze.
  5. Verlassen Sie sich bei der Definition der Stile nicht auf interne Implementierungsdetails der Komponenten, einschließlich CSS-Variablen und Klassennamen.
  6. Verwenden Sie niemals Brute-Force- oder Hacking-Stile, indem Sie komplexe Selektoren schreiben, um Komponenten auf einer Seite anzupassen. Verwenden Sie zum Beispiel nicht „die erste Schaltfläche im Formular“.

Anpassung der Jutro-Stile und Erhaltung der Aktualisierbarkeit​

Der offiziell unterstützte Weg zur Anpassung von Jutro-Komponenten ist die Verwendung von Design-Token und das Ergebnis ihrer Umwandlung in CSS-Variablen.

Wenn sich infolge einer Komponentenuntersuchung die --JDS--CSS-Variablen ändern, die von einer Komponente verwendet werden, nimmt Guidewire die erforderlichen Änderungen in die Konfiguration des Prozesses der Umwandlung im Design-Token zu CSS-Variablen auf, um die Aktualisierung auf die neuere Version ohne negative Auswirkungen oder manuelles Eingreifen des Verbrauchers zu ermöglichen.

Einrichten eines neuen Themes für Ihre Anwendung​

Die beste Möglichkeit, Stile global zu überschreiben, ist die Erstellung eines benutzerdefinierten Designs. Standardmäßig verwenden Jutro-Anwendungen das Theme „Enterprise“. Um zu einem anderen Theme zu wechseln, gehen Sie wie folgt vor.

  1. Bereiten Sie die Design-Token-Konfiguration für Ihr benutzerdefiniertes Theme vor – der Vorgang wird auf dieser Seite beschrieben
  2. Übergeben Sie das richtige Theme, damit start in ./src/startApp.js funktioniert:
import themesConfig from './.themesConfig.json';

start(Jutro, {
        ...
        themeConfig: themesConfig.sampleTheme,
    });

Weitere Einzelheiten finden Sie auf den Dokumentationsseiten zu Design-Token.

Zugriff auf externe Themes​

Abschließend, nach allen Transformationen, wird Ihre Theme-Definition in der tokenOverrides.css-Datei (oder einer Datei mit einem anderen Namen) gespeichert, die die CSS-Variablenwerte enthält, die aus den Design-Token zugeordnet werden. Da der Link zu dieser Datei aus der Theme-Konfiguration übernommen und als href-Wert in einem HTML-<link>-Tag verwendet wird, können Sie die CSS-Datei auf einem anderen Server ablegen. In diesem Fall müssen Sie in Ihrem .themesConfig.json nicht input-path angeben, da Sie keine Transformationen lokal ausführen. Es reicht aus, den Link zu Ihrer tokenOverrides.css-Datei als Wert von output-file-name hinzuzufügen.

{
  "sampleTheme": {
    "name": "sampleTheme",
    "tokens": {
      "output-file-name": "https://example.com/theme/tokenOverrides.css"
    }
  }
}

Damit können Sie die folgenden Szenarien realisieren:

  1. Gemeinsame Nutzung des benutzerdefinierten Themes durch verschiedene Anwendungen.
  2. Bereitstellung von neuen Themes unabhängig von der Anwendung.

Beachten Sie jedoch, dass die Dateien vom Client-Browser aus verfügbar sein müssen und dass das Caching möglicherweise verhindert, dass der Client-Browser aktualisierte Stile sofort anzeigt.

Bitte beachten Sie auch, dass Remote-Dateien während des Upgrades nicht automatisch migriert werden.

Anpassen der Stile einer einzelnen Instanz einer Jutro-Komponente​

Sie können eine className-Eigenschaft verwenden, um das Erscheinungsbild einer einzelnen Instanz einer Jutro-Komponente anzupassen.

  1. Bereiten Sie Ihre eigene CSS-Klasse vor:
.myCustomButtonStyles {
  background: red;
}
  1. Übergeben Sie sie mit Hilfe der className-Eigenschaft an die Komponente:
import { Button } from '@jutro/component';
import styles from './myStyles.module.scss';

const MyForm = () => {
  // this instance of button is going to have use our red background instead of the default one
  return <Button className={styles.myCustomButtonStyles}>Get insured!</Button>;
};

Versuchen Sie nicht, die Standardstile der Jutro-Komponenten zu überschreiben, indem Sie die Namen der von Jutro bereitgestellten CSS-Klassen extrahieren und sie direkt in Ihren Stylesheets überschreiben. Wenn Sie direkt auf eine Jutro-Klasse verweisen, funktionieren Ihre Anpassungen nicht mehr, wenn Jutro zu einem anderen Hashing-Mechanismus wechselt oder die Klasse umbenennt. Klassennamen sind nicht Teil Jutro-API-Oberfläche und ihre Namen können sich von Release zu Release ändern.

.jut__Button__button {
  //this is WRONG, please do not do this
  background: red;
}

Schriftarten, Bilder, statische Dateien​

Alle statischen Ressourcen befinden sich in der Regel in Ihrem src/assets-Ordner. Sie können sie wie folgt referenzieren:

  • aus HTML-Schablonen, z. B. mit dem Platzhalterpräfix %PUBLIC_URL%:

    <img src="%PUBLIC_URL%/<path-to-the-image-under-src-assets>" />

  • aus dem JS-Code (z. B. als Teil des render() der Komponente), mit der Umgebungsvariable PUBLIC_URL:

    render() {
        return (
            <img src={`${process.env.PUBLIC_URL}/<path-to-the-image-under-src-assets>`} />
        );
    }

  • aus CSS-Dateien entweder mit dem absoluten oder relativen Pfad – in diesem Fall sucht der Browser nach den Dateien, die relativ zu der CSS-Datei sind, in welcher der Link angegeben ist

Hinzufügen von benutzerdefinierten Schriftarten​

Um eine benutzerdefinierte Schriftart anzuwenden, legen Sie sie in Ihrem src/assets/fonts-Ordner ab und schließen sie in Ihre SCSS-Datei ein.

@font-face {
  font-family: Acme;
  src: url(./assets/fonts/Acme-Regular.ttf);
}

Sie können die Schriftart auf jede Komponente oder Klasse anwenden. Wenn Sie eine Theme-Schriftart ersetzen möchten, überschreiben Sie das entsprechende Design-Token.

Schriftarten in Webpack 5​

Wenn Sie zu Webpack 5 wechseln, sollte Ihre Theme.scss-Datei nur noch Schriftarten speichern, wie unten gezeigt:

Theme.scss
$fonts-root: '~@jutro/theme/assets/fonts';

// ------------------------------------
//   GROUNDED CSS MODULES
// ------------------------------------
@import '~@jutro/theme/assets/fonts/fonts';

Es wird nicht empfohlen, weitere Informationen zu Ihrer Theme.scss-Datei hinzuzufügen.

Verarbeitung von Theme-Unterschieden über Breakpoints​

Jutro umfasst keine benutzerdefinierte Funktion zur Verarbeitung von Theme-Unterschieden über Breakpoints. Sie können jedoch integrierte CSS-Mechanismen wie Medienabfragen verwenden, wenn dieses Verhalten für Ihre Anwendung erforderlich ist.

Der folgende Abschnitt zeigt Ihnen eine Möglichkeit auf, wie Sie dies umsetzen können. Je nach Art Ihrer Anwendung ist jedoch möglicherweise ein anderer Ansatz erforderlich.

Verwenden von CSS-Medienabfragen zur Verarbeitung von Theme-Unterschieden über Breakpoints​

Bei diesem Ansatz verwenden Sie CSS-Medienabfragen, um zu ermitteln, welche Gruppe von Design-Token aktiv ist, abhängig von der Breite des sichtbaren Bildschirmbereichs und davon, ob es auf einem Bildschirmgerät angezeigt wird. Ihr Anwendungsfall erfordert möglicherweise die Definition mehrerer Szenarien, aber dieses Beispiel deckt zwei ab:

  • screen and (min-width: 769px): aktiv bei der Anzeige auf einem Bildschirmgerät und bei einer Breite von mindestens 769 Pixeln.
  • screen and (max-width: 768px): aktiv bei der Anzeige auf einem Bildschirmgerät und mit einer Breite von 768 Pixeln oder weniger.

Eine kurze Zusammenfassung der durchzuführenden Schritte:

  1. Definieren Sie ein Theme mithilfe von Design-Token für jedes Szenario.
  2. Generieren Sie die CSS Dateien für Ihre Themes mithilfe der Jutro CLI.
  3. Erstellen Sie manuell eine CSS-Datei, die die generierten CSS-Dateien importiert und mithilfe von Medienabfragen festlegt, welche davon aktiv ist.
  4. Erstellen Sie ein Theme, das die manuell erstellte CSS-Datei verwendet.

Überlegungen zur Verwendung dieses Ansatzes​

Bei diesem Ansatz werden die Änderungen bei jeder Neugenerierung der Themes automatisch im neuen, kombinierten Wrapping-Theme berücksichtigt, ohne dass weitere Schritte erforderlich sind.

  • Das Bundle enthält alle Themes, was sich auf die Netzwerknutzung und die Ladezeiten auswirken kann.
  • Auch wenn die manuelle Erstellung eines Themes erforderlich ist, handelt es sich hierbei um eine einmalige Aktion. Wenn Sie Änderungen an den untergeordneten Themes vornehmen, können Sie den Befehl jutro generate:themes einfach erneut ausführen und müssen Ihre manuell erstellte Datei nicht erneut aktualisieren.
  • Diese Empfehlung basiert auf dem Fall, dass beide importierten Theme-Definitionen vollständige Themes enthalten und nicht eine davon nur eine teilweise Überschreibung bestimmter Variablen oder Werte darstellt. Aus diesem Grund verwenden beide Importe die width-Bedingung. Dies bietet folgende Vorteile:
    • Es ist nur ein Theme für die CSS-Auswertung aktiv.
    • Keine Kaskadenkonflikte (z. B. wird ein !important im Basis-Theme auf den in der Medienüberschreibung festgelegten Wert angewendet).
    • Vollständige Trennung zwischen den Themes.
    • Es besteht keine Möglichkeit, dass das Basis-Theme vor dem reaktiven Theme angewendet wird, wenn Benutzer langsame oder unzuverlässige Netzwerkverbindungen haben.

Anweisungen zur Anwendung dieses Ansatzes in einer Jutro-Anwendung​

  1. Definieren Sie Ihre Themes mithilfe von Design-Token und importieren Sie diese wie gewohnt in die .themesConfig.json-Datei. Weitere Details finden Sie in der Dokumentation zur Transformation in CSS-Variablen.
  2. Führen Sie den jutro generate:themes-Befehl zur Erstellung der Dateien mit den CSS-Variablen für Ihre Themes wie gewohnt aus. Weitere Informationen zu diesem Befehl finden Sie in der CLI-Dokumentation.
  3. Definieren Sie manuell ein neues Theme in Ihrem styles-Verzeichnis, ohne Token, das jedes Breakpoint-Theme durch Importe in einer Datei mit dem Namen Combined-Themes/combined-themes-design-tokens.css kombiniert. Wenn Ihre Themes zum Beispiel ConsumerDesktop und ConsumerTablet heißen, fügen Sie den folgenden Text hinzu:
styles/Combined-Themes/combined-themes-design-tokens.css
@import url('../Consumer-Desktop/consumer-desktop-design-tokens.css') screen and
  (min-width: 769px);
@import url('../Consumer-Tablet/consumer-tablet-design-tokens.css') screen and
  (max-width: 768px);
  1. Fügen Sie das kombinierte Theme zu .themesConfig.json als Variablenüberschreibung hinzu.
  "CombinedThemes": {
  "name": "CombinedThemes",
  "variableOverrides":"styles/Combined-Themes/combined-themes-design-tokens.css"
}
Note:

Sie müssen danach nicht wie in Schritt 2 jutro generate:themes erneut ausführen, da Sie die CSS-Datei, die dieses Theme verwendet, in Schritt 3 manuell erstellt haben.

  1. Aktualisieren Sie in Ihrer startApp-Datei das themeConfig-Argument der start-Funktion, um Ihr neues Theme CombinedThemes zu verwenden:
start(Jutro, {
  ...
  themeConfig: themesConfig.CombinedThemes,
  ...
});

Eine detaillierte Demonstration dieses Prozesses wird in der Lernmission zum Hinzufügen von Breakpoint-Themes beschrieben.