pure_route_aware #

中文文档

A pure alternative to Flutter's RouteAware for route visibility callbacks without triggering widget rebuilds.

The Problem #

When using Flutter's built-in RouteAware with RouteObserver, you typically need to call ModalRoute.of(context) to get the current route. However, ModalRoute.of(context) creates a dependency on InheritedWidget, which causes your widget to rebuild whenever the route's state changes.

The Solution #

pure_route_aware uses ModalRoute.settingsOf(context) instead, which only reads the route's settings without creating a rebuild dependency. This gives you the same callbacks as RouteAware without the performance overhead.

Features #

• ✅ No rebuild side-effects - Uses ModalRoute.settingsOf() instead of ModalRoute.of()
• ✅ Simple API - Only 2 callbacks: didPushNext, didPopNext
• ✅ Popup filtering - Dialogs and bottom sheets don't trigger visibility callbacks
• ✅ Multiple listeners - Multiple widgets on the same route can listen independently
• ✅ Easy to use - Just a mixin and an observer, no manual subscribe/unsubscribe

Installation #

Add to your pubspec.yaml:

dependencies:
  pure_route_aware: ^1.0.0

Usage #

1. Register the Observer #

Add PureRouteObserver to your MaterialApp:

import 'package:pure_route_aware/pure_route_aware.dart';

MaterialApp(
  navigatorObservers: [PureRouteObserver()],
  // ...
)

2. Use the Mixin in Your Pages #

Simple way (recommended):

import 'package:pure_route_aware/pure_route_aware.dart';

class _MyPageState extends State<MyPage> with PureRouteAwareMixin<MyPage> {
  @override
  void onRouteVisibilityChanged(bool visible) {
    if (visible) {
      // Page is now visible - resume video, refresh data, etc.
      videoController.play();
    } else {
      // Page is now hidden - pause video, stop animations, etc.
      videoController.pause();
    }
  }

  @override
  Widget build(BuildContext context) => ...;
}

Or use separate callbacks:

class _MyPageState extends State<MyPage> with PureRouteAwareMixin<MyPage> {
  @override
  void didPushNext() {
    super.didPushNext();
    videoController.pause();  // Page hidden
  }

  @override
  void didPopNext() {
    super.didPopNext();
    videoController.play();  // Page visible
  }

  @override
  Widget build(BuildContext context) => ...;
}

3. Check Visibility Status #

You can also check if the current route is visible:

class _MyPageState extends State<MyPage> with PureRouteAwareMixin<MyPage> {
  void someMethod() {
    if (isRouteVisible) {
      // Do something only when visible
    }
  }
}

API Reference #

PureRouteObserver #

A NavigatorObserver that tracks route changes and notifies registered pages.

PureRouteAwareMixin #

A mixin for State classes that provides route visibility callbacks:

PureRouteRegistry #

Internal registry for managing route-to-widget mappings. Typically not used directly.

Comparison with RouteAware #

License #

MIT License - see LICENSE for details.