[摘录] 当页[ModalRoute.of(context)]路由属性详解

Posted 2020-11-24 wuxiaoyi

ModalRoute.of(context) API可以获取当前路由对象，通过它我们可以获取关于当前页面的所有属性：

属性:

• isActive
  当前路由是都位于navigator中；如果该路由active，还位于最顶层路由，则isCurrent为true；如果该路由active，并且是第一个路由（最底层路由），则isFirst为true。

• isCurrent
  判断当前路由是否为最顶层路由，如果胃true，则isActive也一定是true。

• isFirst
  判断当前路由是否为最底层路由。如果为最底层路由，那么Navigator.canPop必定返回false，willHandlePopInternally也会返回false。如果isFirst和isCurrent同时为true，则该路由是navigator中的唯一路由（isActive也一定是true）。

• navigator
  路由所属的navigator。

• overlayEntries
  当前路由的overlay中已经存在了的事务集合，是一个List。

• settings
  获取当前路由的基本配置信息，主要包括两个属性：isInitialRoute表示是否为初始路由（最早被push到navigator中的那个路由，初始路由默认跳过路由动画，来加速app启动）；name表示路由名。

• controller
  路由动画的animation controller，这个属性添加了@protected注解，不建议直接获取，而是通过animation属性来暴露路由动画。

• animation和secondaryAnimation
  路由动画，也就是创建路由时RoutePageBuilder中的动画。

• transitionDuration
  路由动画的持续时间。

• barrierColor
  屏障颜色，一个屏障（barrier）时渲染在每一个路由底部的，用来防止用户和下一层的路由交互。比如我们打开一个dialog路由，位于dialog底部的页面会因为barrier的原因而变暗。如果值为bull，则barrier为透明色。

• barrierLabel
  一个dismissible barrier的语义标签，是为了支持semantic功能的，一般app可以忽略。

• barrierDismissible
  是否可以通过点击屏障来关闭路由。

• semanticsDismissible
  当前barrier的semantics是否被放到了semantics tree里面，true为在树里面，false为不在树里面且点击barrier没有任何效果（不能关闭路由）。

• opaque
  当路由变换结束时，是否需要模糊前面的路由。如果是不透明的路由，那么前一个被遮挡了的路由就不会再被创建了（可以节省系统资源）。

• canPop
  当前路由是否可以被pop出去，如果这个值变化了，路由会重新创建，所有使用了ModalRoute.of的widgets都会收到通知。

• maintainState
  当路由为inactive状态时，是否需要保存路由状态。这个值在路由的生命周期中不应该被改变，因为在路由初期的时候（install方法执行的时候），这个值被用在了createOverlayEntries方法中。

• offstage
  判断当前路由是否可见。在路由进入transition当第一帧开始时，路由就会在当前页面创建一个Offstage控件，路由不可见并且不可交互，但是每一个widget都已经有了固定的大小和位置，因此HeroController可以定位到hero控件的位置。如果offstage为
  true，那么modal barrier是不会被渲染的（rendered）。

• subtreeContext
  包含了当前路由的主要内容的子树的context。

• currentResult
  如果路由pop的时候没有指定返回值，或者返回值为null，那么就会用这个值来代替（该值默认为null）。

• popped
  这是一个Future对象，当路由从navigator中pop时被调用，这个Future是和Navigator.pop的值一起完成的。

