A First Look at Flutter (3): Route Management

1. Basic concepts

The so-called Route Management is to manage how to jump between pages. It is usually also called navigation management. Route Management in Flutter is similar to native development. Whether it is Android or iOS, navigation management will maintain a route stack. The route push operation corresponds to opening a new page, and the route pop operation corresponds to the page closing operation. Route Management mainly refers to how to manage the route stack.

2. MaterialPageRoute

2.1 Basic definition

MaterialPageRoute is a component provided by the Material component library. It can implement routing switching animations consistent with the platform page switching animation style for different platforms:

For Android, when a new page is opened, the new page will slide from the bottom of the screen to the top of the screen; when the page is closed, the current page will slide from the top of the screen to the bottom of the screen and then disappear, while the previous page will be displayed on the screen.
For iOS, when a page is opened, the new page will slide from the right edge of the screen to the left side of the screen until the new page is fully displayed on the screen, while the previous page will slide from the current screen to the left side of the screen and disappear; when the page is closed, just the opposite, the current page will slide out from the right side of the screen, and the previous page will slide in from the left side of the screen.

MaterialPageRoute({
   WidgetBuilder builder,
   RouteSettings settings,
   bool maintainState = true,
   bool fullscreenDialog = false,
})

builder is a WidgetBuilder callback that constructs the route's content and returns a widget. Typically, this callback returns an instance of the new route.
settings Contains the configuration information of the route, such as the route name and whether it is the initial route (home page).
maintainState By default, when a new route is pushed into the stack, the original route will still be saved in memory. If you want to release all the resources occupied by the route when it is no longer used, you can set maintainState to false.
fullscreenDialog indicates whether the new route is presented as a full-screen modal. On iOS, when fullscreenDialog is true, the page slides in from the bottom of the screen rather than horizontally.

2.2 Usage example

class NewRoute extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("New route"),
      ),
      body: Center(
        child: Text("This is new route"),
      ),
    );
  }
}

//...

Column(
  mainAxisAlignment: MainAxisAlignment.center,
  children: <Widget>[
    ... //Omit irrelevant code
    TextButton(
      child: Text("open new route"),
      onPressed: () {
        // Navigate to new route
        Navigator.push( 
          context,
          MaterialPageRoute(builder: (context) {
            return NewRoute();
          }),
        );
      },
    ),
  ],
 )

3. Navigator

3.1 Definition

Navigator is Flutter's route-management component. It provides methods for opening and closing routes and manages the active routes as a stack. The route at the top of the stack is normally the page displayed on screen. Navigator exposes many methods for managing this stack; here are the two most commonly used ones:

Future push(BuildContext context, Route route)
Pushes the given route onto the stack, opening a new page. The returned Future completes with the value passed back when the route is popped (closed).
bool pop(BuildContext context, [ result ])
Pop the top route from the stack, and the result is the data returned to the previous page when the page is closed.

Navigator There are many other methods, such as Navigator.replace, Navigator.popUntil etc. For details, please refer to the API documentation or SDK source code comments, which will not be repeated here. Next we also need to introduce another concept related to routing, "named routing".
Instance Method
The first parameter in the Navigator class is context Static method corresponds to a Navigator Instance Method, for example Navigator.push(BuildContext context, Route route) is equivalent to Navigator.of(context).push(Route route), the following methods related to named routing are also the same.

4. Passing Data Between Routes

4.1 Passing Data with Anonymous Routes

class TipRoute extends StatelessWidget {
  TipRoute({
    Key key,
    required this.text,  // receives a text parameter
  }) : super(key: key);
  final String text;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Tip"),
      ),
      body: Padding(
        padding: EdgeInsets.all(18),
        child: Center(
          child: Column(
            children: <Widget>[
              Text(text),
              ElevatedButton(
                onPressed: () => Navigator.pop(context, "I am the return value"),
                child: Text("return"),
              )
            ],
          ),
        ),
      ),
    );
  }
}

class RouterTestRoute extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Center(
      child: ElevatedButton(
        onPressed: () async {
          // Open `TipRoute` and wait for the result to be returned
          var result = await Navigator.push(
            context,
            MaterialPageRoute(
              builder: (context) {
                return TipRoute(
                  // Routing parameters
                  text: "I am promptxxxx",
                );
              },
            ),
          );
          //Output `TipRoute` route return result
          print("Route return value:$result");
        },
        child: Text("Open prompt page"),
      ),
    );
  }
}

