Theme-Migration

Diese Anleitung aktualisiert das eigenständige Theme und dessen Capacitor-Integration. Für das mit Cordova gebündelte Theme lesen Sie Eine bestehende Theme-App nach Cordova migrieren.

Optional: die Einrichtung vereinfachen

Die gebündelten Theme-Stile und ios27ThemeConfig sind zusätzliche Komfort-APIs. Ihre Einführung ist optional; bestehende einzelne CSS-Pfade und Animationsexporte bleiben unterstützt. Folgen Sie für eine neue Anwendung der Einrichtung und für einzelne Einstellungen der Konfiguration.

Die passende Stylesheet-Gruppe ersetzen

Behalten Sie bei der Auswahl eines Stylesheets die bisherige Darstellungsstrategie der Anwendung bei. Beispielsweise kann eine Anwendung mit klassenbasiertem Dunkelmodus diese Gruppe nach Ionics CSS-Basisimporten ersetzen.

- @import '@ionic/core/css/palettes/dark.class.css';
- @import '@rdlabo/ionic-theme-ios27/dist/css/default-variables.css';
- @import '@rdlabo/ionic-theme-ios27/dist/css/ionic-theme-ios27.css';
- @import '@rdlabo/ionic-theme-ios27/dist/css/md-remove-ios-class-effect.css';
- @import '@rdlabo/ionic-theme-ios27/dist/css/ionic-theme-ios27-dark-class.css';
+ @import '@rdlabo/ionic-theme-ios27/styles/class.css';

Verwenden Sie styles/system.css für einen bestehenden systemgesteuerten Dunkelmodus und styles/always.css für eine stets dunkle Darstellung. Behalten Sie Ionics CSS-Basisimporte und die anwendungsspezifischen Variablenüberschreibungen bei; letztere folgen auf das Stylesheet. Klassenbasierte Anwendungen behalten ihr vorhandenes Umschalten von ion-palette-dark bei. Ersetzen Sie die entsprechenden Importe gemeinsam, um weder eine zweite Palette noch doppelte Theme-Stile zu laden. Anwendungen mit einer eigenen teilweisen Zusammenstellung von Stylesheets können die einzelnen Importe weiterverwenden.

Animationsstandardwerte ersetzen und Anwendungsoptionen beibehalten

Ersetzen Sie die manuell zusammengestellten Animationsstandardwerte durch den Konfigurations-Spread. Behalten Sie konkrete Anwendungseinstellungen nach dem Spread bei, damit sie Vorrang haben.

- import { iosTransitionAnimation, popoverEnterAnimation, popoverLeaveAnimation } from '@rdlabo/ionic-theme-ios27';
+ import { ios27ThemeConfig } from '@rdlabo/ionic-theme-ios27';

 const ionicConfig = {
-   mode: 'ios' as const,
-   navAnimation: iosTransitionAnimation,
-   popoverEnter: popoverEnterAnimation,
-   popoverLeave: popoverLeaveAnimation,
+   ...ios27ThemeConfig,
   animated: false, // Keep this application's reduced-motion setting.
 };

Die Konfiguration stellt auf jeder Plattform den iOS-Modus bereit. Hat die App den Modus bisher plattformabhängig ausgewählt, wählen Sie die Konfiguration als Ganzes vor dem Spread aus. So bleiben außerhalb von iOS Ionics Material-Design-Standardwerte erhalten.

import { isPlatform } from '@ionic/core';
import { ios27ThemeConfig } from '@rdlabo/ionic-theme-ios27';

const ionicConfig = {
  ...(isPlatform('ios') ? ios27ThemeConfig : { mode: 'md' as const }),
  animated: false, // Optional application preference on both platforms.
};

Verwenden Sie die eigene Funktion zur Modusauswahl Ihrer Anwendung, wenn sie einer anderen Strategie folgt. Wenn Sie nach dem Spread nur mode ändern, bleiben die Animationseigenschaften der Konfiguration erhalten. Behalten Sie die bestehende Framework-Initialisierung bei und übergeben Sie ihr die zusammengestellte Konfiguration vor dem Rendern.

