Skip to content

5. Routing

Eine Anwendung hat mehrere Bildschirme. [Flutter] verwaltet sie mithilfe von [Navigator]: einem Stapel von Bildschirmen, auf den ein neuer Bildschirm ([Navigator.push]) gelegt und von dem er wieder entfernt wird ([Navigator.pop] oder die Zurück-Taste des Smartphones). Für eine kleine mobile App genügt das. Sobald Sie jedoch URLs (/doctors/2) wünschen – also Bildschirme, auf die verwiesen werden kann, die über einen Link geöffnet, im Web neu geladen und durch Guards geschützt werden können –, verwenden Sie einen Router. Das Paket [go_router], das vom [Flutter]-Team gepflegt und in dessen Dokumentation empfohlen wird, ist das am weitesten verbreitete.

5.1. Beispiel 17: Der Router

5.1.1. Die Daten

1
2
3
4
5
6
7
8
// "fest codierte" Daten, um in diesem Beispiel nicht von einem Server abzuhängen
typedef Doctor = ({int id, String title, String firstName, String lastName, String specialty});

const doctors = <Doctor>[
  (id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'general practitioner'),
  (id: 2, title: 'Mr', firstName: 'Paul', lastName: 'TATOU', specialty: 'pediatrician'),
  (id: 3, title: 'Melle', firstName: 'Sophie', lastName: 'DUPONT', specialty: 'general practitioner'),
];

„Fest codierte“ Daten, um in diesem Beispiel nicht auf einen Server angewiesen zu sein: eine Liste von Records.

5.1.2. Die Routen

// =========================================================================
// lib/ex17_router/routes.dart - die ROUTEN der Anwendung
// -------------------------------------------------------------------------
// Eine Anwendung hat mehrere Bildschirme ("Seiten"). Der ROUTER ordnet einer
// ADRESSE (einem Pfad, wie im Web: /doctors/2) einen Bildschirm zu. Flutter
// stellt den Navigator bereit (einen STAPEL von Bildschirmen: Wir pushen, wir poppen); das
// Paket go_router, vom Flutter-Team gepflegt, ergänzt ihn um
// Adressen: Links, Parameter, die Zurück-Taste des Browsers
// und von Hand eingetippte Adressen im Web, die Zurück-Taste von Android.
//   '/doctors/:id'   :id ist ein Parameter (/doctors/2 -> id = "2");
//   ShellRoute       eine gemeinsame "Shell" (obere Leiste, untere
//                    Navigationsleiste) um die Bildschirme ihrer Routen;
//   redirect         eine Weiterleitung: Die alte Adresse führt zur neuen;
//   errorBuilder     der Bildschirm einer Adresse, die zu keiner Route passt.
// =========================================================================

import 'package:go_router/go_router.dart';

import 'shell.dart';
import 'pages/home.dart';
// VERZÖGERTES Laden: Im Web wird der Code dieser Seite erst beim
// ersten Besuch heruntergeladen (flutter build web erzeugt dafür eine eigene Datei)
import 'pages/about.dart' deferred as about;
import 'pages/deferred_loading.dart';
import 'pages/doctor_detail.dart';
import 'pages/doctor_list.dart';
import 'pages/not_found_page.dart';
import 'pages/search.dart';

final router = GoRouter(
  // die Startadresse (auf einem Telefon: Es gibt keine Adressleiste)
  initialLocation: '/',
  routes: [
    ShellRoute(
      // child: der Bildschirm der aktuellen Kindroute, IN der Shell platziert
      builder: (context, state, child) => Shell(child: child),
      routes: [
        GoRoute(path: '/', builder: (context, state) => const Home()),
        GoRoute(
          path: '/doctors',
          builder: (context, state) => const DoctorList(),
          // eine VERSCHACHTELTE Route: /doctors/2
          routes: [
            GoRoute(
              path: ':id',
              // pathParameters: die Parameter des Pfads, immer STRINGS
              builder: (context, state) => DoctorDetail(id: state.pathParameters['id']!),
            ),
          ],
        ),
        GoRoute(
          path: '/search',
          // uri.queryParameters: die Parameter nach dem ? (/search?q=pediatrician)
          builder: (context, state) => Search(q: state.uri.queryParameters['q'] ?? ''),
        ),
        GoRoute(
          path: '/about',
          builder: (context, state) =>
              DeferredLoading(load: about.loadLibrary, builder: () => about.About()),
        ),
        // eine Weiterleitung: Die Route hat keinen Bildschirm, sie gibt eine andere Adresse zurück
        GoRoute(path: '/physicians', redirect: (context, state) => '/doctors'),
      ],
    ),
  ],
  errorBuilder: (context, state) => NotFoundPage(address: state.uri.toString()),
);

