Skip to content

9. Kommunikation mit dem Server

Der JSON-Server von [RdvMedecins] muss nun gestartet werden (Port 8080), wie im vorigen Kapitel erklärt, vorzugsweise im CAPTCHA-Testmodus ([CAPTCHA_TEST=test]), der es erlaubt, auf jedes Bild mit „test“ zu antworten.

Die Beispiele 22 bis 25 teilen sich einige Dateien im Ordner [src/app/common/] des Projekts: die Serveradresse ([config.ts]), die Antworttypen ([types.ts]), die Fehlerklassen ([api-error.ts]), den Anfrage-Service ([api.ts]) und eine Anmeldeleiste ([login-bar.ts]). Sie werden im Laufe der Beispiele vorgestellt, sobald sie relevant werden.

9.1. Beispiel 22: Eine erste HTTP-Anfrage

9.1.1. Wo ist der Server?

Bei einem Web-Client, der vom Server selbst ausgeliefert wird, stellt sich die Frage nicht: Die Anfragen gehen mit einer relativen Adresse ([/api/captcha]) an denselben Ursprung wie die Seite. Eine auf einem Telefon installierte App hat keinen verwendbaren Ursprung: Ihre Seite wird von [Capacitor] selbst ausgeliefert, von https://localhost. Sie müssen die vollständige Serveradresse angeben, und diese Adresse hängt davon ab, wo die App läuft:

// =========================================================================
// src/app/common/config.ts - WO liegt der JSON-Server?
// -------------------------------------------------------------------------
// Die Frage stellt sich nicht für eine Webanwendung, die vom
// Server selbst ausgeliefert wird: Die Anfragen gehen an denselben Ursprung wie die Seite
// (eine relative Adresse, /api/...). Eine MOBILE Anwendung hat aber keinen
// verwendbaren Ursprung (unter Android wird die Seite von Capacitor
// über https://localhost ausgeliefert): Ihr muss die vollständige Adresse des Servers mitgegeben werden.
//   - In der Webentwicklung (ng serve) leitet der Entwicklungsserver
//     von Angular die /api-Anfragen an den JSON-Server weiter (Datei
//     proxy.conf.json): Eine relative Adresse genügt;
//   - der Android-Emulator sieht den Rechner, auf dem er läuft, unter
//     der Adresse 10.0.2.2 (localhost ist für ihn der Emulator selbst);
//   - ein echtes Telefon, das mit demselben WLAN wie der Rechner verbunden ist, muss
//     die Adresse des Rechners in diesem Netz verwenden (192.168.1.20 ...):
//     Sie wird beim Erstellen der Anwendung angegeben:
//         ng build --define "SERVER='http://192.168.1.20:8080'"
//     oder aber wir ändern die Konstante androidServer weiter unten.
// =========================================================================

import { Capacitor } from '@capacitor/core';

// die Adresse des Servers für die Android-Anwendung, wenn nichts anderes
// vorgegeben ist: die des Rechners, vom Emulator aus gesehen
const androidServer = 'http://10.0.2.2:8080';

// der Wert, der beim Build mit --define "SERVER='...'" angegeben wird
// (ng build, ng serve). Die Option ersetzt im kompilierten Code das Wort
// SERVER durch den angegebenen Wert. Ohne sie existiert SERVER nicht: typeof
// erlaubt es uns, dies ohne Fehler zu prüfen
declare const SERVER: string | undefined;
const forcedServer = typeof SERVER === 'string' ? SERVER : '';

export const config = {
  // Capacitor.isNativePlatform(): true in der Android-Anwendung (oder iOS),
  // false in einem Browser; Capacitor.getPlatform(): 'android', 'ios' oder 'web'
  serverUrl:
    forcedServer !== ''
      ? forcedServer
      : !Capacitor.isNativePlatform()
        ? '' // das Web: derselbe Ursprung, relative Adressen
        : Capacitor.getPlatform() === 'android'
          ? androidServer
          : 'http://localhost:8080',
};
  • Zeile 21: [Capacitor], das Objekt aus [@capacitor/core] , das Informationen über die Plattform liefert, auf der die Anwendung läuft. Es kann überall verwendet werden, auch in einem Browser;
  • Zeile 25: Die Standardadresse ist die von [Android]. Der Emulator ist eine eigenständige Maschine mit eigenem Netzwerk: Für den Emulator verweist [localhost] auf den Emulator selbst. Die Spezialadresse [10.0.2.2] verweist auf den Computer, auf dem er läuft;
  • Zeilen 31–32: eine Adresse, die beim Build der Anwendung durch die Option [--define] von [Angular] vorgegeben wird: [ng build --define "SERVER='http://192.168.1.20:8080'"]. Die Kompilierung ersetzt den Bezeichner [SERVER] im Code durch den angegebenen Wert (eine Zeichenkette, daher die Apostrophe). Ohne diese Option existiert [SERVER] nicht: [declare const] teilt dem [TypeScript]-Compiler mit, dass [SERVER] ein Bezeichner ist, dessen Deklaration er nicht sieht, und [typeof SERVER] erlaubt es, seine Existenz ohne Fehler zu prüfen. Das ist das exakte Gegenstück zu [--dart-define] und [String.fromEnvironment] in [Flutter];
  • Zeilen 34–45: andernfalls eine plattformspezifische Adresse. [Capacitor.isNativePlatform()] ist in der Anwendung für [Android] (oder [iOS]) wahr, in einem Browser jedoch falsch; [Capacitor.getPlatform()] liefert 'android', 'ios' oder 'web':
  • im Browser (Zeile 41): eine relative URL (''), also derselbe Ursprung wie die App;
  • unter [Android] (Zeile 43): die Adresse aus Zeile 25;
  • anderswo (Zeile 44, [iOS], das dieser Kurs nicht behandelt): [localhost].

Ein echtes Telefon, das mit demselben WLAN wie der Server-Computer verbunden ist, muss die Adresse des Computers in diesem Netzwerk verwenden (der Befehl [ipconfig] von [Windows] liefert sie): Sie können sie beim Kompilieren über [--define] übergeben oder die Konstante in Zeile 25 ändern. Die Firewall des Computers muss außerdem eingehende Verbindungen auf Port 8080 zulassen.

9.1.2. Android-Projekteinstellungen

Der [Flutter]-Client änderte zwei Zeilen in der Datei [android/app/src/main/AndroidManifest.xml]: die Berechtigung zur Nutzung des Netzwerks und die Erlaubnis, unverschlüsselt über HTTP („Plaintext“) zu kommunizieren. Mit [Capacitor] wird diese Datei nicht geändert:

  • Die Berechtigung [android.permission.INTERNET] ist im [Android]-Projekt, das von [npx cap add android] erstellt wurde, bereits deklariert: Eine [Capacitor]-Anwendung ist eine Webseite und benötigt daher immer Netzwerkzugriff;
  • Die Erlaubnis für HTTP im Klartext ist eine Einstellung in der Datei [capacitor.config.ts] im Stammverzeichnis des Projekts:
// =========================================================================
// capacitor.config.ts - die Capacitor-Konfiguration
// -------------------------------------------------------------------------
// Capacitor macht aus der Webanwendung (dem von ng build erzeugten Ordner)
// eine Android-Anwendung: Es verpackt sie in ein Android-Studio-Projekt
// (Ordner android/), in dem sie von einer "WebView" angezeigt wird, der Engine
// des Chrome-Browsers des Telefons. Befehle (siehe Beispiel 01, "Ausführen"):
//     npx cap add android       (nur einmal: erzeugt den Ordner android/)
//     ng build                  (erstellt die Webanwendung)
//     npx cap sync android      (kopiert sie in das Android-Projekt)
//     npx cap run android       (startet sie auf einem Emulator oder Telefon)
// =========================================================================

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

const config: CapacitorConfig = {
  // die eindeutige Kennung der Anwendung auf dem Telefon (und im Play Store)
  appId: 'fr.stahe.examples',
  // der unter dem Symbol angezeigte Name
  appName: 'Ionic Examples',
  // der Ordner der kompilierten Webanwendung (ng build)
  webDir: 'dist/examples_ionic/browser',
  server: {
    // erlaubt unverschlüsselte HTTP-Anfragen (http://10.0.2.2:8080) an
    // den JSON-Server der Entwicklung (Beispiele 22 bis 25)
    cleartext: true,
  },
  plugins: {
    // CapacitorHttp: Die HTTP-Anfragen der Anwendung werden nicht mehr von
    // der WebView gestellt, sondern vom nativen Android-Code. Folgen (siehe
    // Beispiele 22 und 23): keine CORS-Prüfung (der JSON-Server muss nichts
    // erlauben), und die Cookies (das des Authentifizierungs-Tokens) werden
    // von Android gespeichert und automatisch zurückgesendet
    CapacitorHttp: {
      enabled: true,
    },
  },
};

export default config;
  • Zeilen 23–27: [server.cleartext: true]. Ab Version 9 von [Android] darf eine Anwendung nur noch über HTTPS kommunizieren. Unser Entwicklungsserver verwendet HTTP: Wir erlauben es. Der Befehl [npx cap sync android] überträgt diese Einstellung in das [Android]-Projekt (das Attribut [android:usesCleartextTraffic="true"], das dem Manifest hinzugefügt wird, das [Capacitor] mit dem Manifest der Anwendung zusammenführt). In der Produktion läge der Server unter HTTPS, und diese Einstellung würde entfallen;
  • Zeilen 28–37: das [CapacitorHttp]-Plugin. Die HTTP-Anfragen der Anwendung (die des HTTP-Clients von [Angular] ebenso wie die von [fetch]) werden nicht mehr von der WebView gesendet, sondern vom nativen Code von [Android]. Für einen Browser würden die Anwendung (https://localhost) und der Server (http://10.0.2.2:8080) zwei verschiedene Ursprünge haben: Der Browser würde vom Server eine CORS-Autorisierung verlangen, die der Server nicht erteilt, und würde sich weigern, das Token-Cookie mitzusenden. Der native Code kennt diese Regeln nicht. Der Code der App in [TypeScript] ändert sich jedoch nicht: Es ist [Capacitor], das die Anfragen umleitet.

9.1.3. Und im Browser?

Während der Entwicklung läuft die Anwendung im Browser des Computers: [ng serve] liefert sie auf Port 8100 aus, während der JSON-Server auf Port 8080 läuft. Wieder gibt es zwei Ursprünge, und [CapacitorHttp] arbeitet nicht innerhalb eines Browsers. Die Lösung ist ein Proxy, der in [angular.json] konfiguriert wird (Option ["proxyConfig": "proxy.conf.json"] des Targets [serve]):

1
2
3
4
5
6
7
8
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false,
    "changeOrigin": false,
    "logLevel": "warn"
  }
}
  • Zeile 2: Jede Anfrage, deren Adresse mit [/api] beginnt ...
  • Zeile 3: ... wird vom Entwicklungsserver von [Angular] an den JSON-Server weitergeleitet, und seine Antwort wird an den Browser zurückgesendet. Für den Browser haben die Anwendung und die API denselben Ursprung (http://localhost:8100): kein CORS, und das Cookie wird mitgesendet. Genau das ist die Rolle des [Vite]-Proxys im Kurs [React] und der Datei [web_dev_config.yaml] im Kurs [Flutter];
  • Zeile 4: [secure: false]: kein gültiges HTTPS-Zertifikat vom Ziel verlangen (es ist ohnehin HTTP); Zeile 6: nur Proxy-Warnungen anzeigen.

9.1.4. Die Anfrage

Beim Server wird ein CAPTCHA angefordert: [GET /api/captcha], die mit [{ "id": "...", "svg": "<svg ...>" }] beantwortet wird.

// =========================================================================
// src/app/ex22-http/ex22.page.ts - eine erste HTTP-Anfrage an den Server
// -------------------------------------------------------------------------
// Der JSON-Server von RdvMedecins muss laufen (Port 8080). Wir fordern von ihm
// ein CAPTCHA an: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - HttpClient: der HTTP-Client von Angular (der gesamten Anwendung
//     durch provideHttpClient() in main.ts bereitgestellt). http.get<T>(address) liefert
//     ein Observable: Die Anfrage wird gesendet, wenn wir es ABONNIEREN (subscribe), und
//     die Antwort trifft später ein, ihr JSON-Body ist bereits dekodiert;
//   - eine Fehlerantwort (4xx, 5xx) oder das Ausbleiben einer Antwort landet
//     in der Funktion error des Abonnements;
//   - die Adresse des Servers hängt davon ab, wo die Anwendung läuft
//     (Browser, Android-Emulator, Telefon): siehe common/config.ts;
//   - drei darzustellende Zustände: wird geladen, erfolgreich, fehlerhaft;
//   - das Bild des CAPTCHA ist SVG: Ein <img>-Tag kann es anzeigen.
// =========================================================================

import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { Component, DestroyRef, inject, signal } from '@angular/core';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonContent, IonHeader, IonNote, IonProgressBar,
  IonTitle, IonToolbar,
} from '@ionic/angular';
import { Subscription } from 'rxjs';
import { config } from '../common/config';
import { Captcha, captchaImage } from '../common/types';