• completed
  也是一个Future对象，会在路由变换结束后调用，且只会被调用一次。注意是动画dismiss之后，所以会在popped之后执行，因为``popped```可能在animation还没开始的时候就执行完毕了。

• finishedWhenPopped
  官方没给注释，看代码是路由动画的status等于AnimationStatus.dismissed时为true。

• hasScopedWillPopCallback
  如果存在WillPopCallback回调（一个或多个都行），则为true。这个方法可以用来禁止在MaterialPageRoute中设置TargetPlatform.ios时的侧滑关闭。

• willHandlePopInternally
  判断路由内部是否有本地历史事务（LocalHistoryEntry）。举个例子，PageA——>PageB，其中PageB包含了一个本地历史事务Entry1，那么当Entry1执行的时候，点击返回键，回到PageB，再点击返回键，回到PageA，而不是直接从Entry1回到PageA（虽然
  Entry1和PageB都属于同一个路由）。建议看下LocalHistoryRoute的源码注释，有很清楚的demo例子。
  方法

• didPush()
  对应didPop()，任意一方请求push这个路由的时候被调用，在路由的install()方法之后执行，在push变换完成后返回返回值。didChangeNext和didChangePrevious一般会紧跟着这个方法被调用。

• didPop()
  任意一方请求pop掉这个路由的时候被调用。当路由内部处理的时候（比如有自己的stack栈或者内部state状态）返回false，否则返回true。如果返回true，navigator会把这个路由从历史里面remove掉，但是还没有调用dispose方法，而是通过路由自己调用
  NavigatorState.finalizeRoute，这个方法里面会最终执行dispose方法，这给予了路由执行退出动画的时间。

• didReplace(Route<dynamic> oldRoute)
  当一个路由替换了另一个路由当时候被调用，具体是在新路由的install()方法之后执行，didChangeNext和didChangePrevious一般会紧跟着这个方法被调用。

• didComplete()
  路由被pop掉或者被一些其他的方法优雅地remove掉的时候调用。

• dispose()
  这个时候路由会remove它的overlays，并释放其他所有资源，这个路由和navigator之间再也没有任何关联了。

• install(OverlayEntry insertionPoint)
  路由被插入到navigator的时候被调用。这个方法里面会填充overlayEntries并将事务列表添加到overlay中（可以通过Navigator.overlay来获取）。这个操作之所以由route来控制而不是由navigator来亲自控制是因为remove overlay事务的操作也是由route来控制的，这样就对称了。如果是第一个被插入的路由，insertionPoint属性会是null。

• willPop()
  返回的是一个Future类型，返回值为addScopedWillPopCallback中第一个返回false的callback的值，如果这些callback全都返回了true，则返回super.willPop()。一般不会复写这个方法，因为我们很少会直接去new一个modal routes，一般都是通过showDialog()这样的方法来创建modal routes

• addLocalHistoryEntry(LocalHistoryEntry entry)和removeLocalHistoryEntry(LocalHistoryEntry entry)
  添加/删除一个本地事务（remove操作是同步执行的）。

• addScopedWillPopCallback(WillPopCallback callback)
  拦截用户的关闭路由操作。一般配合WillPopScope控件使用，这个控件会找到最近的ModalRoute然后注册这个回调。注意这是一个异步方法，可能路由已经disposed掉了，这个回调才开始执行，所以最好是先判断一下State.mounted。

• removeScopedWillPopCallback(WillPopCallback callback)
  remove掉监听。。

• canTransitionFrom(TransitionRoute<dynamic> previousRoute)和 canTransitionTo(TransitionRoute<dynamic> nextRoute)
  表示是否可以从给定的route中进行transition，子类可以重写这个方法来限制两个route的变换交互。

• changedExternalState()
  当Navigator的NavigatorState或者widget变化时被调用，比如MaterialApp重建的时候。在ModalRoute中会强制重建当前页面。

• changedInternalState()
  当路由的内部状态改变时被调用，包括了willHandlePopInternally、didPop、offstage等等内部状态的值改变。

• didChangeNext(Route<dynamic> nextRoute)和didChangePrevious(Route<dynamic> previousRoute)
  给定的路由的next route / previous route发生改变时会被调用。

• didPopNext(Route<dynamic> nextRoute)
  nextRoute被pop的时候会被调用。

• createAnimationController()
  控制当前路由动画的controller（从前一个路由push到当前路由和从当前路由回去前路由的动画）。

• createAnimation()
  用于暴露当前路由变换的进度，这个animation受createAnimationController()方法中创建的controller控制。

• createOverlayEntries()
  创建overlay事务。

• buildTransitions( BuildContext context,Animation<double> animation,Animation<double> secondaryAnimation, Widget child, )
  可以重写这个方法，然后给child控件包裹一个或多个transition控件，来定义路由如何进入和离开屏幕。默认情况下，child（包含了buildPage返回的控件）不包裹任何transition控件。它和buildPage方法的区别就是，buildTransitions会在每次路由状
  态变化时都被调用（比如路由canPop的时候）。我们常见的创建PageRouteBuilder的时候，如果设置了transitionsBuilder属性，其实就是调用了该方法。

• buildPage(BuildContext context, Animation<double> animation, Animation<double> secondaryAnimation)
  定义路由的主页面内容。