Eine Route ordnet einem Pfad einen Bildschirm zu.

  • Zeile 23: ein verzögerter Import ([deferred]). Im Web wird der Code dieser Seite in eine separate Datei kompiliert, die erst beim ersten Besuch der Seite heruntergeladen wird ([about.loadLibrary()]). Auf einem Smartphone befindet sich der gesamte Code bereits in der App: [loadLibrary()] endet sofort;
  • Zeilen 30–32: Der Router, ein Objekt namens [GoRouter], wird einmal erzeugt, außerhalb jedes Widgets. [initialLocation]: die Startadresse (auf einem Smartphone gibt es keine Adressleiste, in der sie angezeigt würde);
  • Zeilen 34–36: Eine [ShellRoute] ist ein gemeinsamer Container für mehrere Bildschirme: die obere Leiste und die untere Navigationsleiste. Ihr [builder] erhält [child] – den Bildschirm der aktuellen Route – und platziert ihn innerhalb der Shell. Das entspricht verschachtelten Routen und dem [<Outlet />] von [React Router];
  • Zeile 38: eine Route – ihr Pfad – und eine Funktion, die ihren Bildschirm erzeugt. [state] ([GoRouterState]) beschreibt die aktuelle Navigation: die Adresse und ihre Parameter;
  • Zeilen 40–47: die Liste der Ärzte und eine verschachtelte Route: [':id'] unter ['/doctors'] ergibt den Pfad [/doctors/:id], wobei [:id] ein Parameter ist ([/doctors/2]: [id] entspricht ["2"]). [state.pathParameters] liefert die Pfadparameter, die immer Strings sind;
  • Zeilen 52–54: [state.uri] ist die vollständige Adresse; [queryParameters] enthält die Parameter nach dem [?] ([/search?q=pediatrician]);
  • Zeilen 57–59: die Seite, die vom Widget [DeferredLoading] bei Bedarf geladen wird (wird später behandelt);
  • Zeile 62: eine Weiterleitung – die Route hat keinen Bildschirm; ihre Funktion [redirect] gibt eine andere Adresse zurück, auf die die Navigation umgeleitet wird;
  • Zeile 66: der Bildschirm für eine Adresse, die keiner Route entspricht.

5.1.3. Start

// =========================================================================
// lib/ex17_router/main.dart
// -------------------------------------------------------------------------
// MaterialApp.router: Die Anwendung hat nicht mehr EINEN Startbildschirm (home),
// der Router entscheidet anhand der Adresse über den Bildschirm.
// usePathUrlStrategy(): im Web "saubere" Adressen (/doctors/2)
// statt der Standardform (/#/doctors/2). Anderswo ohne Wirkung.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_web_plugins/url_strategy.dart';

import 'routes.dart';

void main() {
  usePathUrlStrategy();
  runApp(
    MaterialApp.router(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      routerConfig: router,
    ),
  );
}
  • Zeile 16: im Web „saubere“ Adressen ([/doctors/2]) statt der Standardform ([/#/doctors/2]). Hat auf einem Smartphone keine Wirkung;
  • Zeilen 17–21: [MaterialApp.router]: Die App zeigt nicht mehr EINEN Startbildschirm an ([home]); der Router bestimmt den Bildschirm anhand der Adresse.

5.1.4. Die Shell der App

// =========================================================================
// lib/ex17_router/shell.dart - die "Shell" der Anwendung
// -------------------------------------------------------------------------
// Die obere Leiste, die untere Navigationsleiste und dazwischen
// der Bildschirm der aktuellen Route (child).
//   - GoRouterState.of(context).uri : die aktuelle Adresse;
//   - context.go('/doctors')        : zu einer Adresse gehen. Der Stapel der
//     Bildschirme wird durch den dieser Adresse ERSETZT (ein Tab);
//   - context.push('/doctors/2')    : einen Bildschirm ÜBER den
//     aktuellen Bildschirm PUSHEN; die Zurück-Taste (oder context.pop()) poppt ihn.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

// die Tabs: (Pfad, Label, Icon)
const tabs = [
  ('/', 'Home', Icons.home),
  ('/doctors', 'Doctors', Icons.people),
  ('/search?q=general practitioner', 'Search', Icons.search),
  ('/about', 'About', Icons.info),
];

class Shell extends StatelessWidget {
  final Widget child;

  const Shell({super.key, required this.child});

  @override
  Widget build(BuildContext context) {
    final address = GoRouterState.of(context).uri;
    // der aktive Tab: der, dessen Pfad der Anfang der aktuellen Adresse ist
    int active = 0;
    for (final (i, (path, _, _)) in tabs.indexed) {
      final start = Uri.parse(path).path;
      if (start != '/' && address.path.startsWith(start)) active = i;
    }

    return Scaffold(
      appBar: AppBar(title: const Text('Example 17 - the router')),
      body: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          Container(
            color: Colors.grey.shade100,
            padding: const EdgeInsets.all(8),
            // Uri.decodeFull: %20 wird wieder zu einem Leerzeichen
            child: Text(
              'current address: ${Uri.decodeFull(address.toString())}',
              style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12),
            ),
          ),
          Expanded(
            child: Padding(padding: const EdgeInsets.all(16), child: child),
          ),
        ],
      ),
      // NavigationBar: die untere Tab-Leiste, typisch für ein Mobilgerät
      bottomNavigationBar: NavigationBar(
        selectedIndex: active,
        onDestinationSelected: (i) => context.go(tabs[i].$1),
        destinations: [
          for (final (_, label, icon) in tabs) NavigationDestination(icon: Icon(icon), label: label),
        ],
      ),
    );
  }
}
  • Zeilen 17–21: die Tabs: Records (Pfad, Beschriftung, Symbol);
  • Zeile 31: die aktuelle Adresse. [GoRouterState.of(context)] ist ein Lesezugriff auf vererbte Daten (siehe Beispiel 14): Die Shell wird bei jeder Navigation neu aufgebaut;
  • Zeilen 33–36: der aktive Tab: derjenige, dessen Pfad den Anfang der aktuellen Adresse bildet. [for (final (i, (path, _, _)) in tabs.indexed)] zerlegt sowohl das Paar (Rang, Tab) als auch den Tab-Record und behält nur den Pfad ([_]: „ignoriert“);
  • Zeilen 48–49: die aktuelle Adresse, angezeigt ([Uri.decodeFull]: [%20] wird wieder zu einem Leerzeichen);
  • Zeilen 53–54: der Bildschirm der aktuellen Route;
  • Zeilen 59–63: die untere Tab-Leiste ([NavigationBar]), typisch für eine mobile App. [onDestinationSelected] erhält den Index des angetippten Tabs; [context.go(path)] führt zu seiner Adresse. [tabs[i].$1]: das erste Feld eines Positions-Records.

