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 JDP-Komponenten aufgeführt und beschrieben, aus denen sich der Vertrag zwischen JDP und seinen Kunden zusammensetzt. 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, sich in keinem Produktionscode auf diese Aspekte zu verlassen.

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

Die folgenden Aspekte gelten als Bestandteil des Vertrag über das Jutro Design System und die 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 wäre kein Direktexport von einem definierten Einstiegspunkt (@jutro/components), daher ist es nicht Teil des JDP-Bibliotheksvertrags:

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

Ein gültiger Import von diesem Einstiegspunkt in diesem Fall wäre 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 könnte neue Eigenschaften hinzufügen oder die zugehörigen akzeptierten 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, und sie werden nicht geändert (sie könnten erweitert werden):
{
  isAuthenticated: boolean;
  isPending: boolean;
  userInfo: OidcUserInfo | null;
  error?: Error;
  login: AuthLogin;
  logout: AuthLogout;
  accessToken: string | null;
  idToken: string | null;
}

React-Komponenteneigenschaften: ihre Namen, Typen und Standardwerte​

Die Komponentennamen und der Satz der akzeptierten Eigenschaften sind Teil des Vertrags. Weitere Details und Optionen zur benutzerdefinierten Anpassung finden Sie in der Komponenten-Dokumentation und in den Escape Hatches.

Beispiel: Wenn eine optionale Eigenschaft obligatorisch wird, gilt dies als Breaking Change. Das Festlegen einer bisher obligatorischen Eigenschaft als optional könnte jedoch in einer Nebenversion erfolgen, da dies keine Auswirkungen auf bestehende Kunden hätte.

Visuelle Aspekte und Verhalten von Komponenten​

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

Beispiele für Verhaltensweisen:

  • Wann sollte ein Tooltip standardmäßig geschlossen werden?
  • Der Standardstatus (aus-/eingeklappt) 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 bieten jedoch auch Optionen zur benutzerdefinierten Anpassung, mit denen die 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 auch andere Alternativen zur kundenspezifischen Anpassung beschrieben.

Accessibility Tree der React-Komponenten​

Barrierefreiheit ist einer der Hauptaspekte des Jutro Design Systems, und 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, und seine Behebung kann z. B. Änderungen am Accessibility Tree erfordern. Hinzufügen, Entfernen oder Ändern einer ARIA-Elementrolle.

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 Teile in der React-Komponentenbibliothek stabil und abwärtskompatibel:

  1. Namen von Design-Token
  2. So werden die Design-Token auf die einzelnen Komponenten angewendet
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 von den einzelnen Komponenten unterstützt werden. Es ist möglich, neue Optionen zur benutzerdefinierten Anpassung einzuführen, bestehende müssen jedoch weiterhin verfügbar sein.

Weitere Einzelheiten finden Sie in der Dokumentation zu Design-Token

Übersetzungsschlüssel​

JDP-Bibliotheken, einschließlich der Komponenten des Jutro Design Systems, stellen beispielsweise Standardnachrichten bereit. Die Meldung, die angezeigt wird, wenn in einer Combobox keine Option verfügbar ist. Diese sind so definiert, dass sie internationalisiert werden können, und stellen einige Standardwerte bereit.

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

Die Nachrichtenschlü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 könnte hinzugefügt werden.

Note: Von Anbietern festgelegte EoL oder EoS 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, akzeptierten Werte und zugehörigen Standardwerte müssen verfügbar und unverändert bleiben. Die verfügbaren Optionen können erweitert oder neue Alternativen eingeführt werden.

Beispiel: JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT wird bereitgestellt und akzeptiert true / false, wobei false der Standardwert ist.

Kompatibilität der Verschachtelung von Micro-Frontends​

Die Komponente MicroFrontend und das Micro-Frontend-SDK definieren eine eindeutige API und enthalten eine Wrapping-Layer, die das Einbetten von Micro-Frontends unabhängig von der Nebenversion der JDP-Bibliotheken ermöglicht, die von 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 werden, um sie an die neuesten Versionen, Praktiken und Funktionsanforderungen anzupassen.

Konfiguration der bereitgestellten Entwicklertools​

Die Skripte zum Erstellen der Anwendung, von Linting-Optionen und anderen verwandten 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 dieser 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 dem Pfad internal oder alle Einstiegspunkte, die nicht im Abschnitt Pakete im Überblick aufgeführt sind.
  • HTML-Markup der Komponenten
  • CSS-Klassennamen
  • CSS-Variablen
  • CSS-Mixins
  • Designmuster und -beispiele, die normalerweise in der Dokumentation enthalten sind
  • Meldungen von Entwickler- und 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 auch das Vertragsunterlagen über die API des Digital SDK .

Digital SDK in Jutro​

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

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 Vertrag über die API der Digital SDK UI Extensions definiert sind.

Infrastruktur der Jutro Digital Platform​

Die Infrastruktur der 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.