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
| // "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):