Zum Hauptinhalt springen

API-Oberfläche

Einführung​

Aufgrund der Besonderheiten der Frontend-Entwicklung sind einige Details der Implementierung oder ihres Ergebnisses für Nutzer sichtbar. Allerdings sind nicht alle Teil der API-Oberfläche.

In diesem Dokument werden die Teile von Jutro Digital Platform (JDP) beschrieben, die Gegenstand des Vertrags zwischen JDP und den Kunden sind. Diese Teile unterliegen den Richtlinien für Non-Breaking Changes, die sicherstellen, dass Nebenversionen keine nicht abwärtskompatiblen Änderungen an ihnen vornehmen.

Die seltene Ausnahme von dieser Regel sind notwendige Sicherheitskorrekturen oder Fehlerbehebungen.

Warning: Die Verwendung eines Nicht-API-Elements kann zu Problemen bei der Wartung und Aktualisierung von Anwendungen führen.

Breaking Changes (nicht abwärtskompatible Änderungen) an Aspekten, die keine APIs sind, können in Nebenversionen erfolgen, ohne dass dies in den Versionshinweisen angegeben wird.

Es wird dringend empfohlen, diese Aspekte nicht im Produktionscode zu verwenden.

Jutro Design System und API für UI-Bibliotheken​

Die folgenden Aspekte sind Bestandteil des Vertrags zu Jutro Design System und UI-Bibliotheken:

Paketnamen und öffentliche Strukturen oder Signaturen von Paketen und Modulen​

Die Namen der JDP-Pakete und ihre öffentlichen Exporte sowie die Signaturen und Typen der verschiedenen Funktionen sind Teil des Vertrags.

Warning: Nur die Direktexporte von den aufgeführten Einstiegspunkten gelten als Vertragsbestandteil. Weitere Informationen finden Sie unter Pakete im Überblick.

Beispiel: Folgendes ist kein Direktexport von einem definierten Einstiegspunkt (@jutro/components), daher auch nicht Teil des Vertrags für JDP-Bibliotheken:

import { intlMessageShape } from '@jutro/components/types/types';

Ein gültiger Import von diesem Einstiegspunkt in diesem Fall ist beispielsweise:

import { Button } from '@jutro/components';

Beispiele:

  • Der Paketname, der Name der MicroFrontend-Komponente, der zugehörige Importpfad und die zugehörigen Eigenschaften sind Teil des Vertrags.
import { MicroFrontend } from '@jutro/micro-frontends'

<MicroFrontend
    src='claimMicroFrontend@http://localhost:3001'
    jutro = {
        mode: 'isolated'
        router: {
            basename: '/welcome',
        }
    ...
    }
>

Die Eigenschaft jutro kann neue Eigenschaften hinzufügen oder die zugehörigen zulässigen Werte erweitern, wobei die Unterstützung für die bestehenden Eigenschaften beibehalten wird.

  • Der Hook useAuth aus dem Paket @jutro/auth gibt die folgenden Attribute zurück, die nicht geändert werden (sie können jedoch erweitert werden):
{
  isAuthenticated: boolean;
  isPending: boolean;
  userInfo: OidcUserInfo | null;
  error?: Error;
  login: AuthLogin;
  logout: AuthLogout;
  accessToken: string | null;
  idToken: string | null;
}
Warning: Gelegentlich sind experimentelle Jutro-Pakete verfügbar. Dabei wird eine Namenskonvention wie @jutro/experimental-* verwendet. Diese Pakete gelten nicht als Teil des JDP-Vertrags und können sich ändern, da sie sich in der aktiven Entwicklung befinden.

Eigenschaften von React-Komponenten: zugehörige Namen, Typen und Standardwerte​

Die Komponentennamen und der Satz der zulässigen Eigenschaften sind Teil des Vertrags. Weitere Details und Optionen zur benutzerdefinierten Anpassung finden Sie unter Komponenten und Escape Hatches.

Beispiel: Wenn eine optionale Eigenschaft als erforderlich festgelegt wird, gilt dies als Breaking Change. Das Festlegen einer bisher erforderlichen Eigenschaft als optional kann jedoch in einer Nebenversion erfolgen, da dies keine Auswirkungen auf bestehende Kunden hat.

