Navigation

De Navigator.push à go_router : routes paramétrées, bottom navigation qui garde l'état des onglets, garde d'authentification branchée sur Riverpod, routes typées, deep links vérifiés. Dans une app bancaire, la navigation est aussi une question de sécurité : aucun écran protégé ne doit être atteignable sans session.

Navigator 1.0 : la pile impérative

Le Navigator historique gère une pile de Route. On empile avec push, on dépile avec pop. Une route peut renvoyer un résultat : push retourne un Future complété par la valeur passée à pop. Ce modèle reste parfaitement valable pour des flux locaux : sélecteur, dialogue, assistant en plusieurs étapes.

// Écran de transfert : on ouvre le sélecteur et on attend le bénéficiaire choisi.
Future<void> pickBeneficiary(BuildContext context) async {
  final selected = await Navigator.of(context).push<Beneficiary>(
    MaterialPageRoute(builder: (_) => const BeneficiaryPickerScreen()),
  );
  // Après un await, le widget a pu être démonté : on vérifie avant d'utiliser context.
  if (!context.mounted || selected == null) return;
  ScaffoldMessenger.of(context).showSnackBar(
    SnackBar(content: Text('Bénéficiaire : ${selected.name}')),
  );
}

// Dans le sélecteur :
// Navigator.of(context).pop(beneficiary);

Routes nommées et leurs limites

Les routes nommées (routes: {'/transfer': ...}, Navigator.pushNamed) centralisent les écrans, mais la documentation officielle ne les recommande plus pour la plupart des apps. Les arguments passent en Object? non typé, les chemins paramétrés (/transactions/42) demandent un onGenerateRoute écrit à la main, le comportement des deep links n'est pas personnalisable, et sur le web le bouton « suivant » du navigateur n'est pas géré.

// Pile : Transfert ─push─▶ Montant ─push─▶ Confirmation.
// Depuis Confirmation, on revient à Transfert ; le Future du push(Montant),
// attendu dans l'écran Transfert, reçoit TransferOutcome.completed.
Navigator.popUntilWithResult<TransferOutcome>(
  context,
  ModalRoute.withName('/transfer'),
  TransferOutcome.completed,
);

Navigator 2.0 et la Router API

La Router API (dite Navigator 2.0) est née de trois besoins que le modèle impératif couvre mal : le web (la barre d'adresse doit refléter l'écran et inversement), les deep links (ouvrir l'app directement sur /transactions/42 avec la bonne pile en dessous), et une navigation déclarative (la pile de pages est une fonction de l'état de l'app, comme l'UI est une fonction de l'état).

L'API est puissante mais verbeuse : écrire soi-même un RouterDelegate et un parser pour une vraie app représente beaucoup de code et de pièges. En pratique, on utilise un package au-dessus. go_router est maintenu par l'équipe Flutter et référencé dans la documentation officielle.

go_router en détail

La version stable en octobre 2026 est la 18.x. Depuis la 18.0, go_router dépend de material_ui et cupertino_ui et exige Flutter 3.44 minimum. Changements cassants à connaître des versions précédentes : URL sensibles à la casse par défaut (15.0, paramètre caseSensitive), onExit qui reçoit aussi le GoRouterState (14.0), observers notifiés pour les navigations dans les ShellRoute (17.0).

Routes, paramètres de chemin et de query

GoRoute(
  path: '/transactions',
  builder: (context, state) {
    // Paramètre de query optionnel : /transactions?type=bill
    final type = state.uri.queryParameters['type'];
    return HistoryScreen(typeFilter: type);
  },
  routes: [
    // Sous-route relative : /transactions/:id
    GoRoute(
      path: ':id',
      builder: (context, state) =>
          TransactionDetailScreen(id: state.pathParameters['id']!),
    ),
  ],
);

// Navigation :
// context.go('/transactions/tx_42');
// context.go(Uri(path: '/transactions', queryParameters: {'type': 'bill'}).toString());

Les sous-routes construisent la pile : aller sur /transactions/tx_42 affiche le détail au-dessus de l'historique, avec un bouton retour qui ramène à la liste, y compris quand on arrive par un deep link.

extra et ses limites

context.go('/transactions/tx_42', extra: transaction) passe un objet quelconque à l'écran cible. Pratique pour éviter un appel réseau, mais extra n'est pas dans l'URL : il est perdu sur un deep link, au rechargement d'une page web, et à la restauration d'état après la mort du processus, sauf à fournir un extraCodec pour le sérialiser. Règle : l'URL doit suffire à reconstruire l'écran (l'id), extra n'est qu'une optimisation facultative.

builder: (context, state) => TransactionDetailScreen(tx: state.extra! as Transaction),
// crash sur deep link : extra est null