Zwei Arten der Navigation mit [go_router]:

  • [context.go('/doctors')]: Zu einer Adresse gehen. Der Bildschirmstapel wird ersetzt durch den Stapel, der von dieser Adresse beschrieben wird. So wechseln Sie die Tabs;
  • [context.push('/doctors/2')]: Den Bildschirm unter dieser Adresse oben auf den aktuellen Bildschirm legen. Die Zurück-Taste des Smartphones (oder [context.pop()]) nimmt ihn wieder vom Stapel, und Sie kehren dorthin zurück, wo Sie waren. So „betreten“ Sie eine Detailansicht.

5.1.5. Die Seiten

// lib/ex17_router/pages/home.dart
// Title: der Titel des Browser-Tabs (Web) oder der Anwendung in
// der Liste der zuletzt verwendeten Anwendungen (Android), solange die Seite angezeigt wird
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

class Home extends StatelessWidget {
  const Home({super.key});

  @override
  Widget build(BuildContext context) {
    return Title(
      title: 'Home',
      color: Colors.indigo,
      child: ListView(
        children: [
          const Text(
            'Welcome. Touch the tabs: the screen changes, and so does its address. On the web, '
            "the address is displayed in the browser's bar, the Back and Forward buttons "
            'work, as well as the reload (F5) of any page.',
          ),
          const SizedBox(height: 16),
          // Links zu bestimmten Adressen
          Wrap(
            spacing: 8,
            children: [
              OutlinedButton(onPressed: () => context.go('/physicians'), child: const Text('/physicians (redirect)')),
              OutlinedButton(onPressed: () => context.go('/unknown-page'), child: const Text('Broken link')),
            ],
          ),
        ],
      ),
    );
  }
}

Jede Seite platziert ein [Title]-Widget: Sein Titel ist der des Browser-Tabs (im Web) oder der der App in der Liste der zuletzt verwendeten Apps (unter [Android]), solange die Seite angezeigt wird. Zwei Schaltflächen führen zu bestimmten URLs: die Weiterleitung [/physicians] und eine URL, die nicht existiert.

// lib/ex17_router/pages/doctor_list.dart - Links mit einem Parameter
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import '../data.dart';

class DoctorList extends StatelessWidget {
  const DoctorList({super.key});

  @override
  Widget build(BuildContext context) {
    return Title(
      title: 'Doctors',
      color: Colors.indigo,
      child: ListView(
        children: [
          for (final m in doctors)
            ListTile(
              title: Text('${m.title} ${m.firstName} ${m.lastName}'),
              trailing: const Icon(Icons.chevron_right),
              // push: Der Bildschirm des Arztes wird GEPUSHT; die Zurück-Taste führt hierher zurück
              onTap: () => context.push('/doctors/${m.id}'),
            ),
        ],
      ),
    );
  }
}
  • Zeile 22: Das Antippen eines Arztes legt seinen Bildschirm auf den Stapel.
// =========================================================================
// lib/ex17_router/pages/doctor_detail.dart - eine Seite mit einem Parameter
// -------------------------------------------------------------------------
// Der Router übergibt ihr den Parameter :id des Pfads, einen STRING ("2").
// context.pop() poppt den Bildschirm (wie die Zurück-Taste); context.go()
// führt zu einer anderen Adresse. Wenn wir von /doctors/1 zu /doctors/2 wechseln,
// verwendet Flutter denselben Bildschirm weiter, der lediglich mit einer anderen id neu gebaut wird.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import '../data.dart';

