Ionic Framework Integration mit Analog

Dieses Tutorial führt durch den Prozess der Integration von Ionic Framework in eine Analog-Anwendung, damit die Leistungsfähigkeit der iOS- und Android-Komponenten von Ionic in einer Anwendungen genutzt werden kann.

Schritt 1: Ionic Framework installieren

Zu Beginn muss das Paket @ionic/angular@latest installiert werden. Je nach bevorzugten Paketmanager führe einen der folgenden Befehle aus:

npm
yarn
pnpm

npm install @ionic/angular@latest

yarn add @ionic/angular@latest

pnpm install @ionic/angular@latest

Optional: Ionic Angular Toolkit für Schemata installieren

Ionic bietet auch eine Reihe von Schemata, die helfen können, Komponenten zu erstellen, die der Ionic-Struktur folgen. Du kannst diese hinzufügen, indem du das Paket @ionic/angular-toolkit zu den devDependencies installierst

npm
yarn
pnpm

npm install -D @ionic/angular-toolkit

yarn add -D @ionic/angular-toolkit

pnpm install -D @ionic/angular-toolkit

Optional: Installieren von Ionicons: Ionic Bibliothek mit benutzerdefinierten Symbolen

Ionic bietet auch eine Icon-Bibliothek, die mehr als 500 Icons für die meisten Bedürfnisse einer mobilen Anwendungen enthält. Diese können installiert werden, indem das Paket ionicons zu dem Projekt hinzugefügt wird:

npm
yarn
pnpm

npm install ionicons

yarn add ionicons

pnpm install ionicons

Schritt 2: Konfigurieren von Ionic Framework in der Anwendung

Aktualisiere die vite.config.ts-Datei, um Ionic-Pakete in den SSR-Prozess einzubeziehen, indem es zum Array noExternal hinzugefügt wird. ionicons ist nur erforderlich, wenn das ionicons-Paket installiert wurde. Wenn du Vitest verwendest, binde das @ionic/angular-Paket ein, damit Vitest dieses Paket korrekt für Vitest bauen kann.

export default defineConfig(({ mode }) => {
  return {
    // ...

    // add these lines
    ssr: {
      noExternal: ['@ionic/**', '@stencil/**', 'ionicons'],
    },

    // ...

    // add these lines if you use Vitest
    test: {
      server: {
        deps: {
          inline: ['@ionic/angular'],
        },
      },
    },
  };
});

Füge in der app.config.ts die Methode provideIonicAngular und den Provider IonicRouteStrategy hinzu.

import { RouteReuseStrategy, provideRouter } from '@angular/router';
import {
  IonicRouteStrategy,
  provideIonicAngular,
} from '@ionic/angular/standalone';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFileRouter(),
    provideClientHydration(),
    provideHttpClient(withFetch()),
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    provideIonicAngular(),
  ],
};

Aktualisiere die app.component.ts-Datei, um in der Vorlage die erforderlichen Ionic-Tags zu setzen. Du solltest dir die Vorsichtsmaßnahme für serverseitiges Rendern ansehen, da Ionic noch keine Client-Hydrierung unterstützt

import { Component } from '@angular/core';
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';

@Component({
  selector: 'demo-root',
  standalone: true,
  imports: [IonApp, IonRouterOutlet],
  template: `<ion-app><ion-router-outlet></ion-router-outlet></ion-app>`,
})
export class AppComponent {}

Benennen Sie die Datei styles.css in styles.scss um.
Setze die Eigenschaft inlineStylesExtension in der Datei vite.config.ts auf 'scss:

export default defineConfig(({ mode }) => {
  return {
    plugins: [
      analog({
        inlineStylesExtension: 'scss',
      }),
    ],
  };
});

Aktualisiere die Datei index.html, um auf die SCSS-Datei zu verweisen:

<head>
  <!-- other headers -->
  <link rel="stylesheet" href="/src/styles.scss" />
</head>
<body>
  <!-- content -->
</body>

Aktualisiere die Datei styles.scss, um die Ionic-Styles zu importieren und ein benutzerdefiniertes Theme zu definieren:

/* Core CSS required for Ionic components to work properly */
@import '@ionic/angular/css/core.css';

/* Basic CSS for apps built with Ionic */
@import '@ionic/angular/css/normalize.css';
@import '@ionic/angular/css/structure.css';
@import '@ionic/angular/css/typography.css';
@import '@ionic/angular/css/display.css';

/* Optional CSS utils that can be commented out */
@import '@ionic/angular/css/padding.css';
@import '@ionic/angular/css/float-elements.css';
@import '@ionic/angular/css/text-alignment.css';
@import '@ionic/angular/css/text-transformation.css';
@import '@ionic/angular/css/flex-utils.css';

/**
 * Ionic Dark Mode
 * -----------------------------------------------------
 * For more info, please see:
 * https://ionicframework.com/docs/theming/dark-mode
 */

/* @import "@ionic/angular/css/palettes/dark.always.css"; */
/* @import "@ionic/angular/css/palettes/dark.class.css"; */
@import '@ionic/angular/css/palettes/dark.system.css';

Vorsichtsmaßnahme für serverseitiges Rendern

Das Ionic Framework unterstützt nicht Angulars neue Client Hydration, wie Angular unterstützt es nicht SSR mit Webkomponenten, und wenn sie unterstützt werden, muss an den Stencil-Komponenten gearbeitet werden, um sie zu aktivieren. Im Moment gibt es also drei Möglichkeiten, dies zu handhaben:

Entfernen provideClientHydration() aus den app.config.ts Providern.

Dies entfernt den neuen Client-Hydrierungsmechanismus von Angular und kehrt zum vorherigen Mechanismus zurück, der ein Flackern verursacht, wenn das DOM vom Client neu gerendert wird.

import { RouteReuseStrategy, provideRouter } from '@angular/router';
import {
  IonicRouteStrategy,
  provideIonicAngular,
} from '@ionic/angular/standalone';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFileRouter(),
    //provideClientHydration(), // remove this.
    provideHttpClient(withFetch()),
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    provideIonicAngular(),
  ],
};

Hinzufügen des Attributs ngSkipHydration zum Tag ion-app.

Dadurch wird der Client-Hydrierungsmechanismus für das Element ion-app und seine Kinder deaktiviert, aber die Client-Hydrierung wird weiterhin für andere Elemente verwendet. Dies wird auch ein Flackern auf der Seite für die Ionic-Komponenten verursachen. Dies ist für andere Elemente/Komponenten nicht sehr hilfreich, da bei Ionic-Apps alle Ionic-Komponenten innerhalb des Tags ion-app existieren.
```
import { Component } from '@angular/core';
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';

@Component({
  selector: 'demo-root',
  standalone: true,
  imports: [IonApp, IonRouterOutlet],
  template: `
    <ion-app ngSkipHydration>
      <ion-router-outlet></ion-router-outlet>
    </ion-app>
  `,
})
export class AppComponent {}
```

SSR vollständig deaktivieren

Deaktiviere SSR in der Datei vite.config.ts. Dadurch wird das Flackern beseitigt, aber du verlierst alle Vorteile von SSR in der Anwendung.
```
plugins: [
  analog({
    ssr: false,
  }),
],
```

Du musst eine der vorherigen Optionen wählen, da die Nichtkonfiguration dazu führt, dass die Anwendung zur Laufzeit Fehler wie folgende auslöst:

ERROR Error: NG0500: During hydration Angular expected <ion-toolbar> but found a comment node.

Angular expected this DOM:

  <ion-toolbar color="secondary">…</ion-toolbar>  <-- AT THIS LOCATION
  …


Actual DOM is:

<ion-header _ngcontent-ng-c1775393043="">
  <!--  -->  <-- AT THIS LOCATION
  …
</ion-header>

Note: attributes are only displayed to better represent the DOM but have no effect on hydration mismatches.

To fix this problem:
  * check the "AppComponent" component for hydration-related issues
  * check to see if your template has valid HTML structure
  * or skip hydration by adding the `ngSkipHydration` attribute to its host node in a template

Schritt 3: Hinzufügen von Capacitor (optional)

Mit Capacitor können native Webanwendungen erstellt werden, die problemlos auf iOS- und Android-Geräten ausgeführt werden können.

Schritt 3.1 Installieren und konfigurieren der Capacitor-App

Zuerst müssen die Pakete @capacitor/core und @capacitor/cli installiert werden. Abhängig vom bevorzugten Paketmanager, führen einen der folgenden Befehle aus:

npm
yarn
pnpm

npm install @capacitor/core
npm install -D @capacitor/cli

yarn add @capacitor/core
yarn add -D @capacitor/cli

pnpm install @capacitor/core
pnpm install -D @capacitor/cli

Dann muss das Capacitor-Projekt mit dem folgenden Befehl initialisiert werden. Die CLI wird einige Fragen stellen, beginnend mit dem Namen der Anwendung und der Paket-ID, die für die Anwendung verwendet werden soll.

npx cap init

Aktualisiere die Eigenschaft webDir der Datei capacitor.config.ts so, dass sie auf den dist-Ordner des Analog Builds zeigt

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.ionic.capacitor',
  appName: 'ionic-capacitor',
  webDir: 'dist/analog/public',
};

export default config;

Schritt 3.2 Erstellen des Android- und iOS-Projektes

Installiere die Pakete @capacitor/android und/oder @capacitor/ios basierend auf den Plattformen, die unterstützt werden sollen.

npm
yarn
pnpm

npm install @capacitor/android
npm install @capacitor/ios

yarn add @capacitor/android
yarn add @capacitor/ios

pnpm install @capacitor/android
pnpm install @capacitor/ios

Füge das Android- und/oder iOS-Projekt zu der App hinzu

npx cap add android
npx cap add ios

Synchronisiere die Projektdateien mit den installierten Plattformen

npx cap sync

Die App nun mit den folgenden Befehlen ausgeführt werden

npx cap run android
npx cap run ios

Das war's! Du hast das Ionic Framework mit (oder ohne) Capacitor für deine Analog-Anwendung erfolgreich installiert und konfiguriert!

Schritt 1: Ionic Framework installieren​

Optional: Ionic Angular Toolkit für Schemata installieren​

Optional: Installieren von Ionicons: Ionic Bibliothek mit benutzerdefinierten Symbolen​

Schritt 2: Konfigurieren von Ionic Framework in der Anwendung​

Vorsichtsmaßnahme für serverseitiges Rendern​

Schritt 3: Hinzufügen von Capacitor (optional)​

Schritt 3.1 Installieren und konfigurieren der Capacitor-App​

Schritt 3.2 Erstellen des Android- und iOS-Projektes​