@Component({
  selector: 'app-ex22',
  imports: [
    IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonProgressBar, IonCard, IonCardContent,
    IonButton, IonNote,
  ],
  templateUrl: './ex22.page.html',
  styles: `
    .error { --background: #ffebee; --color: #333; margin: 12px 0; }
    .image { border: 1px solid #ddd; border-radius: 6px; padding: 4px; text-align: center; }
    .image img { height: 60px; }
    .id { font-family: monospace; font-size: 11px; margin: 8px 0; }
  `,
})
export class Ex22Page {
  private readonly http = inject(HttpClient);
  readonly server = config.serverUrl || '(same origin: /api, ng serve proxy)';
  readonly captchaImage = captchaImage;

  // der Zustand des Bildschirms: Signals
  readonly captcha = signal<Captcha | null>(null);
  readonly loading = signal(true);
  readonly error = signal<string | null>(null);
  readonly requestCount = signal(0);

  // das Abonnement der laufenden Anfrage (falls vorhanden)
  private request?: Subscription;

  constructor() {
    this.load(); // die erste Anfrage, sobald die Seite erzeugt wird
    // die Seite wird zerstört (Zurück-Taste): Die laufende Anfrage wird abgebrochen
    inject(DestroyRef).onDestroy(() => this.request?.unsubscribe());
  }

  load(): void {
    // Das Abbestellen einer noch laufenden Anfrage BRICHT sie ab: Ihre Antwort,
    // nun nutzlos, wird nie verarbeitet (keine "veraltete" Antwort)
    this.request?.unsubscribe();
    this.loading.set(true);
    this.error.set(null);
    // <Captcha>: der Typ des erwarteten JSON-Body (ein Versprechen an den
    // Compiler: Zur Laufzeit wird nichts geprüft)
    this.request = this.http.get<Captcha>(`${config.serverUrl}/api/captcha`).subscribe({
      // next: Die Antwort ist eingetroffen (Code 2xx), ihr JSON-Body ist dekodiert
      next: (captcha) => {
        this.captcha.set(captcha);
        this.requestCount.update((n) => n + 1);
        this.loading.set(false);
      },
      // error: eine Fehlerantwort (4xx, 5xx) oder überhaupt keine Antwort
      // (Server gestoppt, falsche Adresse: status ist dann 0)
      error: (e: HttpErrorResponse) => {
        this.error.set(e.status === 0 ? 'no response (status 0)' : `the server responded ${e.status}`);
        this.captcha.set(null);
        this.loading.set(false);
      },
    });
  }
}
<!-- ======================================================================
     ex22.page.html - ein vom Server angefordertes CAPTCHA
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>Example 22 - a first HTTP request</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <ion-note>Server: {{ server }}</ion-note>

  <!-- ein "unbestimmter" Fortschrittsbalken während der Anfrage -->
  @if (loading()) {
    <ion-progress-bar type="indeterminate" class="ion-margin-top" />
  }

  @if (error(); as error) {
    <ion-card class="error">
      <ion-card-content>
        Unable to get a captcha: {{ error }}.<br />
        Is the RdvMedecins JSON server running (port 8080)?
      </ion-card-content>
    </ion-card>
  }

  @if (captcha(); as captcha) {
    @if (!loading()) {
      <!-- das SVG-Bild in Form einer data:-Adresse (siehe common/types.ts) -->
      <div class="image ion-margin-top">
        <img [src]="captchaImage(captcha)" alt="captcha" />
      </div>
      <div class="id">id: {{ captcha.id }}</div>
    }
  }

  <!-- deaktiviert während einer Anfrage -->
  <ion-button class="ion-margin-top" shape="round" [disabled]="loading()" (click)="load()">Another image</ion-button>
  <p><ion-note>{{ requestCount() }} successful request(s)</ion-note></p>
</ion-content>
  • Zeile 19 (.ts): [HttpClient], der HTTP-Client von [Angular]. Er wird der gesamten Anwendung durch [provideHttpClient()] in [main.ts] bereitgestellt, und die Seite erhält ihn über [inject(HttpClient)] (Zeile 44);
  • Zeile 45 (.ts): die Serveradresse, oben auf dem Bildschirm angezeigt; eine leere Adresse bedeutet „derselbe Ursprung“;
  • Zeilen 49–52 (.ts): der Bildschirmzustand, durch Signals dargestellt: das empfangene CAPTCHA (oder [null]), die drei Anfragezustände (läuft, Fehler, erfolgreich) und die Anzahl erfolgreicher Anfragen;
  • Zeile 55 (.ts): das Abonnement ([Subscription]) der aktuellen Anfrage;
  • Zeilen 57–61 (.ts): Die erste Anfrage wird gesendet, sobald die Seite geladen ist. [DestroyRef] meldet, wann die Seite geschlossen wird (Zurück-Schaltfläche): Das Abonnement der aktuellen Anfrage wird dann abgebrochen;
  • Zeilen 63–86 (.ts): die Anfrage:
  • Zeile 71 (.ts): [this.http.get<Captcha>(address)] sendet die Anfrage noch nicht; es gibt ein [Observable] (Beispiel 19) der Antwort zurück. Die Anfrage wird gesendet, wenn ein Abonnement abgeschlossen wird ([subscribe]). Der Typ [<Captcha>] ist der des erwarteten JSON-Bodys: ein dem Compiler gegebenes Versprechen, das zur Laufzeit nicht geprüft wird;
  • Zeilen 73–77 (.ts): [next] erhält die Antwort, wenn ihr Statuscode 2xx ist. Ihr JSON-Body ist bereits dekodiert: Es ist ein [JavaScript]-Objekt (das Paket [http] von [Flutter] lieferte Text, der an [jsonDecode] übergeben werden musste);
  • Zeilen 80–84 (.ts): [error] erhält eine [HttpErrorResponse], die entweder eine Fehlerantwort (4xx, 5xx) oder keine Antwort anzeigt (Server nicht erreichbar, falsche Adresse, Netzwerkausfall). Unterschieden wird dies durch [e.status], das 0 ist, wenn der Server nicht geantwortet hat. Das unterscheidet sich von [http.get] bei [Flutter], das eine Antwort 4xx oder 5xx als gewöhnliche Antwort behandelte, sodass der Code zu prüfen war;
  • Zeile 66 (.ts): Ist die vorherige Anfrage nicht abgeschlossen, wird sie verworfen: Das Beenden des Abonnements einer HTTP-Anfrage bricht sie ab (der Browser unterbricht sie), und ihre Antwort wird nie verarbeitet. Hier zeigt [Observable] seinen Vorteil gegenüber [Promise], das sich nicht abbrechen lässt: Das [Flutter]-Beispiel musste seine Anfragen nummerieren, um veraltete Antworten zu ignorieren;
  • Zeilen 18–20 (html): eine Fortschrittsleiste ([<ion-progress-bar type="indeterminate">]) während der Anfrage;
  • Zeilen 22–29 (html): der Fehler, in einer Karte angezeigt;
  • Zeilen 31–39 (html): das CAPTCHA. [@if (captcha(); as captcha)] weist dem Wert des Signals einen Namen zu, wenn er nicht [null] ist;
  • Zeile 35 (html): Das CAPTCHA-Bild ist ein SVG in Textform. Ein [<img>]-Tag kann es anzeigen, sofern es als URL übergeben wird; dies ist die Aufgabe der Funktion [captchaImage] in [common/types.ts]:
// der SVG-Text -> eine "data:"-Adresse, die mit <img [src]> verwendbar ist: Das Bild
// steckt IN der Adresse. Ein von <img> angezeigtes SVG-Bild kann kein
// Skript ausführen: kein Risiko, selbst wenn sein Inhalt zweifelhaft wäre
export function captchaImage(c: Captcha): string {
  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(c.svg)}`;
}
  • Zeile 32: Eine [data:]-Adresse enthält die Datei selbst: ihren Typ ([image/svg+xml]), gefolgt von ihrem Inhalt, kodiert durch [encodeURIComponent] , damit er in einer Adresse erscheinen kann. Warum den SVG-Text nicht direkt mit [[innerHTML]] in die Seite einfügen? [Angular] würde ihn ablehnen: Ein SVG kann Skripte enthalten, und [Angular] „bereinigt“ jedes auf diese Weise eingefügte HTML, indem es Tags entfernt, die es nicht als sicher erkennt, darunter [<svg>]. Wir könnten es erzwingen ([DomSanitizer.bypassSecurityTrustHtml]), aber ein Bild ist einfacher und risikofrei: Ein von [<img>] angezeigtes Bild führt nie Skripte aus. Bei [Flutter] war es das Paket [flutter_svg], das das SVG darstellte;
  • Zeile 42 (html): „Anderes Bild“, während einer Anfrage deaktiviert.

Im Browser, über den [ng serve]-Proxy; der Server antwortet dann nicht (für diesen Screenshot lässt das Aufnahmeskript die Anfrage fehlschlagen, genau wie es ein angehaltener Server täte):

Die Entwicklerwerkzeuge von [Chrome] (F12) zeigen auf dem Tab „Network“ jede HTTP-Anfrage der Anwendung mit ihren Headern und ihrem Body: hier [GET http://localhost:8100/api/captcha], über den Proxy übertragen. Auf dem Smartphone wird die Anwendung vom Computer aus unter der Adresse [chrome://inspect] untersucht (siehe Kapitel „Bereitstellung“); Anfragen, die über [CapacitorHttp] laufen – also über den nativen Code –, sind dort weniger gut sichtbar.

Der HTTP-Client von [Angular] bietet seit Version 19 außerdem [httpResource()]: das Gegenstück für eine GET-Anfrage zu [resource()] aus Beispiel 19. Sie übergeben die Adresse und erhalten ein Signal-Objekt zurück ([isLoading()], [value()], [error()], [reload()]): Die gesamte Verwaltung der drei Zustände dieses Beispiels könnte in einer einzigen Zeile stehen. Für eine erste Anfrage haben wir uns entschieden, diese Zustände selbst zu schreiben; die Fallstudie verwendet [resource()].

Der Server speichert den JWT-Token in einem Cookie. Der [Flutter]-Client musste an dieser Stelle seinen HTTP-Client durch einen ersetzen, der den [Set-Cookie]-Header jeder Antwort liest, die Cookies verwaltet (und auf dem Gerät speichert) und sie im [Cookie]-Header jeder Anfrage zurücksendet: Eine [Flutter]-Anwendung hat keinen Browser, der das für sie erledigt.

Eine [Ionic]-Anwendung muss dagegen nichts schreiben:

  • Im Browser des Computers speichert der Browser das Cookie und sendet es zurück, genau wie bei jeder anderen Website. Der [ng serve]-Proxy gibt der Anwendung und der API denselben Origin: Das [SameSite=Strict]-Cookie wird akzeptiert und zurückgesendet. Der Code der Anwendung kann dieses Cookie weder lesen noch schreiben ([HttpOnly]);
  • unter [Android] leitet das [CapacitorHttp]-Plugin (Beispiel 22) die Anfragen über den nativen Code. [Capacitor] richtet beim Start der Anwendung die Cookie-Verwaltung von [Android] (die der WebView) als Verwaltung für native Anfragen ein: Empfangene Cookies werden dort gespeichert und bei den folgenden Anfragen an denselben Server zurückgesendet. Sie bleiben auf dem Gerät erhalten (unseres hat eine Lebensdauer, die durch [Max-Age=7200] festgelegt ist; nur „Sitzungs“-Cookies ohne Ablaufzeit werden beim Start der App gelöscht): Sie bleiben angemeldet, wenn Sie die App schließen und wieder öffnen.

Der Token wird also nie vom Code der App bearbeitet und liegt auch nicht im Klartext auf dem Gerät (der [Flutter]-Client hatte ihn in [shared_preferences] gespeichert).

9.2.2. Ein Command

// =========================================================================
// src/app/ex23-login/command.ts - eine AKTION, ihr Zustand, ihr Ergebnis
// -------------------------------------------------------------------------
// Eine asynchrone Aktion (Anmelden, Speichern ...) hat einen Zustand, den
// der Bildschirm anzeigen muss: LÄUFT sie (Schaltfläche deaktiviert)? Ist sie
// mit einem FEHLER beendet worden (Meldung)? Es ist das Muster "Command" der
// Architekturleitfäden (etwa dem von Flutter), auf das Wesentliche reduziert:
//
//     readonly loginCommand = new Command();
//     this.loginCommand.execute(() => this.logIn());   // startet die Aktion
//     loginCommand.running(), loginCommand.error()      // ihr Zustand
//
// Ihr Zustand besteht aus SIGNALS: Das Template, das sie liest, wird aktualisiert,
// wenn der Command startet und wenn er endet.
// =========================================================================

import { signal } from '@angular/core';

export class Command {
  private readonly _running = signal(false);
  private readonly _error = signal<unknown>(null);
  readonly running = this._running.asReadonly();
  readonly error = this._error.asReadonly();

  // führt die Aktion aus, sofern nicht bereits eine andere läuft
  async execute(action: () => Promise<void>): Promise<void> {
    if (this._running()) return; // keine doppelte Übermittlung (doppeltes Tippen auf die Schaltfläche)
    this._running.set(true);
    this._error.set(null);
    try {
      await action();
    } catch (e) {
      this._error.set(e); // der Fehler wird BEHALTEN, um angezeigt zu werden
    } finally {
      // finally: in ALLEN Fällen ausgeführt, bei Erfolg wie bei Fehler
      this._running.set(false);
    }
  }

  clearError(): void {
    this._error.set(null);
  }
}

Eine asynchrone Aktion (anmelden, speichern usw.) hat einen Status, den der Bildschirm anzeigen muss: Läuft sie gerade (Schaltfläche deaktiviert)? Endete sie mit einem Fehler (Meldung)? Das ist das Muster „Command“ aus den Architekturleitfäden (in [Flutter] heißt es so), auf das Wesentliche reduziert. Der [React]-Kurs verwendete dafür die „Actions“ von [React] 19 ([useActionState]).

  • Zeilen 19–23: eine einfache Klasse (jeder Bildschirm erzeugt seine eigene mit [new]), deren Zustand aus zwei privaten Signalen besteht, die schreibgeschützt nach außen gegeben werden. Das Template, das [running()] oder [error()] liest, wird aktualisiert, wenn das Command startet und wenn es endet: Das ist die Rolle, die [ChangeNotifier] und [ListenableBuilder] in [Flutter] spielten;
  • Zeilen 26–38: eine Aktion ausführen: Läuft bereits eine andere Aktion, geschieht nichts (Zeile 27: verhindert doppeltes Absenden, wenn die Schaltfläche zweimal gedrückt wird); andernfalls wird das Command auf „läuft“ gesetzt; bei einer Exception wird der Fehler festgehalten, damit er angezeigt wird (Zeile 33); in jedem Fall ([finally], Zeilen 34–37) läuft das Command nicht mehr. Der Fehler hat den Typ [unknown]: In [JavaScript] kann jeder beliebige Wert geworfen werden, und [TypeScript] weiß deshalb nicht, was [catch] abfängt.

9.2.3. Der Bildschirm

// =========================================================================
// src/app/ex23-login/ex23.page.ts - Anmeldung am RdvMedecins-Server
// -------------------------------------------------------------------------
//   1. beim Start: GET /api/auth/me - sind wir bereits angemeldet?
//      (Die Anwendung wurde möglicherweise beendet; der Server liest seinerseits das Cookie,
//      das ihm vorgelegt wird);
//   2. Anmeldung: POST /api/auth/login, JSON-Body { login, password,
//      captchaId, captcha }. Bei Erfolg sendet der Server das Cookie
//      des JWT-Tokens (Header Set-Cookie);
//   3. geschützte Anfrage: GET /api/doctors. Das Cookie wird mitgeschickt;
//   4. Abmeldung: POST /api/auth/logout - der Server löscht das Cookie.
// Und das Cookie? Der Code hat NICHTS damit zu tun: In einem Browser speichert
// es der Browser und sendet es zurück; unter Android ist es der native Code
// (Plugin CapacitorHttp, siehe capacitor.config.ts).
// =========================================================================

import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { Component, inject, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonContent, IonHeader, IonInput, IonNote, IonText,
  IonTitle, IonToolbar,
} from '@ionic/angular';
import { firstValueFrom } from 'rxjs';
import { config } from '../common/config';
import { Captcha, captchaImage } from '../common/types';
import { Command } from './command';

// die wenigen Meldungen, die dieses Beispiel braucht (Beispiel 25 wird Wörterbücher verwenden)
const messages: Record<string, string> = {
  'LOGIN.ERROR': 'Incorrect login or password.',
  'ERRORS.WRONG_CAPTCHA': 'The characters you typed do not match the image.',
  'ERRORS.TOO_MANY_ATTEMPTS': 'Too many failed attempts. Try again later.',
};

// was POST /api/auth/login und GET /api/auth/me zurückgeben, und eine Zeile von GET /api/doctors
interface User {
  login: string;
  name: string;
  role: string;
}
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
}

@Component({
  selector: 'app-ex23',
  imports: [
    FormsModule, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonCard, IonCardContent,
    IonInput, IonButton, IonText, IonNote,
  ],
  templateUrl: './ex23.page.html',
  styles: `
    .captcha { display: flex; align-items: center; margin-top: 12px; }
    .captcha img { height: 50px; }
    .error { --background: #ffebee; --color: #333; }
    h3 { font-size: 14px; font-weight: bold; margin: 12px 0 4px; }
  `,
})
export class Ex23Page {
  private readonly http = inject(HttpClient);
  readonly captchaImage = captchaImage;

  readonly user = signal<User | null>(null); // null: niemand ist angemeldet
  readonly doctors = signal<Doctor[]>([]);
  readonly captcha = signal<Captcha | null>(null);
  readonly ready = signal(false); // ist die Startprüfung abgeschlossen?
  readonly serverError = signal<string | null>(null);
  readonly loginCommand = new Command();
  // die Felder des Formulars, per [(ngModel)] gebunden
  readonly login = signal('admin');
  readonly password = signal('');
  readonly captchaAnswer = signal('');

  constructor() {
    this.checkSession();
  }

  private url(path: string): string {
    return `${config.serverUrl}/api${path}`;
  }

  // eine GET-Anfrage, deren JSON-Body wir haben wollen. Eine Antwort, die keine
  // 2xx ist (oder das Ausbleiben einer Antwort), weist das Promise mit einer HttpErrorResponse zurück
  private read<T>(path: string): Promise<T> {
    return firstValueFrom(this.http.get<T>(this.url(path)));
  }

  // ein POST: Das Body-Objekt wird als JSON gesendet (Header content-type: application/json)
  private post<T>(path: string, body: object): Promise<T> {
    return firstValueFrom(this.http.post<T>(this.url(path), body));
  }

  async loadCaptcha(): Promise<void> {
    this.captcha.set(await this.read<Captcha>('/captcha'));
    this.captchaAnswer.set('');
  }

  private async loadDoctors(): Promise<void> {
    this.doctors.set(await this.read<Doctor[]>('/doctors'));
  }

  // 1. wer ist angemeldet? 200 -> der Benutzer; 401 -> niemand
  private async checkSession(): Promise<void> {
    try {
      this.user.set(await this.read<User>('/auth/me'));
      await this.loadDoctors();
    } catch (e) {
      // instanceof: ein TYP-Test; e.status: der Statuscode (0: keine Antwort)
      if (e instanceof HttpErrorResponse && e.status === 401) {
        await this.loadCaptcha();
      } else if (e instanceof HttpErrorResponse && e.status !== 0) {
        this.serverError.set(`The server responded ${e.status}.`);
      } else {
        this.serverError.set(`Is the RdvMedecins JSON server running (${config.serverUrl || 'port 8080'})?`);
      }
    }
    this.ready.set(true);
  }

  // die Schaltfläche "Anmelden": Der Command führt die Aktion aus und speichert ihren Fehler
  submit(): void {
    this.loginCommand.execute(() => this.logIn());
  }

  // 2. die Anmeldung
  private async logIn(): Promise<void> {
    try {
      const user = await this.post<User>('/auth/login', {
        login: this.login().trim(),
        password: this.password(),
        captchaId: this.captcha()?.id,
        captcha: this.captchaAnswer(),
      });
      this.password.set('');
      this.user.set(user);
      await this.loadDoctors();
    } catch (e) {
      if (!(e instanceof HttpErrorResponse)) throw e;
      // e.error: der JSON-Body der Fehlerantwort, { statusCode, key, ... }
      const key: string = e.error?.key ?? 'ERRORS.SERVER_UNREACHABLE';
      await this.loadCaptcha(); // jedes Bild wird nur einmal verwendet
      // der Fehler, den der Command behalten wird
      throw new Error(`${e.status} - ${messages[key] ?? key}`);
    }
  }

  // die Meldung des vom Command behaltenen Fehlers
  errorMessage(): string {
    const error = this.loginCommand.error();
    return error instanceof Error ? error.message : String(error);
  }

  // 4. die Abmeldung
  async logOut(): Promise<void> {
    await this.post('/auth/logout', {});
    this.user.set(null);
    this.doctors.set([]);
    await this.loadCaptcha();
  }
}
<!-- ======================================================================
     ex23.page.html - Login, Sitzung, Logout
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>Example 23 - logging in to the server</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  @if (!ready()) {
    <ion-note>Checking the session...</ion-note>
  } @else if (user(); as u) {
    <!-- angemeldet -->
    <ion-card>
      <ion-card-content>
        <div>Logged in: <strong>{{ u.name }}</strong> ({{ u.login }}), role {{ u.role }}</div>
        <!-- 3. eine geschützte Anfrage: Das Cookie wurde mitgeschickt -->
        <h3>GET /api/doctors</h3>
        @for (m of doctors(); track m.id) {
          <div>• {{ m.title }} {{ m.firstName }} {{ m.lastName }}</div>
        }
        <p class="ion-margin-top"><ion-note>Stop then restart the application: you stay logged in.</ion-note></p>
        <ion-button fill="outline" shape="round" (click)="logOut()">Log out</ion-button>
      </ion-card-content>
    </ion-card>
  } @else if (serverError() === null) {
    <!-- nicht angemeldet: das Formular -->
    <ion-card>
      <ion-card-content>
        <ion-input label="Login" labelPlacement="floating" [(ngModel)]="login" />
        <ion-input label="Password" labelPlacement="floating" type="password" [(ngModel)]="password" />
        <div class="captcha">
          @if (captcha(); as c) {
            <img [src]="captchaImage(c)" alt="captcha" />
          }
          <ion-button fill="clear" size="small" (click)="loadCaptcha()">Another image</ion-button>
        </div>
        <ion-input label="Copy the characters of the image" labelPlacement="floating" autocorrect="off"
          autocapitalize="off" [(ngModel)]="captchaAnswer" />
        <!-- die Schaltfläche folgt dem Zustand des Commands -->
        <ion-button class="ion-margin-top" shape="round" [disabled]="loginCommand.running()"
          (click)="submit()">
          {{ loginCommand.running() ? 'Logging in...' : 'Log in' }}
        </ion-button>
        @if (loginCommand.error() !== null) {
          <p><ion-text color="danger">{{ errorMessage() }}</ion-text></p>
        }
        <p><ion-note>Accounts: admin, pelissier, martin... (password = login).</ion-note></p>
      </ion-card-content>
    </ion-card>
  }

  @if (serverError(); as message) {
    <ion-card class="error">
      <ion-card-content>{{ message }}</ion-card-content>
    </ion-card>
  }
</ion-content>

Der Bildschirm durchläuft die vier Phasen einer Sitzung: beim Start, wer ist angemeldet?; die Anmeldung; eine gesicherte Anfrage; und die Abmeldung.

  • Zeilen 29–34 (.ts): die wenigen Meldungen, die dieses Beispiel benötigt (Beispiel 25 verwendet Wörterbücher);
  • Zeilen 36–47 (.ts): das Format der verwendeten Antworten, beschrieben durch zwei Interfaces (Beispiel 24 legt diese Typen in [common/types.ts] ab);
  • Zeilen 67–76 (.ts): der Zustand: der angemeldete Benutzer ([null]: niemand), die Ärzte, das CAPTCHA, der Abschluss der Anfangsprüfung, ein Serverfehler, das Anmelde-Command und die Formularfelder;
  • Zeilen 86–95 (.ts): zwei Abkürzungen. [firstValueFrom(observable)] (aus [RxJS]) abonniert das [Observable] der Anfrage und liefert ein [Promise] mit dessen erstem Wert, der Antwort: Auf sie kann dann mit [await] gewartet werden, in Code, der sich von oben nach unten liest. Schlägt die Anfrage fehl, wird das [Promise] mit der [HttpErrorResponse] abgelehnt, und [await] wirft sie als Exception. Bei einem POST (Zeile 94) ist der Body ein Objekt: Der HTTP-Client sendet es als JSON, mit dem vom Server verlangten Header [Content-Type: application/json] (andernfalls: 415);
  • Zeilen 107–122 (.ts): 1. Beim Start, wer ist angemeldet? [GET /api/auth/me]: 200, der Benutzer (gefolgt von der Liste der Ärzte); 401 (Zeile 113), niemand: Für das Formular wird ein CAPTCHA geladen. [e instanceof HttpErrorResponse] ist eine Typprüfung: In dem Zweig, in dem sie wahr ist, weiß [TypeScript], dass [e] ein [status]-Feld hat. Ein anderer Fehlercode (Zeilen 115–116) oder gar keine Antwort (Zeilen 117–119, [status] 0): eine Meldung;
  • Zeilen 125–127 (.ts): Die Schaltfläche „Anmelden“ delegiert die Aktion an das Command;
  • Zeilen 130–149 (.ts): 2. die Anmeldung: [POST /api/auth/login]. Bei Erfolg hat der Browser (oder [Android]) das Cookie gespeichert: Der Benutzer wird übernommen, und die Ärzte werden geladen. Schlägt die Anmeldung fehl, ist [e.error] der bereits dekodierte Body der Fehlerantwort: Er enthält den Schlüssel message (Zeile 144; [?.] und [??]: ein Ersatzschlüssel, falls der Body keinen enthält). Ein neues Bild wird geladen (jedes wird nur einmal verwendet), dann wird ein Fehler ausgelöst, dessen Meldung angezeigt wird (Zeile 147): Das Command fängt ihn ab und speichert ihn. Eine Exception, die keine [HttpErrorResponse] ist (eine Anomalie), wird unverändert erneut geworfen (Zeile 142);
  • Zeilen 152–155 (.ts): die vom Command festgehaltene Fehlermeldung;
  • Zeilen 158–163 (.ts): 4. Abmeldung: [POST /api/auth/logout]; der Server löscht das Cookie (er sendet ein leeres, bereits abgelaufenes Cookie), und der Browser vergisst es;
  • Zeilen 15–16 (html): solange die Anfangsprüfung nicht abgeschlossen ist;
  • Zeilen 17–30 (html): 3. angemeldet: der Benutzer und die Liste der Ärzte ([GET /api/doctors], eine geschützte Anfrage: Das Cookie wurde ohne eine einzige Codezeile mitgesendet);
  • Zeilen 31–55 (HTML): nicht angemeldet: das Formular. Die Felder sind über [[(ngModel)]] (Beispiel 05) an die Signale gebunden; das CAPTCHA wird wie in Beispiel 22 angezeigt (Zeilen 38–40);
  • Zeilen 46–52 (HTML): Die Schaltfläche spiegelt den Status der Anfrage wider: deaktiviert und „Anmeldung läuft...“, solange die Anfrage gesendet wird; eine eventuelle Fehlermeldung erscheint darunter;
  • Zeilen 58–62 (HTML): Der Server antwortet nicht.

Der Anmeldebildschirm; ein falsches Passwort; erfolgreiche Anmeldung:

Laden Sie die Browserseite neu (oder schließen und öffnen Sie auf einem Smartphone die App): Sie öffnet sich im angemeldeten Zustand. Das Cookie, vom Browser (oder von [Android]) gespeichert, wird an [GET /api/auth/me] gesendet, und der Server antwortet mit den Daten des Benutzers. Der Token läuft nach zwei Stunden ab: [GET /api/auth/me] liefert dann eine 401-Antwort, und der Anmeldebildschirm erscheint wieder.

9.3. Beispiel 24: Eine Zugriffsschicht für die API

In Beispiel 23 wiederholte jede Anfrage dieselben Schritte. Dieses Beispiel ordnet sie in drei Schichten, auf die die Fallstudie zurückkommt.

9.3.1. Die Typen

// =========================================================================
// src/app/common/types.ts - die mit der RdvMedecins-API ausgetauschten JSON-Objekte
// (siehe das Kapitel zur Blackbox, das jede Route beschreibt)
// -------------------------------------------------------------------------
// Die Übersetzung der Antworten des Servers in TypeScript-Typen. Sie sind
// nur BESCHREIBUNGEN: Sie verschwinden beim Kompilieren und prüfen
// zur Laufzeit nichts. Sie lassen den Compiler
// prüfen, dass der Code nur existierende Felder mit dem richtigen
// Typ verwendet (und lassen den Editor ihre Namen vorschlagen).
// =========================================================================

// ein "Union-Typ" aus Zeichenketten: Nur diese drei Werte sind erlaubt
export type Role = 'ADMIN' | 'DOCTOR' | 'USER';

// POST /api/auth/login, GET /api/auth/me
export interface User {
  login: string;
  name: string; // angezeigter Name: "Marie PELISSIER"
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string; // das Bild im SVG-Format (Text)
}

// der SVG-Text -> eine "data:"-Adresse, die mit <img [src]> verwendbar ist: Das Bild
// steckt IN der Adresse. Ein von <img> angezeigtes SVG-Bild kann kein
// Skript ausführen: kein Risiko, selbst wenn sein Inhalt zweifelhaft wäre
export function captchaImage(c: Captcha): string {
  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(c.svg)}`;
}