class DoctorDetail extends StatelessWidget {
  final String id;

  const DoctorDetail({super.key, required this.id});

  @override
  Widget build(BuildContext context) {
    // int.tryParse: null, wenn id keine Zahl ist; firstWhere... orElse: nicht gefunden
    final number = int.tryParse(id);
    final found = doctors.where((m) => m.id == number);
    if (found.isEmpty) {
      return Text('Doctor no. $id does not exist.', style: const TextStyle(color: Colors.red));
    }
    final doctor = found.first;
    final next = doctor.id % doctors.length + 1;
    return Title(
      title: '${doctor.firstName} ${doctor.lastName}',
      color: Colors.indigo,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text('${doctor.title} ${doctor.firstName} ${doctor.lastName}', style: Theme.of(context).textTheme.titleLarge),
          Text('Specialty: ${doctor.specialty}'),
          const SizedBox(height: 16),
          Wrap(
            spacing: 8,
            children: [
              OutlinedButton(
                // canPop: Gibt es einen Bildschirm darunter? (nicht, wenn wir
                // direkt bei dieser Adresse angekommen sind, im Web)
                onPressed: () => context.canPop() ? context.pop() : context.go('/doctors'),
                child: const Text('Back'),
              ),
              FilledButton(
                // pushReplacement: ersetzt den aktuellen Bildschirm (kein Pushen)
                onPressed: () => context.pushReplacement('/doctors/$next'),
                child: const Text('Next doctor'),
              ),
            ],
          ),
        ],
      ),
    );
  }
}
  • Zeile 16: der Pfadparameter [:id], den der Router an den Konstruktor übergibt;
  • Zeilen 23–26: [int.tryParse]: die numerische ID oder [null]; Wird ein Arzt nicht gefunden, wird eine Meldung angezeigt;
  • Zeile 45: Zurück: Der Bildschirm wird vom Stapel genommen, wenn darunter einer liegt ([canPop]); andernfalls (wenn Sie im Web direkt über diese Adresse gekommen sind) gelangen Sie zur Liste;
  • Zeile 50: Der nächste Arzt ersetzt den aktuellen Bildschirm (kein Stapeln: Die Zurück-Taste führt zur Liste, nicht zum vorherigen Arzt).
// =========================================================================
// lib/ex17_router/pages/search.dart - eine von der Adresse gesteuerte Seite
// -------------------------------------------------------------------------
// /search?q=pediatrician: Die Seite wird vollständig durch ihre Adresse beschrieben.
// Im Web kann sie als Lesezeichen gespeichert und neu geladen werden, wir können
// zurückgehen. Suchen bedeutet, zur Adresse /search?q=<input> zu GEHEN:
// Die Seite zeigt an, was die Adresse sagt, und nichts anderes.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import '../data.dart';

class Search extends StatelessWidget {
  final String q;

  const Search({super.key, required this.q});

  void _search(BuildContext context, String input) {
    // Uri: baut die Adresse und kodiert dabei, was nötig ist (Leerzeichen -> %20)
    context.go(Uri(path: '/search', queryParameters: {'q': input.trim()}).toString());
  }

  @override
  Widget build(BuildContext context) {
    final results = doctors
        .where((m) => '${m.firstName} ${m.lastName} ${m.specialty}'.toLowerCase().contains(q.toLowerCase()))
        .toList();
    return Title(
      title: 'Search',
      color: Colors.indigo,
      child: ListView(
        children: [
          // ein NICHT kontrolliertes Feld, das mit dem Wert der Adresse beginnt;
          // key: ValueKey(q): Wenn sich die Adresse ändert (Zurück-Taste), erzeugt Flutter
          // das Feld neu, das dann den neuen Wert übernimmt
          TextFormField(
            key: ValueKey(q),
            initialValue: q,
            decoration: const InputDecoration(hintText: 'name or specialty', suffixIcon: Icon(Icons.search)),
            textInputAction: TextInputAction.search,
            onFieldSubmitted: (input) => _search(context, input),
          ),
          const SizedBox(height: 8),
          for (final m in results) ListTile(title: Text('${m.firstName} ${m.lastName} (${m.specialty})')),
          if (results.isEmpty)
            const ListTile(
              title: Text('No result.', style: TextStyle(color: Colors.grey)),
            ),
        ],
      ),
    );
  }
}
  • Zeilen 20–22: Suchen bedeutet, zur Adresse [/search?q=<input>] ZU GEHEN. [Uri] erzeugt die Adresse, indem es die notwendigen Informationen codiert (ein Leerzeichen wird zu [%20]). Die Seite wird vollständig durch ihre Adresse beschrieben: Im Web können Sie sie als Lesezeichen speichern, neu laden oder zurückgehen;
  • Zeilen 38–43: ein nicht validiertes Feld, das mit dem Wert der URL beginnt. [key: ValueKey(q)]: Ändert sich die URL (Zurück-Taste des Browsers), ändert sich der Schlüssel; [Flutter] erzeugt das Feld neu, das den neuen Wert übernimmt. [textInputAction: TextInputAction.search]: Die Eingabetaste der Smartphone-Tastatur fungiert als Lupe.