builder: (context, state) => TransactionDetailScreen(
  id: state.pathParameters['id']!,
  initial: state.extra as Transaction?, // affichage immédiat si présent, sinon chargement par id
),

ShellRoute et StatefulShellRoute

Une ShellRoute enveloppe ses sous-routes dans un widget commun (scaffold avec bottom bar) et leur donne un Navigator imbriqué. Mais changer d'onglet remplace la pile : on perd la position de défilement et la sous-page ouverte. StatefulShellRoute donne à chaque onglet (branch) son propre navigator, conservé en mémoire. StatefulShellRoute.indexedStack les place dans un IndexedStack.

StatefulShellRoute.indexedStack(
  builder: (context, state, navigationShell) =>
      AppShell(navigationShell: navigationShell),
  branches: [
    StatefulShellBranch(routes: [
      GoRoute(path: '/home', builder: (context, state) => const HomeScreen()),
    ]),
    StatefulShellBranch(routes: [
      GoRoute(
        path: '/transactions',
        builder: (context, state) => const HistoryScreen(),
        routes: [
          GoRoute(
            path: ':id',
            builder: (context, state) =>
                TransactionDetailScreen(id: state.pathParameters['id']!),
          ),
        ],
      ),
    ]),
    StatefulShellBranch(routes: [
      GoRoute(path: '/profile', builder: (context, state) => const ProfileScreen()),
    ]),
  ],
);

class AppShell extends StatelessWidget {
  const AppShell({super.key, required this.navigationShell});

  final StatefulNavigationShell navigationShell;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: navigationShell,
      bottomNavigationBar: NavigationBar(
        selectedIndex: navigationShell.currentIndex,
        onDestinationSelected: (index) => navigationShell.goBranch(
          index,
          // Retaper l'onglet actif ramène à sa racine (convention mobile).
          initialLocation: index == navigationShell.currentIndex,
        ),
        destinations: const [
          NavigationDestination(icon: Icon(Icons.home_outlined), label: 'Accueil'),
          NavigationDestination(icon: Icon(Icons.receipt_long), label: 'Historique'),
          NavigationDestination(icon: Icon(Icons.person_outline), label: 'Profil'),
        ],
      ),
    );
  }
}

Un écran qui doit masquer la bottom bar (le flux de transfert, par exemple) se déclare comme route de premier niveau, hors du shell : il s'affiche alors sur le navigator racine, par-dessus le scaffold. StatefulShellBranch(preload: true) construit une branche avant sa première visite, à réserver aux onglets dont le chargement initial est visible.

Garde d'authentification : redirect et refreshListenable

redirect est appelé avant chaque navigation : il renvoie null pour laisser passer, ou un autre chemin. Mais la navigation n'est pas le seul déclencheur : quand la session expire, ou quand l'utilisateur se connecte, il faut réévaluer les redirections sur l'écran courant. C'est le rôle de refreshListenable : chaque notification relance redirect.

Avec Riverpod 3, l'état d'auth vit dans un Notifier (chapitre 06). Il faut un pont entre ce provider et un Listenable. Le pattern correct :

sealed class AuthState {
  const AuthState();
}

final class AuthUnknown extends AuthState {
  const AuthUnknown(); // au démarrage, lecture du stockage sécurisé en cours
}

final class Authenticated extends AuthState {
  const Authenticated(this.userId);
  final String userId;
}

final class Unauthenticated extends AuthState {
  const Unauthenticated();
}

final routerProvider = Provider<GoRouter>((ref) {
  // Pont Riverpod ─▶ Listenable. On utilise listen, pas watch :
  // watch recréerait le GoRouter (et perdrait la pile) à chaque changement d'auth.
  final auth = ValueNotifier<AuthState>(ref.read(authProvider));
  ref.listen<AuthState>(authProvider, (_, next) => auth.value = next);

  final router = GoRouter(
    initialLocation: '/home',
    refreshListenable: auth,
    redirect: (context, state) => authRedirect(auth.value, state.uri),
    routes: appRoutes,
  );

  ref.onDispose(() {
    router.dispose();
    auth.dispose();
  });
  return router;
});

/// Fonction pure : testable sans widget ni router.
String? authRedirect(AuthState auth, Uri uri) {
  final path = uri.path;
  final onLogin = path == '/login';
  final onSplash = path == '/splash';

  switch (auth) {
    case AuthUnknown():
      return onSplash ? null : _withFrom('/splash', uri);
    case Unauthenticated():
      return onLogin ? null : _withFrom('/login', uri);
    case Authenticated():
      if (!onLogin && !onSplash) return null;
      return _safeFrom(uri.queryParameters['from']) ?? '/home';
  }
}

String _withFrom(String target, Uri uri) {
  // On conserve la destination demandée (deep link compris) pour y revenir après login.
  final from = uri.queryParameters['from'] ?? uri.toString();
  if (from == '/' || from == target) return target;
  return Uri(path: target, queryParameters: {'from': from}).toString();
}