// der Name einer Person, sonst nichts
export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// ein Arzt oder ein Client (GET /api/doctors, GET /api/clients ...)
// "extends": Eine Person hat alle Felder einer Identity und weitere
export interface Person extends Identity {
  id: number;
  version: number; // optimistisches Sperren: wird bei einer Änderung zurückgesendet
  login?: string; // optional (?): nur für den ADMIN
}

// "Mme Alice DURAND"
export function fullName(i: Identity): string {
  return `${i.title} ${i.firstName} ${i.lastName}`;
}

// eine Zeile von GET /api/schedule: ein Zeitfenster und die RECHTE des angemeldeten Benutzers
export interface ScheduleSlot {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
  free: boolean;
  patient: Identity | null; // null: frei oder von einem anderen Patienten belegt
  mine: boolean; // der Termin des angemeldeten Patienten
  bookable: boolean;
  appointmentId: number | null; // gesetzt, wenn der Benutzer stornieren kann
}

// "8:00 - 8:20"
export function timeRange(c: ScheduleSlot): string {
  const hm = (h: number, m: number) => `${h}:${String(m).padStart(2, '0')}`;
  return `${hm(c.startHour, c.startMinute)} - ${hm(c.endHour, c.endMinute)}`;
}

// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
  doctor: Person;
  day: string; // "yyyy-MM-dd"
  slots: ScheduleSlot[];
  info: string | null; // Übersetzungsschlüssel (Patient, der bereits einen Termin hat)
}

Die Antworten des Servers, in [TypeScript] beschrieben. Es handelt sich lediglich um Beschreibungen: Die Interfaces werden beim Kompilieren entfernt und führen zur Laufzeit keine Prüfungen durch. Sie erlauben dem Compiler zu prüfen, dass der Code nur vorhandene Felder mit dem richtigen Typ verwendet, und dem Editor, deren Namen vorzuschlagen.

  • Zeile 13: ein String-Union-Typ: Einer Variablen vom Typ [Role] kann nur einer dieser drei Strings zugewiesen werden. Der Compiler lehnt [role === 'ADMN'] ab;
  • Zeilen 16–20: der angemeldete Benutzer ([POST /api/auth/login], [GET /api/auth/me]);
  • Zeilen 44–48: eine Person (Arzt oder Kunde). [extends Identity]: Sie hat alle Felder einer [Identity] (Zeilen 36–40) und weitere; [login?]: ein optionales Feld (nur der ADMIN erhält es);
  • Zeilen 56–67: ein Eintrag im Terminkalender. [Identity | null], [number | null]: Zusammen mit ["strict": true] und [TypeScript] verlangt dies, diese Werte vor ihrer Verwendung zu prüfen;
  • Zeilen 51–53, 70–73: Formatierungsfunktionen: „Mme Alice DURAND“, „8:00 – 8:20“. Es sind keine Methoden: Die vom Server empfangenen Objekte sind gewöhnliche [JavaScript]-Objekte ohne Klasse;
  • Zeilen 76–81: der Terminkalender eines Arztes für einen Tag.

Das ist ein grundlegender Unterschied zum [Flutter]-Client. In [Dart] hat das dekodierte JSON keinen Typ ([dynamic]): Jede Klasse hatte einen Konstruktor [fromJson], der prüfte das Format des empfangenen JSON durch Filtern mit [Dart] 3 („Pattern Matching“) und es in ein Objekt umwandelte. Hier glaubt der Compiler, was man ihm sagt ([http.get<Schedule>(...)]): Eine unerwartete Antwort würde erst bemerkt, wenn die Anzeige auf ein fehlendes Feld stößt. Bei einem Server unter unserer Kontrolle ist das übliche Praxis. Bei einer externen API würden wir die Antworten mit einer Bibliothek für „Schemas“ prüfen ([Zod], [Valibot]), die zur Laufzeit leistet, was früher das Filtern in [Dart] leistete.

9.3.2. Fehler

// =========================================================================
// src/app/common/api-error.ts - EINE Klasse für alle Fehler der API
// -------------------------------------------------------------------------
// Alle Fehlerantworten des RdvMedecins-Servers haben dieselbe Form:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Eine Anfrage kann aber auch ANDERS scheitern: gar keine Antwort
// (Netz ausgefallen, Server gestoppt, falsche Adresse) oder eine Antwort, die nicht
// von unserem Server stammt (eine Fehlerseite eines Proxys). Der HTTP-Client
// von Angular meldet alle diese Fehlschläge mit einer HttpErrorResponse; wir
// wandeln sie in EINE Klasse um, ApiError, die den vom Server gesendeten
// Übersetzungsschlüssel trägt (und gegebenenfalls seine Parameter und den Fehler
// jedes Felds).
// =========================================================================

import { HttpErrorResponse } from '@angular/common/http';

// ein Objekt { name: Text }
export type Texts = Record<string, string>;

// "extends Error": ein vollwertiger JavaScript-Fehler, den wir auslösen
// (throw) und abfangen (catch); message lautet "409 ERRORS.LOGIN_TAKEN"
export class ApiError extends Error {
  constructor(
    readonly statusCode: number, // 0: Der Server hat nicht geantwortet
    readonly key: string, // z. B.: 'ERRORS.LOGIN_TAKEN'
    readonly params: Texts = {},
    readonly fields: Texts = {},
  ) {
    super(`${statusCode} ${key}`);
    this.name = 'ApiError';
  }

  // eine Fehlerantwort des HTTP-Clients von Angular -> ein ApiError
  static fromResponse(response: HttpErrorResponse): ApiError {
    // Status 0: keine Antwort (Netz ausgefallen, Server gestoppt, falsche Adresse)
    if (response.status === 0) {
      return new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
    }
    // error: der Body der Antwort, bereits dekodiert, wenn es JSON ist
    const body: unknown = response.error;
    if (isObject(body) && typeof body['key'] === 'string') {
      return new ApiError(response.status, body['key'], texts(body['params']), texts(body['fields']));
    }
    // kein key: Der Proxy oder das Netz hat an seiner Stelle geantwortet
    return new ApiError(
      response.status,
      response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
    );
  }
}

// ein "Type Guard": Liefert die Funktion true, weiß TypeScript, dass
// value ein Objekt ist, dessen Eigenschaften gelesen werden können
function isObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// ein JSON-Objekt { "name": "ERRORS..." } -> Texts (sonst leer)
function texts(json: unknown): Texts {
  if (!isObject(json)) return {};
  return Object.fromEntries(Object.entries(json).map(([key, value]) => [key, String(value)]));
}

Alle Fehlerantworten des Servers haben dasselbe Format. Eine Anfrage kann jedoch auch ANDERS scheitern: gar keine Antwort oder eine Antwort, die nicht von unserem Server stammt. Der HTTP-Client von [Angular] meldet alle diese Fehlschläge als [HttpErrorResponse]; wir wandeln sie in EINE Klasse um, [ApiError].

  • Zeile 18: [Record<string, string>]: ein Objekt, dessen Eigenschaften Strings sind;
  • Zeilen 22–31: [extends Error]: ein vollwertiger [JavaScript]-Fehler, der geworfen ([throw]) und abgefangen ([catch]) wird, samt seinem Aufrufstapel. Die Konstruktorparameter mit vorangestelltem [readonly] deklarieren und initialisieren die Felder (eine Kurzschreibweise von [TypeScript]): einen Status (0: keine Antwort), einen Übersetzungsschlüssel, dessen Parameter und den Fehler je Feld. Die Fehlermeldung (Zeile 29) lautet „401 LOGIN.ERROR“, für eine schnelle Anzeige;
  • Zeilen 34–49: eine [HttpErrorResponse] → ein [ApiError]. Status 0: keine Antwort (Zeilen 36–38). Andernfalls ist [response.error] der Body der Antwort, bereits dekodiert, wenn es JSON ist (Zeile 40); hat er einen Schlüssel [key] vom Typ String, hat unser Server geantwortet (Zeilen 41–42). Andernfalls hat ein Zwischenglied (Proxy, Netzwerk) an seiner Stelle geantwortet (Zeilen 45–48);
  • Zeilen 54–56: ein Type Guard ([value is Record<string, unknown>]) – eine Funktion, deren Ergebnis [true] dem Compiler den Typ ihres Parameters mitteilt. Nach [isObject(body)] weiß er, dass [body] ein Objekt ist, dessen Eigenschaften gelesen werden können. Das erledigte in [Dart] die „if-case“-Anweisung in einem Schritt;
  • Zeilen 59–62: ein JSON-Objekt { "name": "ERRORS..." } → Text (leer, wenn es kein Objekt ist).

9.3.3. Die Anfragen

// =========================================================================
// src/app/common/api.ts - Anfragen an die API, in einer Zeile
// -------------------------------------------------------------------------
// In Beispiel 23 wiederholte jede Anfrage dieselben Schritte: Adresse des
// Servers, Präfix /api, Umwandlung des Observable in ein Promise, Lesen
// des Fehler-Bodys ... Wir fassen sie hier in einem SERVICE zusammen:
//
//   const doctors = await this.api.get<Person[]>('/doctors');
//   await this.api.post('/appointments', { day, slotId: 3 });
//
//   - bei Erfolg liefert das Promise den DEKODIERTEN JSON-Body;
//   - bei einem Fehlschlag wird es mit einem ApiError zurückgewiesen.
// Alle Anfragen laufen über die Methode request: Hier würden wir ein Problem behandeln,
// das ALLEN gemeinsam ist (siehe die Fallstudie und die
// Antwort 401). Verwendet von den Beispielen 24 und 25.
// =========================================================================