// =========================================================================
// lib/ex17_router/pages/deferred_loading.dart
// -------------------------------------------------------------------------
// Ein Bildschirm, dessen Code bei Bedarf geladen wird ("deferred"-Import):
// load() lädt den Code herunter (ein Future), builder() baut den Bildschirm,
// sobald der Code angekommen ist. Währenddessen: ein Ladeindikator.
// FutureBuilder baut seinen Inhalt neu, wenn das Future abgeschlossen ist
// (siehe Beispiel 19).
// =========================================================================

import 'package:flutter/material.dart';

class DeferredLoading extends StatefulWidget {
  final Future<void> Function() load;
  final Widget Function() builder;

  const DeferredLoading({super.key, required this.load, required this.builder});

  @override
  State<DeferredLoading> createState() => _DeferredLoadingState();
}

class _DeferredLoadingState extends State<DeferredLoading> {
  // Das Future wird EINMAL erzeugt (und nicht bei jedem build)
  late final Future<void> _loading = widget.load();

  @override
  Widget build(BuildContext context) {
    return FutureBuilder(
      future: _loading,
      builder: (context, snapshot) => snapshot.connectionState == ConnectionState.done
          ? widget.builder()
          : const Center(child: CircularProgressIndicator()),
    );
  }
}
  • Zeile 25: Der Code wird geladen und EINMAL initiiert (ein [late]-Feld, das beim ersten Lesen initialisiert wird): Würde er in [build] initiiert, würde jeder Neuaufbau ihn erneut auslösen;
  • Zeilen 29–33: [FutureBuilder] baut seinen Inhalt neu auf, wenn [Future] abgeschlossen ist: In der Zwischenzeit wird ein Ladeindikator angezeigt, danach der Bildschirm (siehe Beispiel 19).
// lib/ex17_router/pages/about.dart - eine bei Bedarf geladene Seite
// (siehe den Import "deferred as about" in routes.dart)
import 'package:flutter/material.dart';

class About extends StatelessWidget {
  const About({super.key});

  @override
  Widget build(BuildContext context) {
    return Title(
      title: 'About',
      color: Colors.indigo,
      child: const Text(
        'On the web, this page was downloaded on the first visit (Network tab '
        'of the developer tools: a main.dart.js_1.part.js file). On a phone, '
        'all the code is already in the application.',
      ),
    );
  }
}
// lib/ex17_router/pages/not_found_page.dart - der Bildschirm für unbekannte Adressen
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

class NotFoundPage extends StatelessWidget {
  final String address;

  const NotFoundPage({super.key, required this.address});

  @override
  Widget build(BuildContext context) {
    return Title(
      title: 'Page not found',
      color: Colors.indigo,
      child: Scaffold(
        appBar: AppBar(title: const Text('Page not found')),
        body: Padding(
          padding: const EdgeInsets.all(16),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text('No page at the address $address.', style: const TextStyle(color: Colors.red)),
              const SizedBox(height: 16),
              FilledButton(onPressed: () => context.go('/'), child: const Text('Back to home')),
            ],
          ),
        ),
      ),
    );
  }
}

Der Bildschirm für unbekannte Adressen hat sein eigenes [Scaffold]: Er wird von [errorBuilder] außerhalb der Shell erzeugt.

5.1.6. Ausführung

Der Startbildschirm; die Details eines Arztes (gestapelt: Die obere Leiste hat sich nicht geändert, aber die Zurück-Taste des Smartphones führt Sie zur Liste zurück); die Suche; eine unbekannte Adresse:

Im Web ([flutter run -d chrome]) erscheint die Adresse in der Browserleiste, die Schaltflächen „Zurück“ und „Vor“ funktionieren, und Sie können eine Adresse manuell eingeben.

5.2. Beispiel 18: Navigations-Guards

5.2.1. Die Sitzung

// =========================================================================
// lib/ex18_guards/session.dart - eine SIMULIERTE Sitzung (ohne Server)
// -------------------------------------------------------------------------
// Der angemeldete Benutzer muss den BILDSCHIRMEN (der oberen Leiste,
// dem Terminkalender) und den GUARDS des Routers (Funktionen, die keine
// Widgets sind) bekannt sein. Er wird in einem einzigen Objekt gespeichert, einem ChangeNotifier:
//   - ein privates Feld, der Zustand;
//   - Methoden zum Lesen und Ändern;
//   - notifyListeners(): benachrichtigt seine Abonnenten (den Router, die Bildschirme),
//     wenn er sich ändert.
// (Beispiel 23 macht dasselbe mit einem echten Server.)
// =========================================================================

import 'package:flutter/foundation.dart';

enum Role { admin, doctor, user }