String? _safeFrom(String? from) {
  // Anti open-redirect : uniquement un chemin interne.
  if (from == null || !from.startsWith('/') || from.startsWith('//')) return null;
  return from;
}

// Dans l'app :
class WalletApp extends ConsumerWidget {
  const WalletApp({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return MaterialApp.router(routerConfig: ref.watch(routerProvider));
  }
}

Redirection et sécurité : la garde côté client améliore l'expérience mais ne protège rien à elle seule. Le backend refuse toute requête sans token valide. Côté app, l'écran protégé ne doit pas afficher de données en cache avant que la session soit confirmée, d'où l'état AuthUnknown et l'écran de splash.

Routes typées avec go_router_builder

Les chemins en chaînes ('/transactions/$id') ont deux défauts : une faute de frappe ne se voit qu'à l'exécution, et les paramètres sont des String à parser à la main. go_router_builder génère, à partir de classes annotées, la configuration et des méthodes de navigation typées. Dans une équipe de dix développeurs, c'est la différence entre un renommage sûr par le compilateur et une recherche textuelle.

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

part 'routes.g.dart';

@TypedGoRoute<HistoryRoute>(
  path: '/transactions',
  routes: [TypedGoRoute<TransactionDetailRoute>(path: ':id')],
)
class HistoryRoute extends GoRouteData with $HistoryRoute {
  const HistoryRoute({this.type});

  final String? type; // champ hors du chemin : devient un paramètre de query

  @override
  Widget build(BuildContext context, GoRouterState state) =>
      HistoryScreen(typeFilter: type);
}

class TransactionDetailRoute extends GoRouteData with $TransactionDetailRoute {
  const TransactionDetailRoute({required this.id});

  final String id; // lu depuis :id, typé