import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { inject, Injectable } from '@angular/core';
import { firstValueFrom } from 'rxjs';
import { config } from './config';
import { ApiError } from './api-error';

export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

// providedIn: 'root': eine einzige Instanz für die gesamte Anwendung
@Injectable({ providedIn: 'root' })
export class Api {
  private readonly http = inject(HttpClient);

  // <T>: der Typ der erwarteten Antwort, vom Aufrufer gewählt
  async request<T>(method: Method, url: string, body?: unknown): Promise<T> {
    try {
      // http.request liefert ein Observable; firstValueFrom wandelt es in ein
      // Promise um (die Anfrage wird in diesem Moment gesendet). Ein Body-Objekt wird
      // als JSON gesendet (Header content-type: application/json, den der Server bei
      // einem POST verlangt); die JSON-Antwort wird dekodiert (null, wenn ihr Body leer ist)
      return await firstValueFrom(this.http.request<T>(method, `${config.serverUrl}/api${url}`, { body }));
    } catch (e) {
      // der HTTP-Client meldet JEDEN Fehlschlag (4xx, 5xx, keine Antwort) mit einer
      // HttpErrorResponse: Wir wandeln sie um. Der Rest (eine Anomalie) wird unverändert durchgereicht
      throw e instanceof HttpErrorResponse ? ApiError.fromResponse(e) : e;
    }
  }

  get<T>(url: string): Promise<T> {
    return this.request<T>('GET', url);
  }

  // ein POST hat immer einen JSON-Body: standardmäßig {}
  post<T>(url: string, body: unknown = {}): Promise<T> {
    return this.request<T>('POST', url, body);
  }

  put<T>(url: string, body: unknown): Promise<T> {
    return this.request<T>('PUT', url, body);
  }

  delete<T>(url: string, body?: unknown): Promise<T> {
    return this.request<T>('DELETE', url, body);
  }
}

Ein Service (Beispiel 14), der ein für alle Mal die in Beispiel 23 wiederholten Schritte ausführt:

  • Zeile 27: [@Injectable({ providedIn: 'root' })]: eine einzige Instanz für die gesamte Anwendung, die bei der ersten Anforderung erzeugt wird;
  • Zeilen 32–44: ALLE Anfragen laufen über diese Methode: die Serveradresse und das Präfix [/api], der Body als JSON ([http.request] akzeptiert alle Methoden und sogar bei einem DELETE einen Body), die dekodierte und abgewartete Antwort mit [firstValueFrom] (Zeile 38), in [ApiError] umgewandelte Fehler (Zeile 42). Der Antworttyp [<T>] wird vom Aufrufer gewählt ([api.get<Person[]>('/doctors')]). Hier würde ein allen Anfragen gemeinsames Problem behandelt (siehe die Fallstudie sowie die 401-Antwort bei einer abgelaufenen Sitzung, die in einem HTTP-Interceptor des Clients behandelt wird);
  • Zeilen 46–61: vier Abkürzungen. Ein POST hat immer einen JSON-Body: [{}] als Standardwert (Zeile 51).

9.3.4. Eine Anmeldeleiste

// =========================================================================
// src/app/common/login-bar.ts - Anmeldung / Abmeldung, in einer Leiste
// -------------------------------------------------------------------------
// Das Formular aus Beispiel 23, auf eine Leiste reduziert und mit dem
// Service Api neu geschrieben. Die Komponente sendet das Ereignis userChange mit
// dem angemeldeten Benutzer (oder null) bei jeder Änderung - auch
// beim Start, nach der Abfrage von GET /api/auth/me:
//
//     <app-login-bar (userChange)="onUserChange($event)" />
//
// Der Service Api wird per Dependency Injection (inject) bezogen.
// =========================================================================