typedef User = ({String login, Role role});

// drei "fest codierte" Konten (Passwort = Login)
const _accounts = {'admin': Role.admin, 'pelissier': Role.doctor, 'martin': Role.user};

class Session extends ChangeNotifier {
  User? _user; // der Zustand: null, niemand ist angemeldet

  User? get user => _user;

  bool logIn(String login, String password) {
    final role = _accounts[login];
    if (role == null || password != login) {
      return false;
    }
    _user = (login: login, role: role);
    notifyListeners();
    return true;
  }

  void logOut() {
    _user = null;
    notifyListeners();
  }
}

// die einzige Sitzung der Anwendung
final session = Session();

Der angemeldete Benutzer muss von den Bildschirmen (der oberen Leiste, dem Terminkalender) und den Kontrollen des Routers erkannt werden – Funktionen, die keine Widgets sind. Er wird in einem einzigen Objekt gespeichert, einem [ChangeNotifier] (siehe Beispiel 14):

  • Zeile 24: der Status: ein Benutzer oder [null];
  • Zeilen 28–35: die simulierte Anmeldung: drei „fest codierte“ Konten (Passwort = Login). Sie benachrichtigt ihre Abonnenten ([notifyListeners()]);
  • Zeile 45: die einzige Sitzung der Anwendung, eine globale Variable. (Beispiel 23 wird dasselbe mit einem echten Server tun.)

5.2.2. Guards und geschützte Pfade

// =========================================================================
// lib/ex18_guards/routes.dart - durch Guards GESCHÜTZTE Routen
// -------------------------------------------------------------------------
// redirect: eine Funktion, die go_router VOR jeder Navigation aufruft
// (die des GoRouter: für alle Routen; die einer GoRoute:
// nur für sie). Sie erhält den Zustand der Navigation (state.uri:
// die angeforderte Adresse) und gibt zurück:
//   - null: Die Navigation wird fortgesetzt;
//   - eine Adresse: Die Navigation wird durch eine Navigation zu
//     dieser Adresse ersetzt.
// refreshListenable: ein Objekt, auf das GEHÖRT wird; wenn es eine
// Änderung meldet (die Sitzung: Login, Logout), wertet der Router
// seine Guards für den aktuellen Bildschirm neu aus.
//
// Es ist das clientseitige Gegenstück zu den Guards von NestJS (JwtAuthGuard,
// RolesGuard) - mit einem GRUNDLEGENDEN Unterschied: Ein Client-Guard ist
// nur eine Erleichterung. Die Anwendung liegt in den Händen des Benutzers, der sie
// nach Belieben ändern kann. Der eigentliche Schutz der Daten bleibt
// der des SERVERS (siehe das Kapitel über die Blackbox).
// =========================================================================

import 'package:go_router/go_router.dart';

import 'shell.dart';
import 'pages/home.dart';
import 'pages/administration.dart' deferred as administration;
import 'pages/schedule.dart';
import 'pages/login.dart';
import '../ex17_router/pages/deferred_loading.dart';
import 'session.dart';

// der Guard "Anmeldung erforderlich": nicht angemeldet -> zur Login-Seite,
// mit dem Merken, wohin der Benutzer wollte
String? requireLogin(GoRouterState state) {
  if (session.user == null) {
    return Uri(path: '/login', queryParameters: {'redirect': state.uri.toString()}).toString();
  }
  return null;
}

// der Guard "Rolle erforderlich": eine Funktion, die einen Guard BAUT
String? Function(GoRouterState) requireRole(Set<Role> roles) {
  return (state) {
    final u = session.user;
    if (u == null || !roles.contains(u.role)) {
      // angemeldet, aber nicht mit der richtigen Rolle: zurück zur Startseite, mit einer Begründung
      return Uri(path: '/', queryParameters: {'denied': state.uri.path}).toString();
    }
    return null;
  };
}

final router = GoRouter(
  refreshListenable: session,
  routes: [
    ShellRoute(
      builder: (context, state, child) => Shell(child: child),
      routes: [
        GoRoute(
          path: '/',
          builder: (context, state) => Home(denied: state.uri.queryParameters['denied']),
        ),
        GoRoute(
          path: '/login',
          builder: (context, state) => Login(redirectTo: state.uri.queryParameters['redirect']),
        ),
        GoRoute(
          path: '/schedule',
          redirect: (context, state) => requireLogin(state),
          builder: (context, state) => const Schedule(),
        ),
        GoRoute(
          path: '/administration',
          // die Guards, der Reihe nach: Der erste, der eine Adresse zurückgibt, gewinnt
          redirect: (context, state) => requireLogin(state) ?? requireRole({Role.admin})(state),
          // Der Code der Seite wird erst geladen, wenn die Guards passiert sind
          builder: (context, state) =>
              DeferredLoading(load: administration.loadLibrary, builder: () => administration.Administration()),
        ),
      ],
    ),
  ],
  // jede andere Adresse (keine Route passt): zurück zur Startseite
  onException: (context, state, router) => router.go('/'),
);