Visuelle Aspekte und Verhalten von React-Komponenten​

Das Verhalten der Komponenten und die visuelle Darstellung sind Teil des Vertrags und müssen stabil bleiben.

Beispiele für Verhalten:

  • Wann sollte ein Tooltip-Element standardmäßig geschlossen werden?
  • Standardstatus (erweitert/reduziert) von AccordionCard-Elementen
  • Ereignisse, die bei einer Benutzerinteraktion ausgelöst werden: Wenn das Ereignis onChange ausgelöst wird, während der Benutzer mit einem Eingabeelement interagiert

Die Art und Weise, wie die Komponente (und jede ihrer Varianten) standardmäßig angezeigt wird, bleibt stabil und jede Änderung ist abwärtskompatibel. Komponenten umfassen jedoch auch Optionen zur benutzerdefinierten Anpassung, mit denen Benutzer diese Standardwerte überschreiben können (z. B. Design-Token).

Die verfügbaren Optionen zur benutzerdefinierten Anpassung sind Teil des Vertrags, die angewendeten Werte sind hingegen vom Kunden abhängig. Weitere Informationen finden Sie im Abschnitt Themes: Design-Token weiter unten. Auf der Seite Escape Hatches werden außerdem andere Alternativen zur kundenspezifischen Anpassung beschrieben.

Accessibility Tree der React-Komponenten​

Barrierefreiheit ist einer der Hauptaspekte von Jutro Design System. Der Accessibility Tree der einzelnen Komponenten ist Teil des Vertrags.

Warning: Die Anforderungen an die Barrierefreiheit der Komponenten werden kontinuierlich überprüft. Mangelnde Konformität in diesem Bereich wird als Fehler betrachtet. Die entsprechende Behebung kann Änderungen am Accessibility Tree erfordern, z. B. Hinzufügen, Entfernen oder Ändern der ARIA-Rolle eines Elements.

Themes: Design-Token​

Design-Token definieren die verschiedenen verfügbaren Optionen zur benutzerdefinierten Anpassung und wie sie auf die verschiedenen Komponenten angewendet werden. Während sich die Werte der Design-Token weiterentwickeln können, bleiben 2 Bestandteile in der React-Komponentenbibliothek stabil und abwärtskompatibel:

  1. Namen von Design-Token
  2. Anwendung der Design-Token auf die einzelnen Komponenten
Note: Token auf Komponentenebene stellen die Art und Weise dar, wie Design-Token auf die Komponenten angewendet werden. Sie definieren die Optionen zur benutzerdefinierten Anpassung, die in den einzelnen Komponenten unterstützt werden. Es ist möglich, neue Optionen zur benutzerdefinierten Anpassung einzuführen, vorhandene Optionen müssen jedoch weiterhin verfügbar sein.

Weitere Einzelheiten finden Sie in der Dokumentation zu Design-Token.

Übersetzungsschlüssel​

JDP-Bibliotheken, einschließlich der Jutro Design System-Komponenten, enthalten Standardmeldungen, z. B. die Meldung, die angezeigt wird, wenn in einem Combobox-Element keine Option verfügbar ist. Sie sind so definiert, dass sie internationalisiert werden können, und umfassen einige Standardwerte.

 noResults: {
        id: 'jutro-components.fields.Combobox.noResults',
        defaultMessage: 'No results.',
    },

Die Meldungsschlüssel (id) sind Bestandteil des Vertrags.

Unterstützung für wichtige Abhängigkeiten von Drittanbietern​

Die Unterstützung für Node.js-, React- oder Webpack-Versionen wird beibehalten, aber die Unterstützung für neue Versionen kann hinzugefügt werden.

Note: Von Anbietern festgelegte EoL- oder EoS-Daten müssen berücksichtigt werden, insbesondere in Hinblick auf die Sicherheit.

Außerdem sind für neue JDP-Funktionen eventuell kundenseitige Upgrades auf neuere Abhängigkeitsversionen erforderlich.