  @override
  Widget build(BuildContext context, GoRouterState state) =>
      TransactionDetailScreen(id: id);
}

// Utilisation :
// const TransactionDetailRoute(id: 'tx_42').go(context);
// final ok = await const HistoryRoute(type: 'bill').push<bool>(context);
// Dans un redirect : return const HistoryRoute().location;
// Configuration : GoRouter(routes: $appRoutes, ...)

Le mixin généré ($HistoryRoute) fournit location, go, push, pushReplacement et replace (go_router 16+ et go_router_builder 3+). Les types simples (int, enum, DateTime...) sont convertis automatiquement ; un champ nommé $extra reçoit l'extra. Il existe aussi TypedShellRoute et TypedStatefulShellRoute. Génération : dart run build_runner build.

go ou push

Dans un shell, go('/transactions/tx_42') depuis l'accueil bascule sur l'onglet Historique ; push empilerait le détail dans l'onglet Accueil. Les deux sont légitimes, mais le choix doit être volontaire et cohérent dans l'app.

Touche retour Android et predictive back

Depuis Android 14, le predictive back (retour prédictif) montre un aperçu de l'écran précédent pendant le geste. Cela impose que l'app déclare à l'avance si elle accepte le retour : l'ancien WillPopScope, qui décidait au moment du geste, est remplacé par PopScope. canPop: false bloque le retour (et désactive l'aperçu) ; onPopInvokedWithResult est appelé après la tentative, qu'elle ait abouti ou non.

class TransferScreen extends StatefulWidget {
  const TransferScreen({super.key});

  @override
  State<TransferScreen> createState() => _TransferScreenState();
}

class _TransferScreenState extends State<TransferScreen> {
  bool _dirty = false; // passe à true dès qu'un champ est rempli

  @override
  Widget build(BuildContext context) {
    return PopScope<Object?>(
      canPop: !_dirty,
      onPopInvokedWithResult: (didPop, result) async {
        if (didPop) return; // retour déjà effectué
        final leave = await showDialog<bool>(
          context: context,
          builder: (context) => AlertDialog(
            title: const Text('Abandonner le transfert ?'),
            actions: [
              TextButton(onPressed: () => Navigator.pop(context, false), child: const Text('Rester')),
              TextButton(onPressed: () => Navigator.pop(context, true), child: const Text('Abandonner')),
            ],
          ),
        );
        if (leave == true && context.mounted) Navigator.of(context).pop();
      },
      child: TransferForm(onChanged: () => setState(() => _dirty = true)),
    );
  }
}

Côté Android, le retour prédictif est activé par android:enableOnBackInvokedCallback="true" dans le manifeste. Les transitions de page prédictives se règlent via PageTransitionsTheme (PredictiveBackPageTransitionsBuilder) ; selon la version de Flutter et de material_ui, elles sont activées par défaut ou à activer explicitement : vérifiez la page « Predictive back » de la documentation pour votre version. Avec go_router, GoRoute.onExit permet aussi de confirmer la sortie d'une route.

Deep links, App Links et Universal Links

Trois mécanismes, trois niveaux de confiance :

<!-- Schéma custom -->
<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="wallet" android:host="transactions" />
</intent-filter>

<!-- App Link vérifié -->
<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" android:host="wallet.example.com" android:pathPrefix="/transactions" />
</intent-filter>

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.wallet",
    "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

{
  "applinks": {
    "details": [{
      "appIDs": ["ABCDE12345.com.example.wallet"],
      "components": [{ "/": "/transactions/*" }]
    }]
  }
}

Côté iOS : capability Associated Domains avec applinks:wallet.example.com, et pour le schéma custom une entrée CFBundleURLTypes dans Info.plist. Le fichier AASA est servi en HTTPS, sans extension, en application/json, sans redirection.

Le cas du schéma custom avec go_router

Flutter gère les deep links nativement (désactivable par flutter_deeplinking_enabled à false sur Android ou FlutterDeepLinkingEnabled sur iOS si un plugin s'en charge). Sur Android, le moteur transmet l'URI complète au router. Or dans wallet://transactions/42, transactions est l'hôte de l'URI et le chemin vaut /42 : go_router, qui fait la correspondance sur le chemin, ne trouvera pas la route. On normalise dans redirect, qui est évalué même quand aucune route ne correspond :

/// wallet://transactions/42 ─▶ /transactions/42. Renvoie null si rien à faire.
String? normalizeCustomScheme(Uri uri) {
  if (uri.scheme != 'wallet') return null;
  return Uri(
    path: '/${uri.host}${uri.path}',
    queryParameters: uri.queryParameters.isEmpty ? null : uri.queryParameters,
  ).toString();
}

// Dans le GoRouter :
// redirect: (context, state) =>
//     normalizeCustomScheme(state.uri) ?? authRedirect(auth.value, state.uri),

Point à vérifier sur votre version : le comportement exact de l'embedder iOS pour les schémas custom. Loguez state.uri dans redirect et testez sur les deux plateformes.

# Android : app lancée ou non
adb shell am start -a android.intent.action.VIEW -d "wallet://transactions/tx_42"
adb shell am start -a android.intent.action.VIEW -d "https://wallet.example.com/transactions/tx_42"
# État de vérification des App Links
adb shell pm get-app-links com.example.wallet
# Simulateur iOS
xcrun simctl openurl booted "wallet://transactions/tx_42"

Un deep link vers un écran protégé passe par la même garde : l'utilisateur non connecté est envoyé sur /login?from=/transactions/tx_42, puis ramené sur le détail après connexion. Le détail recharge la transaction par son id ; il ne fait jamais confiance à un montant ou à un statut passé dans l'URL.

Navigation et tests

Trois niveaux, du plus rentable au plus coûteux. Premier niveau : la logique de redirection en fonction pure (authRedirect, normalizeCustomScheme) se teste en tests unitaires, sans widget. Deuxième niveau : un test de widget avec un vrai GoRouter et des écrans factices vérifie qu'un tap mène au bon écran. Troisième niveau : le deep link de bout en bout en test d'intégration. Le chapitre 12 détaille l'outillage.

test('un utilisateur non connecté est envoyé au login avec la destination', () {
  final target = authRedirect(
    const Unauthenticated(),
    Uri.parse('/transactions/tx_42'),
  );
  expect(target, '/login?from=%2Ftransactions%2Ftx_42');
});

test('le paramètre from externe est ignoré après login', () {
  final target = authRedirect(
    const Authenticated('u1'),
    Uri.parse('/login?from=https://evil.example'),
  );
  expect(target, '/home');
});

testWidgets('taper une transaction ouvre son détail', (tester) async {
  final router = GoRouter(initialLocation: '/transactions', routes: testRoutes);
  addTearDown(router.dispose);
  await tester.pumpWidget(MaterialApp.router(routerConfig: router));

  await tester.tap(find.text('tx_42'));
  await tester.pumpAndSettle();

  expect(router.state.uri.path, '/transactions/tx_42');
  expect(find.byType(TransactionDetailScreen), findsOneWidget);
});

Comparaison rapide avec auto_router

En entretien, l'important n'est pas le package mais les concepts : pile déclarative, URL comme source de vérité, gardes réévaluées sur changement d'état, deep links vérifiés.

Questions d'entretien

Exercices

Quiz

12 questions. Corrigez, relisez les explications, refaites-le 48 h plus tard.

Pour aller plus loin

• Navigation and routing
• Deep linking
• Set up app links for Android
• Set up universal links for iOS
• Predictive back
• go_router et go_router_builder
• auto_route
• Android App Links
• Supporting associated domains