Eigene Animationen und ausdrücklich gesetzte Animationswerte mit undefined können ebenfalls nach dem Spread folgen. Beispielsweise überlässt diese Konfiguration Ionic die Auswahl der Einblendeanimation für Popover.

const ionicConfig = {
  ...ios27ThemeConfig,
  popoverEnter: undefined, // Use Ionic's default enter animation.
  // navAnimation: myNavigationAnimation, // Your application's custom transition.
};

Ersetzen Sie bei der Einführung der Konfiguration die alten Zuweisungen der Theme-Standardwerte durch den Spread. Behalten Sie beabsichtigte anwendungsspezifische Überschreibungen danach bei. Bedingungen für Browserfunktionen und die Auswahl mehrerer Themes können ihre bestehende adaptive Konfiguration beibehalten.

Prüfen Sie danach dieselben Modi sowie hellen und dunklen Zustände, die Ihre Anwendung bisher unterstützt hat, und kontrollieren Sie anschließend Navigation und Popover. Gerätelayout und Native-UI-Start verwenden weiterhin ihre jeweiligen APIs.

Upgrade von 2.1.0

Dieser Abschnitt beschreibt in der Theme- und der Native UI-Anleitung dasselbe Upgrade; eine der beiden Anleitungen genügt. Behalten Sie bestehende Theme-Importe, Stylesheets und Animationseinstellungen bei. Native UI bleibt optional. Falls aktiviert, behalten Sie den vorhandenen Aufruf von enableNativeUI(), die Steuerelementauswahl und die Laufzeit an der Anwendungswurzel bei. Die ältere Pakettrennungsmigration weiter unten muss nicht wiederholt werden.

Abhängigkeiten aktualisieren

Aktualisieren Sie bei reinen Theme-Anwendungen das Theme:

npm install @rdlabo/ionic-theme-ios27@latest

Aktualisieren Sie bei Anwendungen mit Gerätegeometrie für die Seitenleiste oder Native UI alle drei Pakete einschließlich Foldable. Sie werden unabhängig versioniert; verwenden Sie gemäß der Peer-Abhängigkeit des Themes kompatible Versionen:

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

Der folgende Resolver-Import liefert Layoutwerte, ohne die native Projektion zu aktivieren. Reine Theme-Anwendungen ohne geräteseitige Leiste können den Schritt zur Gerätegeometrie überspringen.

Gerätegeometrie aktualisieren

Wenn Ihre App getBarPlacement() direkt auf setVerticalBarsLayout({ edge, inset }) abbildet, verwenden Sie den Resolver, um den Ursprung der Werkzeugleiste aus den reservierten Bereichen einzubeziehen:

- import { Foldable, type BarPlacement } from '@erkamyaman/capacitor-foldable';
+ import { Foldable } from '@erkamyaman/capacitor-foldable';
+ import { resolveVerticalBarsLayout } from '@rdlabo/capacitor-native-ui/integration';
 import { setVerticalBarsLayout } from '@rdlabo/ionic-theme-ios27';

- const applyPlacement = ({ verticalBarEdge, inset }: BarPlacement) =>
-   setVerticalBarsLayout({ edge: verticalBarEdge, inset });
- const listener = await Foldable.addListener('barPlacementChange', applyPlacement);
- applyPlacement(await Foldable.getBarPlacement());
+ const updateLayout = async () => {
+   setVerticalBarsLayout(await resolveVerticalBarsLayout(Foldable));
+ };
+ const listener = await Foldable.addListener('layoutChange', () => void updateLayout());
+ await updateLayout();

Ersetzen Sie den alten Platzierungslistener, statt einen zweiten Aktualisierungspfad hinzuzufügen. Behalten Sie await listener.remove() im bestehenden Aufräumcode der Anwendung bei. Falls bereits ein layoutChange-Handler vorhanden ist, rufen Sie den Resolver dort auf. Die bestehende Anbindung von foldStateChange / applyFoldStateClasses für die Faltstellung bleibt erhalten; der Resolver liefert nur die Geometrie der Leiste.