Requires explanation:

The prompt text “I am prompt xxxx” is passed to the new route through TipRoute's text parameter. Await the Future returned by Navigator.push(...) to receive the route's result.
There are two ways to return from TipRoute: click the back arrow in the navigation bar or click the “Return” button on the page. The first returns no data to the previous route, while the second does. The following shows what print in RouterTestRoute writes to the console for each action:

1 2	I/flutter (27896): Route return value: I am the return value I/flutter (27896): Route return value: null

4.2 Passing Data with Named Routes

The so-called "Named Route" is a route with a name. We can give the route a name first, and then directly open a new route through the route name. This brings an intuitive and simple way to Route Management.

4.2.1 Route table

To use named routing, we must first provide and register a route table (route table) so that the application knows which name corresponds to which route component. In fact, registering a route table means giving a name to the route. The route table is defined as follows:

1	Map<String, WidgetBuilder> routes;

The route table is a Map: each key is a route-name string, and each value is a builder callback that creates the corresponding route widget. When a route is opened by name, the app looks up its WidgetBuilder, invokes it, and returns the generated widget.

4.2.2 Register route table

Registering the route table is straightforward. Return to the earlier counter example, locate MaterialApp in MyApp.build, and add the routes property:

MaterialApp(
  title: 'Flutter Demo',
  theme: ThemeData(
    primarySwatch: Colors.blue,
  ),
  //Register routing table
  routes:{
   "new_page":(context) => NewRoute(),
    ... // Omit other routing registration information
  } ,
  home: MyHomePage(title: 'Flutter Demo Home Page'),
);

Now we have completed the registration of the route table. In the above code, the home route does not use a named route. What should we do if we also want to register home as a named route? It’s actually very simple, just look at the code:

MaterialApp(
  title: 'Flutter Demo',
  initialRoute:"/", //The route named "/" is applied as home(Homepage)
  theme: ThemeData(
    primarySwatch: Colors.blue,
  ),
  //Register routing table
  routes:{
   "new_page":(context) => NewRoute(),
   "/":(context) => MyHomePage(title: 'Flutter Demo Home Page'), //Register home page routing
  } 
);

Register MyHomePage in the route table, then use its name as the value of MaterialApp.initialRoute. This property determines the app's initial named route.

4.2.3 Open a new route by route name

To open a new route by route name, you can use the pushNamed method of Navigator:

1	Future pushNamed(BuildContext context, String routeName,{Object arguments})

In addition to pushNamed, Navigator provides methods such as pushReplacementNamed for managing named routes. See the API documentation for the full list. To open a new route by name, update the onPressed callback of TextButton as follows:

onPressed: () {
  Navigator.pushNamed(context, "new_page");
  //Navigator.push(context,
  //  MaterialPageRoute(builder: (context) {
  //  return NewRoute();
  //}));  
},

Hot reload application, click the "open new route" button again, you can still open a new route.

4.2.4 Named route parameter passing

In the initial version of Flutter, named routes could not pass parameters, and parameters were only supported later. The following shows how named routes pass and obtain route parameters:

We first register a route:

1
2
3

routes:{
   "new_page":(context) => EchoRoute(),
  } ,

Obtain routing parameters through the RouteSetting object on the route:

class EchoRoute extends StatelessWidget {

  @override
  Widget build(BuildContext context) {
    //Get routing parameters
    var args=ModalRoute.of(context).settings.arguments;
    //...Omit irrelevant code
  }
}

Pass parameters when opening route

1	Navigator.of(context).pushNamed("new_page", arguments: "hi");

4.2.5 Adaptation

Suppose we also want to register the TipRoute route in the route parameter passing example above into the route table, so that it can also be opened by the route name. However, since TipRoute accepts a text parameter, how can we adapt to this situation without changing the TipRoute source code? It's actually very simple:

MaterialApp(
  ... //Omit irrelevant code
  routes: {
   "tip2": (context){
     return TipRoute(text: ModalRoute.of(context)!.settings.arguments);
   },
 }, 
);

4.3 Route generation hook

4.3.1 onGenerateRoute