Bei [go_router] ist ein Guard eine redirect-Funktion, die vor jeder Navigation aufgerufen wird (die von [GoRouter]: für alle Routen; die von [GoRoute]: nur für diese Route). Sie erhält den Navigationszustand und gibt zurück:

  • [null]: Die Navigation wird fortgesetzt;
  • eine Adresse: Die Navigation wird durch eine Navigation zu dieser Adresse ersetzt.

Der Code:

  • Zeilen 34–38: der Guard „Anmeldung erforderlich“: nicht angemeldet? Leitet zur Anmeldeseite weiter und merkt sich dabei das beabsichtigte Ziel (Parameter [redirect]);
  • Zeilen 42–47: Der Guard „Rolle erforderlich“ wird von einer Funktion erzeugt, die die zulässigen Rollen erhält und den Guard zurückgibt. Angemeldet, aber ohne die richtige Rolle: Weiterleitung zur Startseite mit einem Grund (Parameter [denied]);
  • Zeile 54: Der Router überwacht die Sitzung: Erkennt er eine Änderung (Anmeldung, Abmeldung), wertet er die Guards für den aktuellen Bildschirm erneut aus. Wenn Sie sich im Terminkalender abmelden, werden Sie sofort zur Anmeldeseite weitergeleitet;
  • Zeile 69: Der Terminkalender setzt voraus, dass der Benutzer angemeldet ist;
  • Zeile 75: Die Administrationsseite setzt voraus, dass der Benutzer angemeldet ist UND die Rolle (ADMIN) hat: Die Prüfungen werden mit [??] verkettet; die erste, die eine Adresse zurückgibt, hat Vorrang;
  • Zeilen 77–78: Der Code der Administrationsseite wird erst geladen, nachdem die Guards durchlaufen wurden;
  • Zeile 84: Jede andere Adresse leitet zur Startseite weiter.

Dies ist das clientseitige Gegenstück zu den serverseitigen Prüfungen von [NestJS] ([JwtAuthGuard], [RolesGuard]), mit einem GRUNDLEGENDEN Unterschied: Ein clientseitiger Guard ist lediglich eine Komfortfunktion (um die Anzeige eines unnötigen Bildschirms zu vermeiden). Die Anwendung liegt in den Händen des Benutzers, der sie beliebig verändern kann; der eigentliche Datenschutz bleibt auf dem Server, der bei jeder Anfrage alles erneut prüft (siehe das Kapitel über die Blackbox).

5.2.3. Die Shell und die Seiten

// =========================================================================
// lib/ex18_guards/shell.dart - die Links und der angemeldete Benutzer
// -------------------------------------------------------------------------
// ListenableBuilder: baut seinen Inhalt jedes Mal neu, wenn das abgehörte
// Objekt (die Sitzung) eine Änderung meldet. Die obere Leiste folgt daher
// dem angemeldeten Benutzer.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import 'session.dart';

class Shell extends StatelessWidget {
  final Widget child;

  const Shell({super.key, required this.child});

  @override
  Widget build(BuildContext context) {
    final path = GoRouterState.of(context).uri.path;

    // ein Link: fett, wenn er die angezeigte Seite bezeichnet
    Widget link(String target, String label) => TextButton(
      onPressed: () => context.go(target),
      child: Text(label, style: TextStyle(fontWeight: path == target ? FontWeight.bold : FontWeight.normal)),
    );

    return Scaffold(
      appBar: AppBar(
        title: const Text('Example 18 - the guards'),
        actions: [
          ListenableBuilder(
            listenable: session,
            builder: (context, _) {
              final u = session.user;
              if (u == null) {
                return TextButton(onPressed: () => context.go('/login'), child: const Text('log in'));
              }
              return Row(
                children: [
                  Chip(label: Text('${u.login} ${u.role.name.toUpperCase()}')),
                  IconButton(
                    tooltip: 'log out',
                    icon: const Icon(Icons.logout),
                    onPressed: () {
                      session.logOut();
                      context.go('/');
                    },
                  ),
                ],
              );
            },
          ),
        ],
      ),
      body: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Wrap(
            children: [
              link('/', 'Home'),
              link('/schedule', 'Schedule (logged in)'),
              link('/administration', 'Administration (ADMIN)'),
            ],
          ),
          const Divider(),
          Expanded(
            child: Padding(padding: const EdgeInsets.all(16), child: child),
          ),
        ],
      ),
    );
  }
}
  • Zeilen 24–26: eine lokale Funktion, die einen Link erzeugt: fett, wenn er auf die aktuell angezeigte Seite verweist;
  • Zeilen 33–37: [ListenableBuilder] baut seinen Inhalt jedes Mal neu auf, wenn das überwachte Objekt (die Sitzung) eine Änderung signalisiert: Die obere Leiste folgt dem angemeldeten Benutzer;
  • Zeilen 46–48: Abmeldung, dann die Willkommensseite.