Konfiguration: Dateien, Variablennamen, Standardwerte und Typen​

Die vorhandenen Konfigurationsvariablen, zulässigen Werte und zugehörigen Standardwerte müssen verfügbar und unverändert bleiben. Es ist möglich, die verfügbaren Optionen zu erweitern oder neue Alternativen einzuführen.

Beispiel: JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT ist enthalten und unterstützt true / false, wobei false der Standardwert ist.

Kompatibilität der Verschachtelung von Micro Frontends​

Die MicroFrontend-Komponente und das Microfrontend SDK definieren eine eindeutige API und enthalten eine Wrapping-Ebene, die das Einbetten von Micro Frontends unabhängig von der Nebenversion der JDP-Bibliotheken ermöglicht, die in der Shell und den Micro Frontend-Anwendungen verwendet werden.

Weitere Informationen finden Sie in der Dokumentation zu Micro Frontends, einschließlich der API-Referenz.

CLI-Befehle: Verfügbarkeit, Signatur und Zweck​

Die Liste der verfügbaren Befehle in den bereitgestellten CLIs sowie die verschiedenen Konfigurationsoptionen sind Teil des Vertrags.

Warning: Die Ergebnisse der Ausführung von CLI-Befehlen können geändert und so an die neuesten Versionen, Verfahren und Funktionsanforderungen angepasst werden.

Konfiguration der bereitgestellten Entwicklertools​

Die Skripte zum Erstellen der Anwendung, Linting-Optionen und andere verbundene Funktionen bleiben abwärtskompatibel.

Warning: Die Skripte und Konfigurationen bleiben zwar weiterhin verfügbar, müssen jedoch möglicherweise aufgrund sich entwickelnder Produkt- und Kundenanforderungen geändert oder angepasst werden, was zu einer anderen Ausgabe der Skripte führen kann.

Aspekte, die nicht Teil der API sind​

Im Folgenden sind Aspekte aufgeführt, die nicht Bestandteil des JDP-Vertrags sind, selbst wenn sie verfügbar sind:

  • Alle Exporte unter den internal-Pfaden oder alle Einstiegspunkte, die nicht auf der Seite Pakete im Überblick aufgeführt sind.
  • Alle Exporte aus experimental-*-Pfaden.
  • HTML-Markup der Komponenten.
  • CSS-Klassennamen.
  • CSS-Variablen.
  • CSS-Mixins.
  • Designmuster und -beispiele, die normalerweise in der Dokumentation enthalten sind.
  • Meldungen für Entwickler und Meldungen von Build-Tools, z. B. Fehlertexte und Warnungen.
  • Laufzeitfehler: Fehlerauslösung und zugehörige Fehlercodes (spezifische Meldungen und zusätzliche Eigenschaften sind nicht Teil der API).
  • Vorlagen.

Digital SDK​

Siehe Dokumentation zum Digital SDK API-Vertrag .

Digital SDK in Jutro​

Beim Generieren des Digital SDK mit der Jutro Platform CLI gelten die gleichen Verträge wie in der Dokumentation zum Digital SDK .

Für die Initialisierung und Konfiguration stehen jedoch einige Jutro-spezifische Funktionen zur Verfügung, die auch Teil des JDP-Vertrags sind.

Digital SDK UI Extensions​

Die Digital SDK UI Extensions sind eine Reihe generierter Abstraktionen, die das Digital SDK erweitern, damit es in React-basierten Anwendungen effizienter funktioniert. Für diese Erweiterungen gibt es eigene Verträge, die im Digital SDK UI Extensions API-Vertrag definiert sind.

Infrastruktur von Jutro Digital Platform​

Die Infrastruktur von Jutro Digital Platform wird als Service bereitgestellt. Mit dem Ziel, Störungen für die Kunden zu reduzieren, gelten jedoch die folgenden Aspekte als Vertragsbestandteil:

Automatisch generiertes Format der Bereitstellungs-URL​

Das automatisch generierte Format der Bereitstellungs-URLs, wenn Bereitstellungen ohne Verwendung benutzerdefinierter Domänen erstellt werden.