Suppose we want to develop an e-commerce App. When users are not logged in, they can view store, product and other information, but transaction records, shopping carts, user personal information and other pages need to be logged in before they can be viewed. In order to achieve the above functions, we need to determine the user login status before opening each route! If we need to make a judgment every time before opening the routing, it will be very troublesome. Is there any better way? The answer is yes!

MaterialApp has an onGenerateRoute property that may be called when opening a named route. If the requested name is registered in the route table, Flutter uses that route's builder. Otherwise, it calls onGenerateRoute to create the route. The callback signature is:

1	Route<dynamic> Function(RouteSettings settings)

With the onGenerateRoute callback, it is very easy to implement the above function of controlling page permissions: we abandon the use of routing tables and instead provide a onGenerateRoute callback, and then perform unified permission control in this callback, such as:

MaterialApp(
  ... //Omit irrelevant code
  onGenerateRoute:(RouteSettings settings){
	  return MaterialPageRoute(builder: (context){
		   String routeName = settings.name;
       // If the accessed routing page requires login, but you are not currently logged in, you will directly return to the login page routing.
       // Guide users to log in; in other cases, open routing normally.
     }
   );
  }
);

Note that onGenerateRoute will only take effect on named routes.

4.3.2 navigatorObservers (to be added)

Monitor all routing jump actions

4.3.3 onUnknownRoute (to be added)

Will be called when opening a named route that does not exist

4.4 How to choose Route Management method

It is best to use the unified management method of named routing, which will bring the following benefits:

The semantics are clearer.
The code is easier to maintain; if you use anonymous routing, you must create a new route where Navigator.push is called. This not only requires importing the dart file of the new route, but also such code will be very scattered.
Can use onGenerateRoute to do some global route jump pre-processing logic.

一、基本概念

所谓路由管理，就是管理页面之间如何跳转，通常也可被称为导航管理。Flutter 中的路由管理和原生开发类似，无论是 Android 还是 iOS，导航管理都会维护一个路由栈，路由入栈（push）操作对应打开一个新页面，路由出栈（pop）操作对应页面关闭操作，而路由管理主要是指如何来管理路由栈。

二、MaterialPageRoute

2.1 基本定义

MaterialPageRoute 是 Material组件库提供的组件，它可以针对不同平台，实现与平台页面切换动画风格一致的路由切换动画：

对于 Android，当打开新页面时，新的页面会从屏幕底部滑动到屏幕顶部；当关闭页面时，当前页面会从屏幕顶部滑动到屏幕底部后消失，同时上一个页面会显示到屏幕上。
对于 iOS，当打开页面时，新的页面会从屏幕右侧边缘一直滑动到屏幕左边，直到新页面全部显示到屏幕上，而上一个页面则会从当前屏幕滑动到屏幕左侧而消失；当关闭页面时，正好相反，当前页面会从屏幕右侧滑出，同时上一个页面会从屏幕左侧滑入。

MaterialPageRoute({
   WidgetBuilder builder,
   RouteSettings settings,
   bool maintainState = true,
   bool fullscreenDialog = false,
})

builder 是一个WidgetBuilder类型的回调函数，它的作用是构建路由页面的具体内容，返回值是一个widget。我们通常要实现此回调，返回新路由的实例。
settings 包含路由的配置信息，如路由名称、是否初始路由（首页）。
maintainState 默认情况下，当入栈一个新路由时，原来的路由仍然会被保存在内存中，如果想在路由没用的时候释放其所占用的所有资源，可以设置maintainState为 false。
fullscreenDialog 表示新的路由页面是否是一个全屏的模态对话框，在 iOS 中，如果fullscreenDialog为 true，新页面将会从屏幕底部滑入（而不是水平方向）。

2.2 使用例子

class NewRoute extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("New route"),
      ),
      body: Center(
        child: Text("This is new route"),
      ),
    );
  }
}

//...

Column(
  mainAxisAlignment: MainAxisAlignment.center,
  children: <Widget>[
    ... //省略无关代码
    TextButton(
      child: Text("open new route"),
      onPressed: () {
        //导航到新路由   
        Navigator.push( 
          context,
          MaterialPageRoute(builder: (context) {
            return NewRoute();
          }),
        );
      },
    ),
  ],
 )

三、Navigator

3.1 Definition

Navigator是一个路由管理的组件，它提供了打开和退出路由页方法。Navigator通过一个栈来管理活动路由集合。通常当前屏幕显示的页面就是栈顶的路由。Navigator提供了一系列方法来管理路由栈，在此我们只介绍其最常用的两个方法：

