Overlay intégré

L'overlay est un panneau rendu à l'intérieur de l'app en cours d'exécution. Il offre une visibilité en temps réel sur les requêtes, mutations et mises à jour optimistes.

Vue mobileVue tablette/desktop

Installation

flutter pub add qora_devtools_overlay

Ajoutez-le dans dependencies, pas dans dev_dependencies : votre main.dart l'importe, et importer une dépendance de dev depuis lib/ est signalé par le lint depend_on_referenced_packages. Il ne coûte rien en release, comme expliqué dans Sécurité en production.

Configuration

Créer un OverlayTracker et le passer à la fois à QoraClient et à QoraInspector. Passer la référence du client à QoraInspector pour activer les boutons d'action de l'inspecteur.

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:qora_devtools_overlay/qora_devtools_overlay.dart';
import 'package:qora_flutter/qora_flutter.dart';

void main() {
  final tracker = OverlayTracker();

  final client = QoraClient(
    // null en mode release : QoraClient utilise NoOpTracker, aucun événement émis.
    tracker: kDebugMode ? tracker : null,
  );

  runApp(
    QoraInspector(
      tracker: tracker,
      // Requis pour que les boutons d'action (Refetch, Invalidate, Remove, etc.)
      // opèrent sur le cache en direct. Omettre cela désactive la section ACTIONS.
      client: kDebugMode ? client : null,
      child: QoraScope.auto(client: client, child: const MyApp()),
    ),
  );
}

En mode debug, un bouton Q est rendu dans le coin inférieur droit de l'écran. Appuyer dessus ouvre le panneau.

Comportement responsive

La disposition de l'overlay s'adapte à la largeur d'écran disponible.

• 600 px et plus (tablette, desktop) : disposition trois colonnes avec tous les panneaux visibles simultanément.
• Moins de 600 px (téléphone) : navigation mono-colonne avec navigation vers les vues inspecteur et timeline.

Sécurité en production

Deux mécanismes indépendants tiennent l'overlay à l'écart de la production :

1. Garde à la compilation

@override
Widget build(BuildContext context) {
  if (!kDebugMode) return child; // rien n'est construit en release
  return _buildOverlay();
}

kDebugMode est une constante de compilation. En build release, la branche de l'overlay est inatteignable, et le tree shaking retire le code du panneau.

2. NoOpTracker en release

QoraClient est construit avec tracker: kDebugMode ? tracker : null. En mode release, null active NoOpTracker. Ses méthodes sont des no-ops et aucun événement de suivi n'est émis.

Résultat : aucun impact d'exécution depuis le chemin du tracker overlay en production.