import { Component, inject, output, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { IonButton, IonCard, IonCardContent, IonIcon, IonInput, IonLabel, IonText } from '@ionic/angular';
import { addIcons } from 'ionicons';
import { logInOutline, person } from 'ionicons/icons';
import { Api } from './api';
import { ApiError } from './api-error';
import { Captcha, captchaImage, User } from './types';

@Component({
  selector: 'app-login-bar',
  imports: [FormsModule, IonCard, IonCardContent, IonInput, IonButton, IonIcon, IonLabel, IonText],
  templateUrl: './login-bar.html',
  styles: `
    ion-card { --background: #eceff1; margin: 0 0 8px; }
    ion-card-content { padding: 8px 12px; }
    .line { display: flex; align-items: center; gap: 8px; }
    .line > ion-input, .line > ion-label { flex: 1; }
    img { height: 40px; }
    .error { font-size: 13px; }
  `,
})
export class LoginBar {
  private readonly api = inject(Api);
  readonly captchaImage = captchaImage;

  // das an das Elternelement gesendete Ereignis: der angemeldete Benutzer oder null
  readonly userChange = output<User | null>();

  readonly user = signal<User | null>(null);
  readonly captcha = signal<Captcha | null>(null);
  readonly login = signal('admin');
  readonly password = signal('');
  readonly captchaAnswer = signal('');
  readonly error = signal<string | null>(null);

  constructor() {
    addIcons({ person, logInOutline });
    this.start();
  }

  private change(u: User | null): void {
    this.user.set(u);
    this.userChange.emit(u);
  }

  private async newCaptcha(): Promise<void> {
    this.captcha.set(await this.api.get<Captcha>('/captcha'));
    this.captchaAnswer.set('');
  }

  // beim Start: sind wir bereits angemeldet?
  private async start(): Promise<void> {
    try {
      this.change(await this.api.get<User>('/auth/me'));
    } catch {
      this.change(null); // 401: Niemand ist angemeldet
      try {
        await this.newCaptcha();
      } catch {
        this.error.set('Is the JSON server running (port 8080)?');
      }
    }
  }

  async logIn(): Promise<void> {
    this.error.set(null);
    try {
      const u = await this.api.post<User>('/auth/login', {
        login: this.login().trim(),
        password: this.password(),
        captchaId: this.captcha()?.id,
        captcha: this.captchaAnswer(),
      });
      this.password.set('');
      this.change(u);
    } catch (e) {
      // e.message: "401 LOGIN.ERROR" (Beispiel 25 wird den Schlüssel übersetzen)
      this.error.set(e instanceof ApiError ? e.message : String(e));
      await this.newCaptcha();
    }
  }

  async logOut(): Promise<void> {
    await this.api.post('/auth/logout');
    this.change(null);
    await this.newCaptcha();
  }
}
<!-- ======================================================================
     login-bar.html - der angemeldete Benutzer oder ein kleines Formular
     ====================================================================== -->

<ion-card>
  <ion-card-content>
    @if (user(); as u) {
      <div class="line">
        <ion-icon name="person" />
        <ion-label>{{ u.name }} ({{ u.role }})</ion-label>
        <ion-button fill="clear" size="small" (click)="logOut()">Log out</ion-button>
      </div>
    } @else {
      <div class="line">
        <ion-input label="login" labelPlacement="floating" [(ngModel)]="login" />
        <ion-input label="password" labelPlacement="floating" type="password" [(ngModel)]="password" />
      </div>
      <div class="line">
        <!-- das SVG-Bild des CAPTCHA, von UNSEREM Server erzeugt (siehe Beispiel 22) -->
        @if (captcha(); as c) {
          <img [src]="captchaImage(c)" alt="captcha" />
        }
        <ion-input label="captcha" labelPlacement="floating" autocorrect="off" autocapitalize="off"
          [(ngModel)]="captchaAnswer" (keyup.enter)="logIn()" />
        <ion-button fill="clear" aria-label="Log in" (click)="logIn()">
          <ion-icon slot="icon-only" name="log-in-outline" />
        </ion-button>
      </div>
      @if (error(); as message) {
        <ion-text color="danger"><div class="error">{{ message }}</div></ion-text>
      }
    }
  </ion-card-content>
</ion-card>

Das Formular aus Beispiel 23, auf eine Leiste reduziert und mit dem Service [Api] neu geschrieben. Die Komponente sendet das Ereignis [userChange] aus, sobald sich der angemeldete Benutzer ändert, auch beim Start.

  • Zeile 37 (.ts): der Service [Api], per Injektion bezogen ([provider] aus [Flutter]);
  • Zeile 41 (.ts): [output<User | null>()]: ein Ereignis, das die Komponente an ihre übergeordnete Komponente sendet (Beispiel 11) und das diese über [(userChange)="..."] abonniert;
  • Zeilen 55–58 (.ts): ein Benutzerwechsel: Wir merken ihn uns und benachrichtigen die übergeordnete Komponente ([emit]);
  • Zeilen 66–77 (.ts): beim Start, wer ist angemeldet? [await this.api.get<User>('/auth/me')]: eine einzige Zeile. Jeder Fehler bedeutet „niemand“: Es wird dann ein CAPTCHA geladen; schlägt auch das fehl, antwortet der Server nicht. [catch] ohne Variable: Der Fehler selbst wird nicht verwendet;
  • Zeilen 79–95 (.ts): der Anmeldevorgang in wenigen Zeilen: Fehler erscheinen als [ApiError], und die Meldung wird angezeigt („401 LOGIN.ERROR“: Beispiel 25 erklärt den Schlüssel);
  • Zeilen 7–12 (html): angemeldet: der Benutzer mit seiner Rolle und die Schaltfläche „Abmelden“;
  • Zeilen 13–31 (HTML): das Formular, auf zwei Zeilen verteilt ([display: flex]); die Eingabetaste im CAPTCHA-Feld sendet das Formular ab ([(keyup.enter)], Zeile 24); die Schaltfläche hat nur ein Symbol und für Screenreader einen Namen ([aria-label]).

9.3.5. Die Zugriffsschicht für die API

// =========================================================================
// src/app/ex24-api-layer/rdvmedecins.ts - die Zugriffsschicht auf die API
// -------------------------------------------------------------------------
// Eine Methode pro Route der API, typisiert. Die Bildschirme kennen weder die
// Adressen noch den HTTP-Client noch das JSON-Format: Sie rufen
// Methoden auf, die typisierte Objekte zurückgeben (Person, Schedule ...).
// Es ist das clientseitige Gegenstück zur DAO-Schicht auf der Serverseite: Ändert sich die API
// (eine Adresse, ein Feldname), ändern wir nur diese Datei.
// Die Architekturleitfäden nennen diese Schicht ein "Repository".
// =========================================================================

import { HttpParams } from '@angular/common/http';
import { inject, Injectable } from '@angular/core';
import { Api } from '../common/api';
import { Schedule, Person } from '../common/types';

@Injectable({ providedIn: 'root' })
export class RdvMedecins {
  private readonly api = inject(Api);

  getDoctors(): Promise<Person[]> {
    return this.api.get<Person[]>('/doctors');
  }

  getClients(): Promise<Person[]> {
    return this.api.get<Person[]>('/clients');
  }

  // HttpParams erzeugt "doctorId=1&day=2030-01-15" und kodiert dabei, was nötig ist
  getSchedule(doctorId: number, day: string): Promise<Schedule> {
    const params = new HttpParams().set('doctorId', doctorId).set('day', day);
    return this.api.get<Schedule>(`/schedule?${params.toString()}`);
  }

  // clientId?: ein optionaler Parameter. ...(condition && object): die
  // Eigenschaft clientId wird nur dann in den Body aufgenommen, wenn clientId angegeben ist
  async book(day: string, slotId: number, clientId?: number | null): Promise<void> {
    await this.api.post('/appointments', { day, slotId, ...(clientId != null && { clientId }) });
  }

  async cancelAppointment(appointmentId: number): Promise<void> {
    await this.api.delete(`/appointments/${appointmentId}`);
  }
}

Eine typisierte Methode pro Route der API. Die Bildschirme kennen weder Adressen noch den HTTP-Client noch das JSON-Format: Sie rufen Methoden auf, die typisierte Objekte zurückgeben. Ändert sich die API (eine Adresse, ein Feldname), muss nur diese Datei angepasst werden. Die Architekturleitfäden bezeichnen diese Schicht als „Repository“.

  • Zeile 19: Die Schicht stützt sich auf den Service [Api], den sie per Injektion bezieht: [Angular] setzt die Schichten selbst zusammen, während das [main] des [Flutter]-Clients sie einzeln erzeugte ([RdvMedecins(api)]);
  • Zeile 31: [HttpParams] erzeugt den String „doctorId=1&day=2030-01-15“, indem es die nötigen Daten kodiert;
  • Zeile 38: [clientId] wird nur in den Body aufgenommen, wenn es angegeben ist. [...(condition && object)]: Ist die Bedingung falsch, wird [false] „expandiert“, was nichts hinzufügt; andernfalls wird das Objekt [{ clientId }] (Kurzform von [{ clientId: clientId }]) expandiert. In [?clientId] war es das in [Dart] 3.8. [clientId != null] (mit [!=] und nicht [!==]) schließt sowohl [null] als auch [undefined] aus.

9.3.6. Das View-Model

// =========================================================================
// src/app/ex24-api-layer/schedule-model.ts - das "View Model" des Bildschirms
// -------------------------------------------------------------------------
// Die Architekturleitfäden empfehlen, Folgendes zu trennen:
//   - die VIEW: das Template und seine Klasse, die anzeigen und die Aktionen des
//     Benutzers weitergeben;
//   - das VIEW MODEL (ViewModel): ein Service, der den Zustand des
//     Bildschirms (der gewählte Arzt, der Tag, der erhaltene Terminkalender ...) in
//     SIGNALS enthält, die Aktionen (wählen, buchen, stornieren) und der die
//     Zugriffsschicht auf die API aufruft.
// Die View hat keine Logik mehr: Sie ist einfach zu lesen; das View Model
// hat kein Template: Es ist einfach zu testen.
// Es wird von der SEITE bereitgestellt (providers: [ScheduleModel]): Es entsteht und stirbt
// mit ihr.
//
// Es erledigt auch, was wir nicht für jeden Bildschirm neu schreiben wollen:
//   - einen CACHE: Der Terminkalender jedes bereits gelesenen (Arzt, Tag) wird behalten; die
//     Rückkehr dorthin zeigt ihn sofort an, während er im Hintergrund erneut gelesen wird;
//   - VERALTETE Antworten werden ignoriert (siehe Beispiel 19).
// =========================================================================

import { computed, inject, Injectable, signal } from '@angular/core';
import { ApiError } from '../common/api-error';
import { Schedule, ScheduleSlot, timeRange, Person, User } from '../common/types';
import { RdvMedecins } from './rdvmedecins';

// ein Datum -> "2026-10-07" (der LOKALE Tag; toISOString würde den Tag in Greenwich liefern)
export function formatDay(d: Date): string {
  const twoDigits = (n: number) => String(n).padStart(2, '0');
  return `${d.getFullYear()}-${twoDigits(d.getMonth() + 1)}-${twoDigits(d.getDate())}`;
}

// morgen: der heutige Tag plus eins
function tomorrow(): Date {
  const d = new Date();
  d.setDate(d.getDate() + 1);
  return d;
}

export interface Message {
  success: boolean;
  text: string;
}

@Injectable()
export class ScheduleModel {
  private readonly rdvmedecins = inject(RdvMedecins);

  // ==== der Zustand ====
  readonly user = signal<User | null>(null);
  readonly doctors = signal<Person[]>([]);
  readonly clients = signal<Person[]>([]);
  readonly doctorId = signal<number | null>(null);
  readonly day = signal(formatDay(tomorrow()));
  readonly clientId = signal<number | null>(null);
  readonly schedule = signal<Schedule | null>(null);
  readonly loading = signal(false);
  readonly message = signal<Message | null>(null);

  private readonly cache = new Map<string, Schedule>();
  private readNumber = 0;

  // ==== berechnete Werte ====
  readonly loggedIn = computed(() => this.user() !== null);
  readonly isManager = computed(() => this.loggedIn() && this.user()?.role !== 'USER');

  // ==== die Aktionen ====
  async changeUser(u: User | null): Promise<void> {
    this.user.set(u);
    this.doctors.set([]);
    this.clients.set([]);
    this.schedule.set(null);
    this.doctorId.set(null);
    this.message.set(null);
    this.cache.clear(); // die Rechte haben sich geändert: Wir vergessen alles
    if (u === null) return;
    this.doctors.set(await this.rdvmedecins.getDoctors());
    // ein USER würde 403 erhalten
    if (this.isManager()) this.clients.set(await this.rdvmedecins.getClients());
  }

  chooseDoctor(id: number): void {
    this.doctorId.set(id);
    this.message.set(null);
    this.readSchedule();
  }

  chooseDay(day: string): void {
    this.day.set(day);
    this.message.set(null);
    this.readSchedule();
  }

  chooseClient(id: number | null): void {
    this.clientId.set(id);
  }

  book(c: ScheduleSlot): Promise<void> {
    return this.act(
      () => this.rdvmedecins.book(this.day(), c.id, this.isManager() ? this.clientId() : null),
      `Slot ${timeRange(c)} booked.`,
    );
  }

  cancel(c: ScheduleSlot): Promise<void> {
    return this.act(() => this.rdvmedecins.cancelAppointment(c.appointmentId!), `Appointment of ${timeRange(c)} cancelled.`);
  }

  // eine Aktion, dann IMMER ein erneutes Lesen des Terminkalenders: Der SERVER ist die Referenz
  private async act(action: () => Promise<void>, success: string): Promise<void> {
    try {
      await action();
      this.message.set({ success: true, text: success });
    } catch (e) {
      this.message.set({ success: false, text: e instanceof ApiError ? e.message : String(e) });
    }
    await this.readSchedule();
  }

  private async readSchedule(): Promise<void> {
    const id = this.doctorId();
    if (id === null) return;
    const key = `${id}/${this.day()}`;
    const number = ++this.readNumber;
    // zuerst der Cache (oder nichts), dann das Lesen
    this.schedule.set(this.cache.get(key) ?? null);
    this.loading.set(true);
    try {
      const read = await this.rdvmedecins.getSchedule(id, this.day());
      if (number !== this.readNumber) return; // ein neueres Lesen wurde gestartet
      this.cache.set(key, read);
      this.schedule.set(read);
    } catch (e) {
      if (number !== this.readNumber) return;
      this.schedule.set(null);
      this.message.set({ success: false, text: e instanceof ApiError ? e.message : String(e) });
    }
    this.loading.set(false);
  }
}

Die Architekturleitfäden empfehlen, die View (das Template und seine Klasse, die anzeigen und Benutzeraktionen weitergeben) und das View-Model (ein Service, der den Zustand des Bildschirms und seine Aktionen enthält und die API-Zugriffsschicht aufruft) zu trennen. Die View enthält keine Logik mehr; das View-Model hat kein Template: Es kann ohne Bildschirm getestet werden.

  • Zeilen 28–38: der Tag im Serverformat („2026-10-07“) und der folgende Tag. Wir verwenden nicht [toISOString()], das den Tag in der mittleren Greenwich-Zeit liefern würde: Um 0:30 Uhr in Paris ist dort noch der Vortag;
  • Zeile 45: [@Injectable()], ohne [providedIn]: Der Service wird nicht für die gesamte Anwendung bereitgestellt, sondern von der Seite, die ihn in ihren [providers] deklariert (siehe den Bildschirm). Er wird zusammen mit dieser Seite erzeugt und zerstört;
  • Zeilen 50–58: der Zustand des Bildschirms, durch Signale dargestellt;
  • Zeilen 60–61: ein Cache: Der Terminkalender jedes bereits gelesenen Paars (Arzt, Tag) wird gespeichert; kehrt man zu ihm zurück, wird er sofort angezeigt, während er neu gelesen wird. Dazu die Nummer des letzten Lesevorgangs, um veraltete Antworten zu ignorieren (siehe Beispiel 19). Das ist, in wenigen Zeilen, was die Bibliothek [TanStack Query] im Kurs [React] leistet;
  • Zeilen 64–65: berechnete Werte ([computed]): angemeldet? Administrator (ADMIN oder DOCTOR)?
  • Zeilen 68–80: ein neuer Benutzer: Wir verwerfen alles (die Berechtigungen haben sich geändert), dann lesen wir die Ärzte und, für ADMIN und DOCTOR, die Kunden (ein USER würde eine 403 erhalten);
  • Zeilen 98–107: Buchen, stornieren. Das [!] in [c.appointmentId!] (Zeile 106) teilt dem Compiler mit, dass der Wert nicht [null] ist: Die Schaltfläche „Stornieren“ wird nur in diesem Fall angezeigt;
  • Zeilen 110–118: eine Aktion, IMMER gefolgt von einem erneuten Lesen des Terminkalenders: Die Daten des Servers haben Vorrang;
  • Zeilen 120–139: das Lesen des Terminkalenders: zuerst der Cache oder nichts (Zeile 126), dann die Antwort des Servers, es sei denn, in der Zwischenzeit wurde ein neueres Lesen gestartet (Zeile 130).

9.3.7. Der Bildschirm

// =========================================================================
// src/app/ex24-api-layer/ex24.page.ts - ein Terminkalender mit der Zugriffsschicht auf die API
// -------------------------------------------------------------------------
// Melden Sie sich an (obere Leiste), wählen Sie einen Arzt und einen Tag:
// Der Terminkalender wird angezeigt. ADMIN und DOCTOR können für einen Patienten buchen und
// stornieren; ein Patient (martin ...) bucht für sich selbst. Jede Aktion
// endet mit einem erneuten Lesen des Terminkalenders.
// Drei Schichten, von unten nach oben:
//   Api (common/api.ts)                  die HTTP-Anfragen, die Fehler;
//   RdvMedecins (rdvmedecins.ts)         eine typisierte Methode pro Route der API;
//   ScheduleModel (schedule-model.ts)    der Zustand und die Aktionen des Bildschirms;
// und die View (diese Klasse und ihr Template), die nur das Modell anzeigt.
// =========================================================================

import { Component, inject } from '@angular/core';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonChip, IonContent, IonDatetime, IonHeader,
  IonIcon, IonItem, IonLabel, IonList, IonModal, IonProgressBar, IonSelect, IonSelectOption, IonText, IonTitle,
  IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { addCircleOutline, calendarOutline, closeCircleOutline } from 'ionicons/icons';
import { LoginBar } from '../common/login-bar';
import { timeRange, fullName } from '../common/types';
import { ScheduleModel } from './schedule-model';

@Component({
  selector: 'app-ex24',
  imports: [
    IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonSelect, IonSelectOption, IonButton,
    IonIcon, IonModal, IonDatetime, IonCard, IonCardContent, IonProgressBar, IonText, IonList, IonItem, IonLabel,
    IonChip, LoginBar,
  ],
  templateUrl: './ex24.page.html',
  // das View Model wird von der SEITE bereitgestellt: eine Instanz pro Seite, mit ihr zerstört
  providers: [ScheduleModel],
  styles: `
    .day { display: flex; align-items: center; }
    ion-modal.calendar { --width: fit-content; --height: fit-content; --border-radius: 8px; }
    .message { margin: 8px 0; }
    .success { --background: #e8f5e9; --color: #333; }
    .failure { --background: #ffebee; --color: #333; }
    .schedule-title { font-weight: bold; font-size: 14px; margin: 8px 0; }
    .time-range { flex: 0 0 90px; font-size: 13px; }
    .free { --background: #c8e6c9; }
    .mine { --background: #c5cae9; }
    .other { --background: #e0e0e0; }
    ion-item ion-icon { font-size: 26px; }
  `,
})
export class Ex24Page {
  readonly model = inject(ScheduleModel);
  readonly timeRange = timeRange;
  readonly fullName = fullName;

  constructor() {
    addIcons({ calendarOutline, addCircleOutline, closeCircleOutline });
  }

  // ion-datetime liefert "2026-10-07" (presentation="date") oder ein Array, wenn
  // mehrere Daten wählbar sind: Wir behalten nur eine Zeichenkette
  chooseDay(value: string | string[] | null | undefined): void {
    if (typeof value === 'string') this.model.chooseDay(value.substring(0, 10));
  }
}
<!-- ======================================================================
     ex24.page.html - die View: sie zeigt nur das View Model an
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>Example 24 - an API access layer</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <!-- die Anmeldeleiste benachrichtigt das View Model -->
  <app-login-bar (userChange)="model.changeUser($event)" />

  @if (model.loggedIn()) {
    <ion-select placeholder="-- choose a doctor --" interface="popover" class="doctor-choice" aria-label="doctor"
      [value]="model.doctorId()" (ionChange)="model.chooseDoctor($event.detail.value)">
      @for (m of model.doctors(); track m.id) {
        <ion-select-option [value]="m.id">{{ fullName(m) }}</ion-select-option>
      }
    </ion-select>

    <div class="day">
      Day: {{ model.day() }}
      <ion-button id="calendar24" fill="clear" aria-label="choose the day">
        <ion-icon slot="icon-only" name="calendar-outline" />
      </ion-button>
    </div>
    <ion-modal class="calendar" trigger="calendar24">
      <ng-template>
        <ion-datetime presentation="date" locale="en-US" [firstDayOfWeek]="1" [showDefaultButtons]="true"
          doneText="OK" cancelText="Cancel" [value]="model.day()" (ionChange)="chooseDay($event.detail.value)" />
      </ng-template>
    </ion-modal>

    <!-- ADMIN und DOCTOR: der Patient, für den wir buchen -->
    @if (model.isManager()) {
      <ion-select interface="popover" class="patient-choice" aria-label="patient" [value]="model.clientId()"
        (ionChange)="model.chooseClient($event.detail.value)">
        <ion-select-option [value]="null">-- patient to book --</ion-select-option>
        @for (c of model.clients(); track c.id) {
          <ion-select-option [value]="c.id">{{ fullName(c) }}</ion-select-option>
        }
      </ion-select>
    }

    @if (model.message(); as message) {
      <ion-card class="message" [class.success]="message.success" [class.failure]="!message.success">
        <ion-card-content>{{ message.text }}</ion-card-content>
      </ion-card>
    }
    @if (model.loading()) {
      <ion-progress-bar type="indeterminate" />
    }

    @if (model.schedule(); as schedule) {
      <!-- info: der Schlüssel, den der Server sendet, wenn ein Patient bereits einen bevorstehenden Termin hat -->
      @if (schedule.info) {
        <ion-text color="primary"><div>{{ schedule.info }}</div></ion-text>
      }
      <div class="schedule-title">Schedule of {{ schedule.day }} - {{ fullName(schedule.doctor) }}</div>
      <ion-list lines="none">
        <!-- eine Zeile pro Zeitfenster: der Zeitraum, der Belegende, die erlaubte Schaltfläche -->
        @for (c of schedule.slots; track c.id) {
          <ion-item>
            <ion-label class="time-range">{{ timeRange(c) }}</ion-label>
            @if (c.free) {
              <ion-chip class="free">Free</ion-chip>
            } @else {
              <ion-chip [class.mine]="c.mine" [class.other]="!c.mine">
                {{ c.patient ? fullName(c.patient) : 'Booked' }}
              </ion-chip>
            }
            <!-- die Schaltflächen folgen den vom Server berechneten Rechten -->
            @if (c.bookable) {
              <ion-button slot="end" fill="clear" color="success" aria-label="Book" (click)="model.book(c)">
                <ion-icon slot="icon-only" name="add-circle-outline" />
              </ion-button>
            } @else if (c.appointmentId !== null) {
              <ion-button slot="end" fill="clear" color="danger" aria-label="Cancel" (click)="model.cancel(c)">
                <ion-icon slot="icon-only" name="close-circle-outline" />
              </ion-button>
            }
          </ion-item>
        }
      </ion-list>
    }
  }
</ion-content>
  • Zeile 36 (.ts): [providers: [ScheduleModel]]: Die Seite stellt das View-Model sich selbst und den darin enthaltenen Komponenten bereit. Die beiden anderen Schichten ([Api], [RdvMedecins]) werden für die gesamte Anwendung bereitgestellt ([providedIn: 'root']);
  • Zeile 52 (.ts): Die View bezieht das View-Model; sie hat keinen anderen Zustand;
  • Zeilen 53–54 (.ts): die Formatierungsfunktionen, für das Template zugänglich gemacht (ein Template sieht nur Member seiner Klasse);
  • Zeilen 62–64 (.ts): [ion-datetime] liefert das ausgewählte Datum („2026-10-07“) oder ein Array, falls mehrere Daten ausgewählt werden könnten: Es wird nur ein String übernommen;
  • Zeile 16 (html): Die Anmeldeleiste benachrichtigt das View-Model; [$event] ist der gelieferte Wert, entweder der Benutzer oder [null];
  • Zeilen 19–24 (HTML): die Arztauswahl: ein [<ion-select>] , dessen Liste sich in einem Popup-Fenster öffnet ([interface="popover"]); sein Wert wird aus dem View-Model gelesen, und jede Auswahl ([ionChange]) löst eine Aktion des View-Models aus;
  • Zeilen 26–37 (HTML): der Tag und ein Kalender in einem modalen Fenster (wie in Beispiel 21): [ion-datetime], auf amerikanischem Englisch, mit Wochenbeginn am Montag; seine Schaltflächen OK und Abbrechen ([showDefaultButtons]) schließen das Fenster, und OK bestätigt den Tag ([ionChange]);
  • Zeilen 40–48 (HTML): für ADMIN und DOCTOR der Patient, für den der Termin vereinbart wird;
  • Zeilen 50–57 (html): die Meldung zur letzten Aktion (grün oder rot: [[class.success]] fügt die CSS-Klasse hinzu, wenn die Bedingung wahr ist) und der Fortschrittsbalken während des Lesens;
  • Zeilen 61–63 (html): [info], der vom Server gesendete Schlüssel, wenn der Patient bereits einen bevorstehenden Termin hat. Er wird unverändert angezeigt: Beispiel 25 zeigt, wie die Schlüssel dekodiert werden;
  • Zeilen 67–88 (HTML): eine Zeile pro Zeitfenster: die Uhrzeit, ein [<ion-chip>] (ein „Badge“) mit der Beschriftung „Frei“ oder dem Namen des Patienten (in Indigo, wenn es der Termin des angemeldeten Patienten ist) und die zugehörige Schaltfläche. Die Schaltflächen folgen den vom Server berechneten Berechtigungen ([bookable], [appointmentId]): Der Bildschirm trifft keine Entscheidungen.

Angemeldet als [admin], der Terminkalender von Frau PELISSIER für den folgenden Tag; ein Zeitfenster ist für Herrn Jean MARTIN reserviert; angemeldet als [martin] (Rolle USER), derselbe Terminkalender:

Der Patient [martin] sieht seinen Termin (in Indigo, mit der Schaltfläche zum Stornieren); der Schlüssel [SCHEDULE.ALREADY_BOOKED_INFO] zeigt an, dass er bereits einen bevorstehenden Termin hat: Weitere Zeitfenster stehen nicht zur Buchung zur Verfügung. Ein Termin eines anderen Patienten würde als „Belegt“ ohne Namen erscheinen: Der Server sendet ihn nicht an den Benutzer.

9.4. Beispiel 25: Vom Server zurückgegebene Fehler

9.4.1. Die Wörterbücher

{
  "FORM": {
    "TITLE_ADD": "Ajouter un client",
    "TITLE_EDIT": "Modifier un client",
    "TITLE": "Titre",
    "FIRSTNAME": "Prénom",
    "LASTNAME": "Nom",
    "LOGIN": "Login",
    "PASSWORD": "Mot de passe",
    "SAVE": "Enregistrer",
    "CANCEL": "Annuler",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "DELETE_CONFIRM": "Supprimer le client {{name}}, son compte et ses rendez-vous ?",
    "ADDED": "Le client {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le client {{name}} a été modifié.",
    "DELETED": "Le client {{name}} a été supprimé.",
    "ADMIN_ONLY": "Connectez-vous avec le compte admin : seul le rôle ADMIN gère les clients.",
    "PAGE_TITLE": "Exemple 25 - les erreurs du serveur",
    "NEW": "Nouveau client"
  },
  "ERRORS": {
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Rechargez-la avant de recommencer.",
    "FORBIDDEN": "Votre rôle ne vous permet pas cette action.",
    "AUTH_REQUIRED": "Connectez-vous d'abord.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "SERVER_UNREACHABLE": "Le serveur ne répond pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite.",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image."
  }
}

Die Fehlermeldungen des Servers sind Schlüssel („ERRORS.LASTNAME_REQUIRED“): Das Wörterbuch übersetzt sie. Es sind die Wörterbücher des [Flutter]-Beispiels, unverändert; das englische Wörterbuch [ex25-en.json] hat dieselben Schlüssel. Wie die aus Beispiel 21 liegen sie im Ordner [public/i18n/] des Projekts, der unverändert mit der Anwendung ausgeliefert wird.

9.4.2. Der Bildschirm

// =========================================================================
// src/app/ex25-server-errors/ex25.page.ts - Anzeige der Fehler des SERVERS
// -------------------------------------------------------------------------
// Die Verwaltung der Clients (Admin-Konto). Dieses Formular führt
// ABSICHTLICH keine Validierung auf dem Telefon durch: Alles wird an den
// Server gesendet, der im Fall einer Ablehnung mit einem JSON-Fehler antwortet (von
// common/api.ts in einen ApiError umgewandelt):
//
//   400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
//   409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
//   409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (optimistisches Sperren)
//
// Der Fehler JEDES Felds (ApiError.fields) wird seinem
// Formular-Control übergeben (setErrors): ion-input zeigt ihn unter dem Feld an (errorText).
// Seine Meldung ist der vom Server gesendete SCHLÜSSEL, den der Bildschirm übersetzt
// (Wörterbücher aus Beispiel 21). Das Ändern eines Felds löscht seinen Fehler.
// Probieren Sie: einen leeren Namen, einen Titel "Dr", einen Namensvetter (Alice DURAND), einen
// bereits vergebenen Login (martin), denselben Datensatz auf zwei Geräten geändert ...
// =========================================================================

import { Component, inject, signal } from '@angular/core';
import { NonNullableFormBuilder, ReactiveFormsModule } from '@angular/forms';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonCardHeader, IonCardTitle, IonContent, IonHeader,
  IonIcon, IonInput, IonItem, IonLabel, IonList, IonNote, IonPopover, IonSelect, IonSelectOption, IonText, IonTitle,
  IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { createOutline, languageOutline, trashOutline } from 'ionicons/icons';
import { Api } from '../common/api';
import { LoginBar } from '../common/login-bar';
import { ApiError, Texts } from '../common/api-error';
import { fullName, Person, User } from '../common/types';
import { injectConfirmation } from '../ex16-confirmation/confirmation';
import { languages, Translations } from '../ex21-i18n/translations';
import { Command } from '../ex23-login/command';

// die Felder des Formulars und eine zu übersetzende Meldung (ein Schlüssel und seine Parameter)
type Field = 'title' | 'firstName' | 'lastName' | 'login' | 'password';
interface Success {
  key: string;
  params: Texts;
}

@Component({
  selector: 'app-ex25',
  imports: [
    ReactiveFormsModule, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonButton, IonIcon, IonPopover,
    IonContent, IonList, IonItem, IonLabel, IonCard, IonCardHeader, IonCardTitle, IonCardContent, IonSelect,
    IonSelectOption, IonInput, IonText, IonNote, LoginBar,
  ],
  templateUrl: './ex25.page.html',
  // die Übersetzungen der Seite mit den Wörterbüchern ex25-fr.json und ex25-en.json
  providers: [{ provide: Translations, useFactory: () => new Translations('ex25') }],
  styles: `
    .warning { --background: #fff8e1; --color: #333; }
    .message { margin-top: 12px; }
    .status { font-size: 12px; }
  `,
})
export class Ex25Page {
  private readonly api = inject(Api);
  private readonly confirm = injectConfirmation();
  readonly tr = inject(Translations);
  readonly languages = languages;
  readonly titles = ['Mr', 'Mme', 'Melle', 'Dr']; // "Dr": Der Server wird ihn ablehnen
  readonly fullName = fullName;

  readonly user = signal<User | null>(null);
  readonly clients = signal<Person[]>([]);

  // das Formular: KEINE Validierungsregel, alles wird vom Server geprüft
  readonly form = inject(NonNullableFormBuilder).group({
    title: ['Mr'],
    firstName: [''],
    lastName: [''],
    login: [''],
    password: [''],
  });
  // null: Anlegen; sonst die ID des geänderten Clients und die mit seinem Datensatz gelesene Version
  readonly editedId = signal<number | null>(null);
  private version = 0;

  // die allgemeine Meldung des letzten Fehlers und die eines Erfolgs
  readonly pageError = signal<ApiError | null>(null);
  readonly success = signal<Success | null>(null);
  // das Senden an den Server: ein Command (Beispiel 23), der angibt, ob er läuft
  readonly sending = new Command();

  constructor() {
    addIcons({ languageOutline, createOutline, trashOutline });
    this.tr.start();
  }

  isAdmin(): boolean {
    return this.user()?.role === 'ADMIN';
  }

  private async reload(): Promise<void> {
    this.clients.set(await this.api.get<Person[]>('/clients'));
  }

  async onUserChange(u: User | null): Promise<void> {
    this.user.set(u);
    this.clients.set([]);
    if (u?.role === 'ADMIN') await this.reload();
  }

  // der vom Server zurückgegebene, übersetzte Fehler eines Felds ('': kein Fehler)
  fieldError(field: Field): string {
    const key = this.form.controls[field].errors?.['server'];
    return typeof key === 'string' ? this.tr.t(key) : '';
  }

  private clearMessages(): void {
    this.pageError.set(null);
    this.success.set(null);
  }

  newForm(): void {
    this.editedId.set(null);
    this.version = 0;
    // reset: die Startwerte und kein Fehler mehr
    this.form.reset();
    this.clearMessages();
  }

  edit(c: Person): void {
    this.editedId.set(c.id);
    // die mit dem Datensatz gelesene VERSION geht mit der Änderung zurück: Hat jemand
    // den Datensatz in der Zwischenzeit geändert, antwortet der Server mit 409 CONCURRENT_UPDATE
    this.version = c.version;
    this.form.reset({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '' });
    this.clearMessages();
  }

  // die Schaltfläche "Speichern"
  submit(): void {
    this.sending.execute(() => this.save());
  }

  private async save(): Promise<void> {
    this.clearMessages();
    const input = { ...this.form.getRawValue(), version: this.version };
    const id = this.editedId();
    try {
      const client =
        id === null
          ? await this.api.post<Person>('/clients', input)
          : await this.api.put<Person>(`/clients/${id}`, input);
      this.newForm(); // Formular geleert, Meldungen gelöscht ...
      // ... außer dieser
      this.success.set({
        key: id === null ? 'FORM.ADDED' : 'FORM.UPDATED',
        params: { name: `${client.firstName} ${client.lastName}`, login: client.login ?? '' },
      });
      await this.reload();
    } catch (e) {
      if (!(e instanceof ApiError)) throw e;
      this.pageError.set(e); // die allgemeine Meldung
      // der Fehler jedes Felds: Er wird seinem Control übergeben, das
      // ungültig wird (ng-invalid); markAsTouched markiert es als "berührt"
      // (ng-touched): Ionic zeigt dann seinen errorText an
      for (const [field, key] of Object.entries(e.fields)) {
        const control = this.form.get(field);
        control?.setErrors({ server: key });
        control?.markAsTouched();
      }
    }
  }

  async remove(c: Person): Promise<void> {
    const name = `${c.firstName} ${c.lastName}`;
    if (!(await this.confirm(this.tr.t('FORM.DELETE_CONFIRM', { name })))) return;
    this.clearMessages();
    try {
      await this.api.delete(`/clients/${c.id}`);
      this.success.set({ key: 'FORM.DELETED', params: { name } });
    } catch (e) {
      if (e instanceof ApiError) this.pageError.set(e);
    }
    await this.reload();
  }
}
<!-- ======================================================================
     ex25.page.html - die Verwaltung der Kunden und die Fehler des Servers
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>{{ tr.t('FORM.PAGE_TITLE') }}</ion-title>
    <!-- die Sprache: ein Menü in einem Pop-up-Fenster (ion-popover) -->
    <ion-buttons slot="end">
      <ion-button id="language25" aria-label="language">
        <ion-icon slot="icon-only" name="language-outline" />
      </ion-button>
    </ion-buttons>
    <ion-popover trigger="language25" [dismissOnSelect]="true">
      <ng-template>
        <ion-list>
          @for (l of languages; track l) {
            <ion-item [button]="true" (click)="tr.changeLanguage(l)">{{ l.toUpperCase() }}</ion-item>
          }
        </ion-list>
      </ng-template>
    </ion-popover>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <app-login-bar (userChange)="onUserChange($event)" />

  @if (user() !== null && !isAdmin()) {
    <ion-card class="warning">
      <ion-card-content>{{ tr.t('FORM.ADMIN_ONLY') }}</ion-card-content>
    </ion-card>
  }

  @if (isAdmin()) {
    <ion-list>
      @for (c of clients(); track c.id) {
        <ion-item>
          <ion-label>
            {{ fullName(c) }}
            <p>{{ c.login }}</p>
          </ion-label>
          <ion-button slot="end" fill="clear" color="dark" [attr.aria-label]="tr.t('FORM.EDIT')"
            (click)="edit(c)">
            <ion-icon slot="icon-only" name="create-outline" />
          </ion-button>
          <ion-button slot="end" fill="clear" color="danger" [attr.aria-label]="tr.t('FORM.DELETE')"
            (click)="remove(c)">
            <ion-icon slot="icon-only" name="trash-outline" />
          </ion-button>
        </ion-item>
      }
    </ion-list>

    <ion-card>
      <ion-card-header>
        <ion-card-title>{{ tr.t(editedId() === null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT') }}</ion-card-title>
      </ion-card-header>
      <ion-card-content>
        <!-- kein (ngSubmit): Die Schaltfläche Speichern ruft submit() auf -->
        <form [formGroup]="form">
          <!-- errorText: der vom Server zurückgegebene, übersetzte Fehler des Feldes. Ionic
               zeigt ihn an, wenn das Control ungültig (ion-invalid) und touched (ion-touched) ist -->
          <ion-select [label]="tr.t('FORM.TITLE')" labelPlacement="floating" interface="popover"
            formControlName="title" [errorText]="fieldError('title')">
            @for (t of titles; track t) {
              <ion-select-option [value]="t">{{ t }}</ion-select-option>
            }
          </ion-select>
          <ion-input [label]="tr.t('FORM.FIRSTNAME')" labelPlacement="floating" formControlName="firstName"
            [errorText]="fieldError('firstName')" />
          <ion-input [label]="tr.t('FORM.LASTNAME')" labelPlacement="floating" formControlName="lastName"
            [errorText]="fieldError('lastName')" />
          <ion-input [label]="tr.t('FORM.LOGIN')" labelPlacement="floating" formControlName="login"
            [errorText]="fieldError('login')" />
          <ion-input [label]="tr.t('FORM.PASSWORD')" labelPlacement="floating" type="password"
            formControlName="password" [errorText]="fieldError('password')" />
        </form>

        <ion-button class="ion-margin-top" shape="round" [disabled]="sending.running()" (click)="submit()">
          {{ tr.t('FORM.SAVE') }}
        </ion-button>
        <ion-button class="ion-margin-top" shape="round" fill="outline" (click)="newForm()">
          {{ tr.t('FORM.CANCEL') }}
        </ion-button>

        @if (success(); as s) {
          <div class="message"><ion-text color="success">{{ tr.t(s.key, s.params) }}</ion-text></div>
        }
        <!-- die allgemeine Meldung und der HTTP-Status, zum Verständnis -->
        @if (pageError(); as e) {
          <div class="message">
            <ion-text color="danger">{{ tr.t(e.key, e.params) }}</ion-text>
            <ion-note class="status"> ({{ e.message }})</ion-note>
          </div>
        }
      </ion-card-content>
    </ion-card>
  }
</ion-content>

Kundenverwaltung (Admin-Konto). Dieses Formular führt auf dem Smartphone keine Validierung durch: Alles wird an den Server gesendet, der im Fall einer Ablehnung mit einem Fehler-JSON antwortet, das vom Service [Api] in [ApiError] umgewandelt wird.

  • Zeilen 34–36 (.ts): Die Seite verwendet drei Werkzeuge aus den vorigen Beispielen wieder, indem sie sie aus ihren jeweiligen Ordnern importiert: die Bestätigung aus Beispiel 16, die Übersetzungen aus Beispiel 21 und das Command aus Beispiel 23 (der [Flutter]-Client tat dasselbe). Die Klasse [Translations] aus Beispiel 21 wurde dafür geschrieben: Sie ist kein Singleton-Service, sondern eine Klasse, die über das Präfix ihrer Wörterbücher konfiguriert wird. Zeile 54 erzeugt eine Instanz davon für diese Seite, mit den Wörterbüchern [ex25-fr.json] und [ex25-en.json]. Warum nicht nach [common/] verschieben? In einer Anwendung würde sie dort hineinpassen; in diesem Kurs wird jedes Beispiel der Reihe nach gelesen, und Beispiel 21 bleibt das Beispiel, das sie einführt;
  • Zeile 63 (.ts): die Bestätigungsfunktion aus Beispiel 16 ([AlertController]);
  • Zeile 66 (.ts): ein Titel „Dr“, den der Server ablehnen wird: siehe [ERRORS.INVALID_TITLE];
  • Zeilen 73–79 (.ts): ein reaktives Formular (Beispiel 08), OHNE Validierungsregeln;
  • Zeilen 81–82 (.ts): der bearbeitete Kunde ([null]: eine Neuanlage) und die zusammen mit seinem Datensatz abgerufene Version;
  • Zeilen 85–88 (.ts): die allgemeine Meldung zum letzten Fehler, die Erfolgsmeldung (ein Schlüssel und seine Parameter, zur Anzeige übersetzt: Sie folgen einem Sprachwechsel) und das Absenden, ein [Command] (Beispiel 23);
  • Zeilen 110–113 (.ts): die Fehlermeldung zu einem Feld. Der Fehler wird in der Validierungslogik des Feldes unter dem Namen [server] gespeichert (siehe unten); sein Wert ist der vom Server gesendete Schlüssel, der übersetzt wird;
  • Zeilen 120–126 (.ts): ein neuer Kunde: [form.reset()] stellt die Standardwerte wieder her (das Formular ist „non-nullable“, Beispiel 08) und löscht alle Fehler;
  • Zeilen 128–135 (.ts): einen Kunden bearbeiten: Das Formular erhält den Datensatz des Kunden. Die aus dem Datensatz gelesene Version wird mit der Änderung aktualisiert: Hat in der Zwischenzeit jemand den Datensatz geändert, antwortet der Server mit einer 409 [CONCURRENT_UPDATE] (das optimistische Sperren);
  • Zeilen 142–170 (.ts): Speichern: [POST /api/clients] (anlegen) oder [PUT /api/clients/:id] (aktualisieren), mit den Werten des Formulars und der Version (Zeile 144). Bei Erfolg wird das Formular geleert und eine Erfolgsmeldung angezeigt (Zeilen 151–156). Bei Ablehnung zeigt [ApiError] die allgemeine Meldung (Zeile 160) und den Fehler je Feld (Zeilen 164–168) an:
  • [control.setErrors({ server: key })] lässt die Validierung des Feldes einen Fehler zurückgeben: Das Feld wird ungültig (Klasse [ng-invalid]);
  • [control.markAsTouched()] markiert es als „berührt“ (Klasse [ng-touched]), als hätte man es verlassen;
  • [Ionic] kopiert diese beiden Klassen – [ion-invalid] und [ion-touched]– auf das Feld (Beispiel 07): Es zeigt dann unter dem Feld den Text seines [errorText] an und hebt es rot hervor;
  • und das Bearbeiten des Feldes löscht den Fehler ohne eine einzige Codezeile: Bei jedem Tastendruck validiert [Angular] das Feld erneut anhand seiner Regeln … und es hat keine. Der manuell gesetzte Fehler verschwindet. Im [onChanged] mussten Sie im [Flutter]-Client für jedes Feld eigens schreiben;
  • Zeilen 172–183 (.ts): das Löschen nach Bestätigung (die Bestätigungsmeldung wird übersetzt, mit dem Namen des Kunden als Parameter);
  • Zeilen 11–25 (html): Sprache: eine Schaltfläche in der oberen Leiste, die ein [<ion-popover>] öffnet (ein mit der Schaltfläche verbundenes Popup-Fenster, dessen [id] durch [trigger] angegeben wird); [dismissOnSelect] schließt es bei der ersten Auswahl. Das war der [PopupMenuButton] von [Flutter];
  • Zeilen 32–36 (html): ein angemeldeter Benutzer, der nicht ADMIN ist: eine Warnung;
  • Zeilen 38–56 (html): die Liste der Kunden mit ihren Schaltflächen „Bearbeiten“ und „Löschen“;
  • Zeilen 64–81 (HTML): das Formular. Jedes Feld ist mit seinem Control verbunden ([formControlName]); ihre Beschriftungen werden übersetzt; [[errorText]] erhält den übersetzten Serverfehler (Zeilen 67–68: [<ion-select>] hat ebenfalls einen [errorText]). Das Formular hat kein [(ngSubmit)]: Die Schaltfläche „Speichern“ ruft das Command auf (Zeilen 83–85);
  • Zeilen 90–99 (HTML): die Erfolgsmeldung und die allgemeine Fehlermeldung, übersetzt; der Übersichtlichkeit halber werden der HTTP-Status und der Schlüssel klein gedruckt angezeigt.

Ein leeres Formular; ein Namensvetter („Alice DURAND“); dasselbe auf Französisch:

Ein Sprachwechsel übersetzt den gesamten Bildschirm neu, auch bereits angezeigte Fehler: Der Bildschirm speichert die vom Server gesendeten Schlüssel – nicht den Text – und übersetzt sie bei jeder Anzeige des Bildschirms. Probieren Sie auch: einen Titel „Dr“, einen bereits vergebenen Benutzernamen ([martin]), einen ungültigen Benutzernamen („Jean M“) oder denselben Datensatz, der auf zwei Geräten bearbeitet wird (oder in zwei Browser-Tabs, oder in der App und mit [curl]).

Das Prinzip ist dasselbe wie bei allen Formularen der Fallstudie: Die Regeln liegen an nur EINER Stelle – dem Server; die App zeigt seine Antworten in der Sprache des Benutzers an. Natürlich spricht nichts dagegen, die Felder zusätzlich auf dem Smartphone zu validieren (Beispiel 08), um dem Benutzer schneller zu antworten; der Server muss jedoch alles erneut validieren, und sein Urteil ist endgültig.

Der Vergleich der beiden Clients zeigt, wie sehr sich [Ionic] auf den Browser stützt: Der HTTP-Client liefert direkt [JavaScript]-Objekte (JSON ist die native Sprache von [JavaScript]), das Token-Cookie wird ohne eine einzige Codezeile weitergereicht, und eine Anfrage kann abgebrochen werden. Dafür validiert [TypeScript] das Format der Antworten zur Laufzeit nicht, was das Filtern von [Dart] ganz selbstverständlich leistete. Der [Angular]-Client für [RdvMedecins] (Kurs [Angular]) ist genau wie diese Beispiele geschrieben: derselbe [HttpClient], dieselben Services, dieselben reaktiven Formulare; nur die Anzeigekomponenten unterscheiden sich, mit denen von [Ionic] , die die eines [Android]-Smartphones nachahmen.