Future push(BuildContext context, Route route)
将给定的路由入栈（即打开新的页面），返回值是一个Future对象，用以接收新路由出栈（即关闭）时的返回数据。
bool pop(BuildContext context, [ result ])
将栈顶路由出栈，result 为页面关闭时返回给上一个页面的数据。

Navigator 还有很多其他方法，如Navigator.replace、Navigator.popUntil等，详情请参考API文档或SDK 源码注释，在此不再赘述。下面我们还需要介绍一下路由相关的另一个概念“命名路由”。
实例方法
Navigator类中第一个参数为context的静态方法都对应一个Navigator的实例方法，比如Navigator.push(BuildContext context, Route route)等价于Navigator.of(context).push(Route route) ，下面命名路由相关的方法也是一样的。

四、路由传值

4.1 非命名路由传值

class TipRoute extends StatelessWidget {
  TipRoute({
    Key key,
    required this.text,  // 接收一个text参数
  }) : super(key: key);
  final String text;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("提示"),
      ),
      body: Padding(
        padding: EdgeInsets.all(18),
        child: Center(
          child: Column(
            children: <Widget>[
              Text(text),
              ElevatedButton(
                onPressed: () => Navigator.pop(context, "我是返回值"),
                child: Text("返回"),
              )
            ],
          ),
        ),
      ),
    );
  }
}

class RouterTestRoute extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Center(
      child: ElevatedButton(
        onPressed: () async {
          // 打开`TipRoute`，并等待返回结果
          var result = await Navigator.push(
            context,
            MaterialPageRoute(
              builder: (context) {
                return TipRoute(
                  // 路由参数
                  text: "我是提示xxxx",
                );
              },
            ),
          );
          //输出`TipRoute`路由返回结果
          print("路由返回值: $result");
        },
        child: Text("打开提示页"),
      ),
    );
  }
}

需要说明：

提示文案“我是提示xxxx”是通过TipRoute的text参数传递给新路由页的。我们可以通过等待Navigator.push(…)返回的Future来获取新路由的返回数据。
在TipRoute页中有两种方式可以返回到上一页；第一种方式是直接点击导航栏返回箭头，第二种方式是点击页面中的“返回”按钮。这两种返回方式的区别是前者不会返回数据给上一个路由，而后者会。下面是分别点击页面中的返回按钮和导航栏返回箭头后，RouterTestRoute页中print方法在控制台输出的内容：

1 2	I/flutter (27896): 路由返回值: 我是返回值 I/flutter (27896): 路由返回值: null

4.2 命名路由传值

所谓“命名路由”（Named Route）即有名字的路由，我们可以先给路由起一个名字，然后就可以通过路由名字直接打开新的路由了，这为路由管理带来了一种直观、简单的方式。

4.2.1 路由表

要想使用命名路由，我们必须先提供并注册一个路由表（routing table），这样应用程序才知道哪个名字与哪个路由组件相对应。其实注册路由表就是给路由起名字，路由表的定义如下：

1	Map<String, WidgetBuilder> routes;

它是一个Map，key为路由的名字，是个字符串；value是个builder回调函数，用于生成相应的路由widget。我们在通过路由名字打开新路由时，应用会根据路由名字在路由表中查找到对应的WidgetBuilder回调函数，然后调用该回调函数生成路由widget并返回。

4.2.2 注册路由表

路由表的注册方式很简单，我们回到之前“计数器”的示例，然后在MyApp类的build方法中找到MaterialApp，添加routes属性，代码如下：

MaterialApp(
  title: 'Flutter Demo',
  theme: ThemeData(
    primarySwatch: Colors.blue,
  ),
  //注册路由表
  routes:{
   "new_page":(context) => NewRoute(),
    ... // 省略其他路由注册信息
  } ,
  home: MyHomePage(title: 'Flutter Demo Home Page'),
);

现在我们就完成了路由表的注册。上面的代码中home路由并没有使用命名路由，如果我们也想将home注册为命名路由应该怎么做呢？其实很简单，直接看代码：

