Qora
Usage avec Flutter

Widgets de statut réseau

NetworkStatusBuilder et NetworkStatusIndicator : widgets réactifs pour afficher l'état hors-ligne dans les applications Flutter.

NetworkStatusBuilder et NetworkStatusIndicator sont deux widgets Flutter qui s'abonnent au ConnectivityManager exposé par le QoraScope le plus proche et se reconstruisent à chaque changement de NetworkStatus.

Prérequis

Un QoraScope avec un ConnectivityManager doit être un ancêtre. Sans lui, les deux widgets émettent NetworkStatus.unknown et ne se mettent jamais à jour.

lib/main.dart
QoraScope(
  client: client,
  connectivityManager: FlutterConnectivityManager(), // requis
  child: const MyApp(),
)

NetworkStatusIndicator

Le widget de haut niveau. Encapsule l'application (ou un sous-arbre) et superpose une bannière hors-ligne quand NetworkStatus.offline est détecté.

Bannière par défaut

lib/main.dart
QoraScope(
  client: client,
  connectivityManager: FlutterConnectivityManager(),
  child: NetworkStatusIndicator(
    child: const MyApp(),
  ),
)

Affiche une fine barre sombre semi-transparente en bas de l'écran avec une icône wifi-off et le texte "Mode hors-ligne". Pas de dépendance Material : utilise uniquement flutter/widgets.dart.

Bannière hors-ligne personnalisée

Remplacer l'UI hors-ligne avec offlineBanner :

lib/main.dart
NetworkStatusIndicator(
  offlineBanner: (context) => Container(
    color: Colors.orange.shade800,
    padding: const EdgeInsets.symmetric(vertical: 8, horizontal: 16),
    child: const Row(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Icon(Icons.wifi_off, color: Colors.white, size: 16),
        SizedBox(width: 8),
        Text('Pas de connexion', style: TextStyle(color: Colors.white)),
      ],
    ),
  ),
  child: const MyApp(),
)

offlineBanner est ignoré quand un builder personnalisé est fourni.

Contrôle total via builder

Utiliser builder pour réagir à toutes les valeurs de NetworkStatus, y compris online et unknown :

lib/main.dart
NetworkStatusIndicator(
  builder: (context, status, child) {
    return Stack(
      children: [
        child!,
        if (status == NetworkStatus.offline)
          const Positioned(
            bottom: 0, left: 0, right: 0,
            child: MyOfflineBanner(),
          ),
        if (status == NetworkStatus.unknown)
          const Positioned(
            bottom: 0, left: 0, right: 0,
            child: MyCheckingBanner(),
          ),
      ],
    );
  },
  child: const MyApp(),
)

Props

PropTypeDéfautDescription
childWidgetrequisLe contenu principal de l'application.
builderWidget Function(BuildContext, NetworkStatus, Widget?)?nullBuilder à contrôle total. Quand défini, offlineBanner est ignoré.
offlineBannerWidget Function(BuildContext)?nullWidget personnalisé affiché en bas quand hors-ligne.

NetworkStatusBuilder

Le widget de bas niveau. S'abonne au stream du ConnectivityManager et appelle builder à chaque transition de NetworkStatus. À utiliser quand un contrôle fin sur le rendu de chaque statut est requis.

Utilisation de base

lib/ui/widgets/offline_banner.dart
NetworkStatusBuilder(
  builder: (context, status, child) {
    return status == NetworkStatus.offline
        ? const MyOfflineBanner()
        : const SizedBox.shrink();
  },
)

Avec optimisation via child

Passer un sous-arbre coûteux en child pour éviter sa reconstruction à chaque changement de statut :

lib/ui/screens/home_screen.dart
NetworkStatusBuilder(
  builder: (context, status, child) {
    return Column(
      children: [
        if (status == NetworkStatus.offline) const OfflineBanner(),
        Expanded(child: child!),
      ],
    );
  },
  child: const ExpensiveContentTree(),
)

Le framework réutilise child entre les appels à builder : seul le wrapper se reconstruit.

Lecture du statut courant de façon impérative

lib/ui/offline_badge.dart
final manager = QoraScope.connectivityManagerOf(context);
final status = manager?.currentStatus ?? NetworkStatus.unknown;

Props

PropTypeDéfautDescription
builderWidget Function(BuildContext, NetworkStatus, Widget?)requisConstruit l'arbre de widgets pour le NetworkStatus donné.
childWidget?nullChild optionnel transmis inchangé à builder.

Valeurs de NetworkStatus

ValeurSignification
NetworkStatus.onlineL'appareil a au moins une interface réseau active.
NetworkStatus.offlineToutes les interfaces réseau sont hors service.
NetworkStatus.unknownAucun ConnectivityManager n'est enregistré, ou le statut n'a pas encore été déterminé.
NetworkStatus reflète la disponibilité des interfaces, pas l'accessibilité internet réelle. Un appareil connecté à un routeur sans accès WAN rapportera online. Pour valider l'accessibilité, ajouter un health-check personnalisé dans l'implémentation de ConnectivityManager.

Placement recommandé

Placer NetworkStatusIndicator juste à l'intérieur de QoraScope, en encapsulant l'application entière. Cela garantit que la bannière est toujours visible quelle que soit la route active :

lib/main.dart
runApp(
  QoraScope(
    client: client,
    connectivityManager: FlutterConnectivityManager(),
    child: NetworkStatusIndicator(
      child: MaterialApp(
        home: const HomeScreen(),
      ),
    ),
  ),
);

Étapes suivantes

  • Guide réseau adaptatif : Guide complet de mise en place offline-first
  • QoraScope : Câblage de FlutterConnectivityManager dans l'arbre de widgets
  • QoraBuilder : Utilisation de FetchStatus.paused pour les indicateurs hors-ligne par widget

Hooks (flutter_hooks)

Utiliser useQuery, useMutation, useInfiniteQuery, useIsFetching et useIsMutating avec flutter_hooks pour une API concise et composable.

Bonnes pratiques

Patterns et conventions pour construire des applications Flutter fiables avec Qora : clés, placement des requêtes, câblage des mutations et performance.

Copyright © 2026