Verwenden Sie das gemeldete Leistenlayout direkt, ohne es von isDeviceFoldable(), einem Gerätenamen oder heuristischen Viewport-Größen abhängig zu machen. Entfernen Sie feste Toolbar-Top-Workarounds, die Gerätegeometrie nachbilden sollten. Beabsichtigte CSS-Anpassungen der Anwendung bleiben unterstützt. Standardwerte verbleiben in setVerticalBarsLayout des Themes, nicht im Resolver. Der Standard für das Außendisplay beträgt 174px; gemeldete Gerätegeometrie kann den Ursprung des Innendisplays von 124px liefern. Siehe Layoutwerte und Rückfallverhalten.

Modal-Korrekturen und Aussehen von Absendeaktionen

Schwebende Karten und Sheets verwenden jetzt gemessene Grenzen, um die Duo-Leiste nicht zu überlappen, und Native UI erkennt schwebende Dialoge, die die Leiste überlappen, korrekt. Dies korrigiert das Modal-Layout und die Behandlung nativer Steuerelemente ohne Änderungen am Anwendungscode. CSS, das allein als Workaround für diesen Fehler volle Breite erzwungen hat, können Sie entfernen. Behalten Sie explizite Vollbildgrößen bei, wenn sie eine Produktanforderung sind. Mit ios-theme-vertical-bars oder ios-theme-fold-expanded auf ion-app lassen schwebende Karten und Sheets auf jeder Seite mindestens 8px frei. Bei mindestens 600px hohen Viewports ist ihre Breite auf 653px begrenzt; niedrigere Viewports nutzen die verfügbare Breite minus 16px. Der obere Abstand folgt der Safe Area und beträgt mindestens 8px. Sheet-Breakpoints steuern weiterhin die sichtbare Höhe. Anwendungsspezifische Größen über --width, --max-width und --height bleiben unterstützt. Übliche Telefon- und Tablet-Standardwerte ändern sich nicht, wenn keine der Layoutklassen aktiv ist.

Ausgefüllte Ionic-Absende-Schaltflächen verwenden automatisch eine hervorgehobene native Glasdarstellung:

<ion-button type="submit" fill="solid">Save</ion-button>

Dasselbe Aussehen gilt für vorhandene .button-submit-Aktionen mit solider Füllung. Diese Klasse gestaltet nur die Darstellung und sendet kein Formular ab. Clear- und Outline-Füllungen erhalten keine Absendehervorhebung. Bestehende explizite Deklarationen von data-native-ui="button-submit" bleiben unterstützt.

Native Steuerelemente behalten während Navigation, Modal-Animationen und Bildübergaben die Zuständigkeit. Ein in der WebView angezeigtes Bild ist weiterhin die Darstellung der nativen Projektion und keine Rückkehr zum ursprünglichen Web-Button. Testen und entfernen Sie transitionsspezifische Workarounds, die diese Steuerelemente ins Web zurückzwingen. Behalten Sie beabsichtigte Ausnahmen sowie die Behandlung nicht unterstützter Steuerelemente und nativer Fehler bei; zusätzliche Animationsflags oder eine zweite Laufzeit sind nicht nötig.

Prüfen Sie beide Leistenseiten, das Verschwinden der Leiste, Falten und Drehen, Karten-, Sheet- und Vollbilddarstellungen sowie solide Absendeaktionen. Prüfen Sie auch ein gewöhnliches iPhone und den Browser-Fallback. Verwenden Sie für Cordova die gebündelte Integration; das festgelegte Theme und native Änderungen werden durch ein Cordova-Plugin-Release bereitgestellt, nicht über diese Capacitor-Installationsbefehle.

Aufteilung in ein eigenes Native UI-Paket

Theme-Stile und gewöhnliche Theme-API-Importe werden weiterhin unterstützt. Wenn Sie native Bedienelemente bisher über dieses Paket verwendet haben: Die Einstiegspunkte /native und /vertical-bars wurden entfernt:

Fügen Sie das native Paket als direkte Anwendungsabhängigkeit hinzu, aktualisieren Sie Importe, erstellen Sie die Web-Assets erneut und führen Sie npx cap sync ios aus. Die Native UI-Migrationsanleitung beschreibt Starteinstellungen aus 1.2.1 und Änderungen am nativen Projekt. Reine Theme-Apps benötigen weder nativen Start noch Plugin-Einrichtung.

Gerätelayout in 2.0

Installieren Sie Foldable im Rahmen der Standardeinrichtung neben dem Theme:

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

Ersetzen Sie die bisherigen Gerätelayout-APIs durch Foldable-Abonnements:

Wenden Sie die Position mit setVerticalBarsLayout und die Faltstellung mit applyFoldStateClasses an; beide werden aus dem Theme importiert. Lesen Sie neben dem Abonnieren von Änderungen auch den Anfangszustand. Die aktuelle Einrichtung beschreiben Gerätelayout und Split Panes und Seitenleistenprojektion. Die Paketinstallation allein abonniert keine Geräteereignisse und aktiviert keine Projektion.

Vom iOS-26-Theme

Für eine App mit @rdlabo/ionic-theme-ios26 empfiehlt sich, dieses Paket zu behalten und @rdlabo/ionic-theme-ios27 hinzuzufügen. Die adaptive Theme-Einrichtung wählt iOS-27- oder iOS-26-Stile anhand der Browserfunktionen und lässt älteren Browsern Ionics standardmäßige iOS-Darstellung.

1. Das neue Paket hinzufügen

Behalten Sie das iOS-26-Paket bei und ergänzen Sie iOS 27. Das neue Theme benötigt @ionic/core ab 8.8.1 (Ionic 8 oder 9).

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

2. Die Styles adaptiv gestalten

Ersetzen Sie unbedingte iOS-26-Imports in Ihrem globalen Sass-Stylesheet durch zwei einander ausschließende Zweige. Dieses Beispiel verwendet den klassenbasierten dunklen Modus:

+ @use 'sass:meta';
+
- @use '@rdlabo/ionic-theme-ios26/src/styles/default-variables.scss';
- @use '@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26.scss';
- @use '@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26-dark-class.scss';
- @use '@rdlabo/ionic-theme-ios26/src/styles/md-remove-ios-class-effect.scss';
+ @supports (overflow-anchor: auto) {
+  @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/default-variables');
+  @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/ionic-theme-ios27');
+  @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/ionic-theme-ios27-dark-class');
+  @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/md-remove-ios-class-effect');
+ }
+
+ @supports (text-wrap: pretty) and (not (overflow-anchor: auto)) {
+  @include meta.load-css('@rdlabo/ionic-theme-ios26/src/styles/default-variables');
+  @include meta.load-css('@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26');
+  @include meta.load-css('@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26-dark-class');
+  @include meta.load-css('@rdlabo/ionic-theme-ios26/src/styles/md-remove-ios-class-effect');
+ }

Behalten Sie die passende dunkle Ionic-Palette bei. Ersetzen Sie für einen systemgesteuerten oder dauerhaft dunklen Modus beide -dark-class-Imports durch die passende Variante. Wenn Sie md-ion-list-inset verwenden, laden Sie das Stylesheet des entsprechenden Pakets innerhalb jedes Zweigs. Browser ohne diese Funktionen behalten die Standardgestaltung von Ionic.

3. Die Animationen wechseln

Ersetzen Sie den iOS-26-Animationsimport und aktivieren Sie die iOS-27-Animationen anhand derselben Browser-Funktionen. Ermitteln Sie die Optionen vor der Initialisierung von Ionic:

- import { iosTransitionAnimation, popoverEnterAnimation, popoverLeaveAnimation } from '@rdlabo/ionic-theme-ios26';
+ import { iosTransitionAnimation, popoverEnterAnimation, popoverLeaveAnimation } from '@rdlabo/ionic-theme-ios27';
+
+ function loadIOSAnimations() {
+  if (typeof CSS === 'undefined') return {};
+  if (!CSS.supports('overflow-anchor: auto') && !CSS.supports('text-wrap: pretty')) return {};
+
+  return {
+    navAnimation: iosTransitionAnimation,
+    popoverEnter: popoverEnterAnimation,
+    popoverLeave: popoverLeaveAnimation,
+  };
+ }

  provideIonicAngular({
-  navAnimation: isPlatform('ios') ? iosTransitionAnimation : undefined,
-  popoverEnter: isPlatform('ios') ? popoverEnterAnimation : undefined,
-  popoverLeave: isPlatform('ios') ? popoverLeaveAnimation : undefined,
+  ...(isPlatform('ios') ? loadIOSAnimations() : {}),
  });

Die iOS-27-Seitenübergangs- und Popover-Animationen werden für beide gestalteten Generationen verwendet. Ältere Browser behalten die Ionic-Standardwerte. Das Beispiel verwendet Angular; übergeben Sie dieselben Optionen an setupIonicReact von React oder IonicVue von Vue.

4. Anpassungen aktualisieren

Benennen Sie die von Ihrer Anwendung verwendeten Theme-Variablen und deaktivierenden Klassen um. Zum Beispiel:

  ion-content {
-  --ios26-content-box-shadow-rgb: 0, 0, 0;
+  --ios-theme-content-box-shadow-rgb: 0, 0, 0;
  }

- <ion-button class="ios26-disabled">Standard Ionic button</ion-button>
+ <ion-button class="ios-theme-disabled">Standard Ionic button</ion-button>

Die alten Namen bleiben als veraltete Rückfalloptionen erhalten. Prüfen Sie die resultierenden Oberflächen im hellen und dunklen Modus auf den unterstützten Browsern.

Nur iOS 27

Um vollständig auf iOS 27 umzustellen, entfernen Sie das iOS-26-Paket und ersetzen Sie dessen Stylesheet- und Animationsimports. Die Stylesheet-Änderungen lauten:

- @use '@rdlabo/ionic-theme-ios26/src/styles/default-variables.scss';
- @use '@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26.scss';
- @use '@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26-dark-class.scss';
- @use '@rdlabo/ionic-theme-ios26/src/styles/md-remove-ios-class-effect.scss';
+ @use '@rdlabo/ionic-theme-ios27/src/styles/default-variables.scss';
+ @use '@rdlabo/ionic-theme-ios27/src/styles/ionic-theme-ios27.scss';
+ @use '@rdlabo/ionic-theme-ios27/src/styles/ionic-theme-ios27-dark-class.scss';
+ @use '@rdlabo/ionic-theme-ios27/src/styles/md-remove-ios-class-effect.scss';

Ändern Sie den Animationsimport von @rdlabo/ionic-theme-ios26 zu @rdlabo/ionic-theme-ios27; die vorhandene Konfiguration mit isPlatform('ios') kann bleiben. Siehe iOS-27-Einrichtung. Unbedingte Importe wenden die neuen Stile in jedem Browser mit Ionics iOS-Modus an.

Benennung für iOS 27

Verwenden Sie im iOS-27-Zweig oder in einer reinen iOS-27-Anwendung @rdlabo/ionic-theme-ios27. Seine Stylesheets heißen ionic-theme-ios27.scss beziehungsweise ionic-theme-ios27.css, einschließlich der Varianten -dark-always, -dark-system und -dark-class. Behalten Sie bei adaptiver Konfiguration die iOS-26-Stylesheet-Namen im iOS-26-Zweig bei.

Verwenden Sie für neue Anpassungen die versionsunabhängigen Namen.

Die aktuellen Namen finden Sie unter Spezielles Markup und Klassen und Standardvariablen.

Frühere Migrationshinweise bleiben in der iOS-26-Migrationsanleitung erhalten.

Aussehen von Absende-Schaltflächen

Absende-Schaltflächen verwenden jetzt den Standard-Kontrastwert jeder Ionic-Farbe und eine richtungsabhängige iOS-27-Randgestaltung. Entfernen Sie die themespezifischen Helligkeitsvariablen.

  :root {
-  --ion-color-primary-brightness-rgb: 130, 255, 255;
-  --ion-color-primary-brightness: #96feff;
  }