MaterialApp(
  title: 'Flutter Demo',
  initialRoute:"/", //名为"/"的路由作为应用的home(首页)
  theme: ThemeData(
    primarySwatch: Colors.blue,
  ),
  //注册路由表
  routes:{
   "new_page":(context) => NewRoute(),
   "/":(context) => MyHomePage(title: 'Flutter Demo Home Page'), //注册首页路由
  } 
);

可以看到，我们只需在路由表中注册一下MyHomePage路由，然后将其名字作为MaterialApp的initialRoute属性值即可，该属性决定应用的初始路由页是哪一个命名路由。

4.2.3 通过路由名打开新路由页

要通过路由名称来打开新路由，可以使用Navigator 的pushNamed方法：

1	Future pushNamed(BuildContext context, String routeName,{Object arguments})

Navigator 除了pushNamed方法，还有pushReplacementNamed等其他管理命名路由的方法，读者可以自行查看API文档。接下来我们通过路由名来打开新的路由页，修改TextButton的onPressed回调代码，改为：

onPressed: () {
  Navigator.pushNamed(context, "new_page");
  //Navigator.push(context,
  //  MaterialPageRoute(builder: (context) {
  //  return NewRoute();
  //}));  
},

热重载应用，再次点击“open new route”按钮，依然可以打开新的路由页。

4.2.4 命名路由参数传递

在Flutter最初的版本中，命名路由是不能传递参数的，后来才支持了参数；下面展示命名路由如何传递并获取路由参数：

我们先注册一个路由：

1
2
3

routes:{
   "new_page":(context) => EchoRoute(),
  } ,

在路由页通过RouteSetting对象获取路由参数：

class EchoRoute extends StatelessWidget {

  @override
  Widget build(BuildContext context) {
    //获取路由参数  
    var args=ModalRoute.of(context).settings.arguments;
    //...省略无关代码
  }
}

在打开路由时传递参数

1	Navigator.of(context).pushNamed("new_page", arguments: "hi");

4.2.5 适配

假设我们也想将上面路由传参示例中的TipRoute路由页注册到路由表中，以便也可以通过路由名来打开它。但是，由于TipRoute接受一个text 参数，我们如何在不改变TipRoute源码的前提下适配这种情况？其实很简单：

MaterialApp(
  ... //省略无关代码
  routes: {
   "tip2": (context){
     return TipRoute(text: ModalRoute.of(context)!.settings.arguments);
   },
 }, 
);

4.3 路由生成钩子

4.3.1 onGenerateRoute

假设我们要开发一个电商App，当用户没有登录时可以看店铺、商品等信息，但交易记录、购物车、用户个人信息等页面需要登录后才能看。为了实现上述功能，我们需要在打开每一个路由页前判断用户登录状态！如果每次打开路由前我们都需要去判断一下将会非常麻烦，那有什么更好的办法吗？答案是有！

MaterialApp有一个onGenerateRoute属性，它在打开命名路由时可能会被调用，之所以说可能，是因为当调用Navigator.pushNamed(...)打开命名路由时，如果指定的路由名在路由表中已注册，则会调用路由表中的builder函数来生成路由组件；如果路由表中没有注册，才会调用onGenerateRoute来生成路由。onGenerateRoute回调签名如下：

1	Route<dynamic> Function(RouteSettings settings)

有了onGenerateRoute回调，要实现上面控制页面权限的功能就非常容易：我们放弃使用路由表，取而代之的是提供一个onGenerateRoute回调，然后在该回调中进行统一的权限控制，如：

MaterialApp(
  ... //省略无关代码
  onGenerateRoute:(RouteSettings settings){
	  return MaterialPageRoute(builder: (context){
		   String routeName = settings.name;
       // 如果访问的路由页需要登录，但当前未登录，则直接返回登录页路由，
       // 引导用户登录；其他情况则正常打开路由。
     }
   );
  }
);

注意，onGenerateRoute 只会对命名路由生效。

4.3.2 navigatorObservers（待补充）

监听所有路由跳转动作

4.3.3 onUnknownRoute（待补充）

打开一个不存在的命名路由时会被调用

4.4 如何选择路由管理方式

最好统一使用命名路由的管理方式，这将会带来如下好处：

语义化更明确。
代码更好维护；如果使用匿名路由，则必须在调用Navigator.push的地方创建新路由页，这样不仅需要import新路由页的dart文件，而且这样的代码将会非常分散。
可以通过onGenerateRoute做一些全局的路由跳转前置处理逻辑。