Native UI zum Theme hinzufügen

Sie verwenden bereits @rdlabo/ionic-theme-ios27? Ergänzen Sie native Bedienelemente unter iOS und behalten Sie Theme-Stile, Web-Inhalte und Routing. Nicht unterstützte Bedienelemente, Browser und Android behalten ihre Web-Darstellung.

Beginnen Sie mit der Theme-Einrichtung, falls das Theme noch nicht konfiguriert ist. Für eine andere Web-Darstellung folgen Sie stattdessen der Native UI-Einrichtung.

Unter Funktionsweise der Projektion erfahren Sie, wie native Bedienelemente mit Ihrem Web-DOM und Ihren Handlern verbunden bleiben.

1. Das native Plugin installieren

Diese Anleitung setzt eine Capacitor-8-Anwendung mit einem iOS-Projekt voraus. Reine Web-Nutzer des Themes benötigen weiterhin kein Capacitor; native iOS-Bedienelemente erfordern jedoch zunächst dieses native Projekt. Die unterstützten Versionen von Ionic, iOS und Xcode finden Sie unter Native UI-Anforderungen.

Aktualisieren Sie Theme und Native UI gemeinsam, damit ihre Versionen übereinstimmen, und installieren Sie Foldable als separate Anwendungsabhängigkeit:

npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui @erkamyaman/capacitor-foldable

Behalten Sie Ihre bestehenden Theme-Stylesheets. Capacitors standardmäßige Plugin-Erkennung benötigt eine direkte Abhängigkeit; die allein über das Theme installierte Kopie registriert das native Plugin nicht.

2. Native Bedienelemente aktivieren

Aktivieren Sie die Shell einmal beim Anwendungsstart, nachdem ion-app eingebunden wurde:

import { enableNativeUI } from '@rdlabo/capacitor-native-ui';

const shell = await enableNativeUI();

Rufen Sie beim Auflösen der verantwortlichen Anwendungsinstanz await shell.destroy() auf; erzeugen Sie keine Shell pro Seite. Verbinden Sie Start und Bereinigung anhand der App-Root-Beispiele für Angular, React oder Vue.

Behalten Sie navAnimation: iosTransitionAnimation aus dem Theme-Paket. Diese Animation koordiniert native Bedienelemente bereits bei Seitenübergängen und Zurückgesten; umschließen Sie sie nicht erneut. Für eigene Animationen folgen Sie den Anweisungen zum Übergangsadapter.

Die Installation des Plugins oder die Konfiguration der Theme-Animationen aktiviert keine nativen Bedienelemente. Die Anwendung aktiviert sie mit dem obigen Startaufruf.

3. Synchronisieren und unter iOS ausführen

Erstellen Sie Ihre Web-Assets und führen Sie anschließend Folgendes aus:

npx cap sync ios

Starten Sie die App auf einem unterstützten iOS-Gerät oder Simulator. Geeignete fixierte Bedienelemente sollten nativ dargestellt werden und weiterhin ihre vorhandenen Handler aufrufen. Navigieren Sie vorwärts und zurück und prüfen Sie anschließend dieselbe App im Browser auf den Web-Fallback. Bleibt unter unterstütztem iOS alles im Web, prüfen Sie direkte Abhängigkeit, Startaufruf, Synchronisierung und erneuten nativen Build. Unter unterstützte Bedienelemente finden Sie geeignetes Markup und das Web-Fallback-Verhalten. Behalten Sie die Theme-Stile für Web-Inhalte und nicht projizierte Bedienelemente.

Optional: Vertical Bars

Für eine Seitenleiste folgen Sie der Standardkonfiguration für Vertical Bars: Laden Sie das Layout-Stylesheet und verbinden Sie Anfangsposition sowie Ereignisse des installierten Foldable-Plugins. Die Shell enthält die Laufzeit für die Seitenleiste; ein weiterer Startaufruf ist nicht nötig. Der Standardstart wählt bereits horizontale und seitliche Bedienelemente aus; behalten Sie ihn beim Hinzufügen einer Seitenleiste zur bestehenden nativen Oberfläche. Verwenden Sie enableNativeUI({ controls: 'verticalOnly' }) nur, wenn die automatische Projektion auf die Seitenleiste beschränkt sein soll. Siehe Konfigurationsoptionen.

Eine bestehende native Integration aktualisieren

Wenn Sie native APIs bisher aus dem Theme-Paket importiert haben, folgen Sie der Migration nativer Importe und der Migration des nativen Projekts. Behalten Sie gewöhnliche Theme-Importe und Stylesheets.