// =========================================================================
// lib/ex18_guards/pages/login.dart
// -------------------------------------------------------------------------
// Nach der Anmeldung wird der Benutzer zu der Seite zurückgeschickt, die er
// öffnen wollte (Parameter ?redirect=..., vom Guard gesetzt), oder zur Startseite.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import '../session.dart';

class Login extends StatefulWidget {
  final String? redirectTo;

  const Login({super.key, this.redirectTo});

  @override
  State<Login> createState() => _LoginState();
}

class _LoginState extends State<Login> {
  final _login = TextEditingController();
  final _password = TextEditingController();
  bool _error = false;

  @override
  void dispose() {
    _login.dispose();
    _password.dispose();
    super.dispose();
  }

  void _submit() {
    if (!session.logIn(_login.text.trim(), _password.text)) {
      setState(() => _error = true);
      return;
    }
    // nur ein INTERNER Pfad wird akzeptiert: Er beginnt mit /, aber nicht mit //
    // (//site.com/... bezeichnet eine ANDERE Website) - keine Weiterleitung zu einer anderen Website
    final r = widget.redirectTo;
    final internal = r != null && r.startsWith('/') && !r.startsWith('//');
    context.go(internal ? r : '/');
  }

  @override
  Widget build(BuildContext context) {
    return ListView(
      children: [
        if (widget.redirectTo != null)
          Card(
            color: Colors.amber.shade50,
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Text('Log in to open ${widget.redirectTo}.'),
            ),
          ),
        TextField(
          controller: _login,
          decoration: const InputDecoration(labelText: 'login'),
        ),
        TextField(
          controller: _password,
          obscureText: true,
          decoration: const InputDecoration(labelText: 'password'),
          onSubmitted: (_) => _submit(),
        ),
        const SizedBox(height: 16),
        Align(
          alignment: Alignment.centerLeft,
          child: FilledButton(onPressed: _submit, child: const Text('Log in')),
        ),
        if (_error)
          const Padding(
            padding: EdgeInsets.only(top: 8),
            child: Text('Incorrect login or password.', style: TextStyle(color: Colors.red)),
          ),
      ],
    );
  }
}
  • Zeilen 41–43: Nach der Anmeldung wird der Benutzer auf die Seite weitergeleitet, die er öffnen wollte (Parameter [redirect] vom Guard gesetzt), oder auf die Startseite. Es wird nur ein interner Pfad akzeptiert: Er beginnt mit [/], aber nicht mit [//] ([//site.com/...] verweist auf eine ANDERE Website). Eine von Dritten erzeugte Anmelde-URL im Web ([/login?redirect=//pirate-site.com]) führt daher nie woandershin.

Die übrigen Seiten sind sehr einfach:

import 'package:flutter/material.dart';

class Home extends StatelessWidget {
  // ?denied=...: vom Guard requireRole gesetzt, wenn die Rolle nicht passt
  final String? denied;

  const Home({super.key, this.denied});

  @override
  Widget build(BuildContext context) {
    return ListView(
      children: [
        if (denied != null)
          Card(
            color: Colors.red.shade50,
            child: Padding(padding: const EdgeInsets.all(12), child: Text('Your role does not allow opening $denied.')),
          ),
        const Text(
          'Public page. Try the two other links, logged in or not '
          '(admin, pelissier, martin - password = login).',
        ),
      ],
    );
  }
}
import 'package:flutter/material.dart';

import '../session.dart';

class Schedule extends StatelessWidget {
  const Schedule({super.key});

  @override
  Widget build(BuildContext context) {
    return Text.rich(
      TextSpan(
        children: [
          const TextSpan(text: 'The schedule of '),
          TextSpan(
            text: session.user?.login,
            style: const TextStyle(fontWeight: FontWeight.bold),
          ),
          const TextSpan(text: ': this page requires being logged in.'),
        ],
      ),
    );
  }
}
import 'package:flutter/material.dart';

class Administration extends StatelessWidget {
  const Administration({super.key});

  @override
  Widget build(BuildContext context) {
    return const Text(
      'Administration: page reserved for the ADMIN role, loaded on demand (on the web, its '
      'code is only downloaded on the first visit, and only if the guards allowed it).',
    );
  }
}
// =========================================================================
// lib/ex18_guards/main.dart
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_web_plugins/url_strategy.dart';

import 'routes.dart';

void main() {
  usePathUrlStrategy();
  runApp(
    MaterialApp.router(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      routerConfig: router,
    ),
  );
}

5.2.4. Ausführung

Ohne angemeldet zu sein, fordern wir den Zugriff auf die Administrationsoberfläche an: Der Guard leitet uns zur Anmeldeseite weiter (links). Wir melden uns mit dem Konto [martin] (Rolle USER) an: Die Anmeldung führt uns zurück zur Administrationsoberfläche, wo der zweite Guard den Zugriff verweigert (in der Mitte). Nach der Anmeldung mit dem Konto [admin]öffnet sich die Seite (rechts):