跳到主内容

概述

#

为了支持 Android 14 的预测返回功能，一系列“提前”API 已取代了“即时”导航 API，例如 WillPopScope 和 Navigator.willPop。

背景

#

Android 14 引入了预测返回功能，它允许用户在有效的返回手势期间，在当前路由的后面进行预览，并决定是继续返回还是取消手势。这与 Flutter 的导航 API 不兼容，因为后者允许开发者在收到返回手势后取消它。

通过预测返回，当用户发起手势时，返回动画会立即开始，而且是在手势被提交之前。Flutter 应用没有机会在那时决定是否允许发生。它必须提前知道。

因此，所有允许 Flutter 应用开发者在收到返回手势时取消返回导航的 API 现已弃用。它们已被等效的 API 取代，这些 API 始终维护一个布尔状态，指示是否可能进行返回导航。如果可能，预测返回动画照常发生。否则，导航停止。在这两种情况下，都会通知应用开发者已尝试返回以及是否成功。

PopScope

#

PopScope 类直接取代 WillPopScope，以启用预测返回。它不再在弹窗发生时决定是否可能弹窗，而是通过 canPop 布尔值提前设置。您仍然可以使用 onPopInvoked 监听弹窗事件。

dart
PopScope(
  canPop: _myPopDisableEnableLogic(),
  onPopInvoked: (bool didPop) {
    // Handle the pop. If `didPop` is false, it was blocked.
  },
)

Form.canPop 和 Form.onPopInvoked

#

这两个新参数基于 PopScope，取代了已弃用的 Form.onWillPop 参数。它们与 PopScope 的用法与上述相同。

dart
Form(
  canPop: _myPopDisableEnableLogic(),
  onPopInvoked: (bool didPop) {
    // Handle the pop. If `didPop` is false, it was blocked.
  },
)

Route.popDisposition

#

此 getter 同步返回路由的 RoutePopDisposition，它描述了弹窗的行为方式。

dart
if (myRoute.popDisposition == RoutePopDisposition.doNotPop) {
  // Back gestures are disabled.
}

ModalRoute.registerPopEntry 和 ModalRoute.unregisterPopEntry

#

使用这些方法注册 PopScope 小部件，以便在路由决定是否可以弹窗时进行评估。此功能可能在实现自定义 PopScope 小部件时使用。

dart
@override
void didChangeDependencies() {
  super.didChangeDependencies();
  final ModalRoute<dynamic>? nextRoute = ModalRoute.of(context);
  if (nextRoute != _route) {
    _route?.unregisterPopEntry(this);
    _route = nextRoute;
    _route?.registerPopEntry(this);
  }
}

迁移指南

#

从 WillPopScope 迁移到 PopScope

#

WillPopScope 小部件的直接替代是 PopScope 小部件。在许多情况下，在 onWillPop 中返回手势发生时运行的逻辑可以在构建时完成并设置为 canPop。

迁移前的代码

dart
WillPopScope(
  onWillPop: () async {
    return _myCondition;
  },
  child: ...
),

迁移后的代码

dart
PopScope(
  canPop: _myCondition,
  child: ...
),

对于需要通知已尝试弹窗的情况，onPopInvoked 方法可以像 onWillPop 一样使用。请记住，onWillPop 在弹窗处理之前被调用并具有取消它的能力，而 onPopInvoked 在弹窗处理完成后被调用。

迁移前的代码

dart
WillPopScope(
  onWillPop: () async {
    _myHandleOnPopMethod();
    return true;
  },
  child: ...
),

迁移后的代码

dart
PopScope(
  canPop: true,
  onPopInvoked: (bool didPop) {
    _myHandleOnPopMethod();
  },
  child: ...
),

针对嵌套 Navigator，从 WillPopScope 迁移到 NavigatorPopHandler

#

WillPopScope 的一个非常常见的用例是在使用嵌套 Navigator 小部件时正确处理返回手势。使用 PopScope 也可以实现这一点，但现在有一个包装小部件使其变得更容易：NavigatorPopHandler。

迁移前的代码

dart
WillPopScope(
  onWillPop: () async => !(await _nestedNavigatorKey.currentState!.maybePop()),
  child: Navigator(
    key: _nestedNavigatorKey,
    …
  ),
)

迁移后的代码

dart
NavigatorPopHandler(
  onPop: () => _nestedNavigatorKey.currentState!.pop(),
  child: Navigator(
    key: _nestedNavigatorKey,
    …
  ),
)

从 Form.onWillPop 迁移到 Form.canPop 和 Form.onPopInvoked

#

以前，Form 在底层使用了 WillPopScope 实例并暴露了其 onWillPop 方法。现在，这已被一个 PopScope 取代，它暴露了 canPop 和 onPopInvoked 方法。迁移过程与上述从 WillPopScope 迁移到 PopScope 的过程相同。

从 Route.willPop 迁移到 Route.popDisposition

#

Route 的 willPop 方法返回一个 Future<RoutePopDisposition>，以适应弹窗可能被取消的事实。现在这不再是真的了，此逻辑已简化为同步 getter。

迁移前的代码

dart
if (await myRoute.willPop() == RoutePopDisposition.doNotPop) {
  ...
}

迁移后的代码

dart
if (myRoute.popDisposition == RoutePopDisposition.doNotPop) {
  ...
}

从 ModalRoute.add/removeScopedWillPopCallback 迁移到 ModalRoute.(un)registerPopEntry

#

在内部，ModalRoute 通过使用 addScopedWillPopCallback 和 removeScopedWillPopCallback 注册 WillPopScope 来跟踪其小部件子树中 WillPopScope 的存在。由于 PopScope 取代了 WillPopScope，这些方法已被 registerPopEntry 和 unregisterPopEntry 分别取代。

PopEntry 由 PopScope 实现，以便仅向 ModalRoute 暴露必要的最少信息。任何编写自己的 PopScope 的人都应该实现 PopEntry 并向其包含的 ModalRoute 注册和注销他们的小部件。

迁移前的代码

dart
@override
void didChangeDependencies() {
  super.didChangeDependencies();
  if (widget.onWillPop != null) {
    _route?.removeScopedWillPopCallback(widget.onWillPop!);
  }
  _route = ModalRoute.of(context);
  if (widget.onWillPop != null) {
    _route?.addScopedWillPopCallback(widget.onWillPop!);
  }
}

迁移后的代码

dart
@override
void didChangeDependencies() {
  super.didChangeDependencies();
  _route?.unregisterPopEntry(this);
  _route = ModalRoute.of(context);
  _route?.registerPopEntry(this);
}

从 ModalRoute.hasScopedWillPopCallback 迁移到 ModalRoute.popDisposition

#

此方法以前用于一个与预测返回非常相似的用例，但在 Cupertino 库中，某些返回过渡允许取消导航。当甚至存在 WillPopScope 小部件取消弹窗的可能性时，路由过渡就会被禁用。

现在 API 要求提前决定这一点，因此不再需要推测性地基于 PopScope 小部件的存在。ModalRoute 是否被 PopScope 小部件阻止弹窗的确定性逻辑已内置到 ModalRoute.popDisposition 中。

迁移前的代码

dart
if (_route.hasScopedWillPopCallback) {
  // Disable predictive route transitions.
}

迁移后的代码

dart
if (_route.popDisposition == RoutePopDisposition.doNotPop) {
  // Disable predictive route transitions.
}

迁移返回确认对话框

#

WillPopScope 有时用于在收到返回手势时显示确认对话框。使用 PopScope 仍然可以采用类似的方式完成此操作。

迁移前的代码

dart
WillPopScope(
  onWillPop: () async {
    final bool? shouldPop = await _showBackDialog();
    return shouldPop ?? false;
  },
  child: child,
)

迁移后的代码

dart
return PopScope(
  canPop: false,
  onPopInvoked: (bool didPop) async {
    if (didPop) {
      return;
    }
    final NavigatorState navigator = Navigator.of(context);
    final bool? shouldPop = await _showBackDialog();
    if (shouldPop ?? false) {
      navigator.pop();
    }
  },
  child: child,
)

支持预测返回

#
  1. 运行 Android 14（API 级别 34）或更高版本。
  2. 在设备的“开发者选项”下启用预测返回功能标志。在未来的 Android 版本中，这将是不必要的。
  3. 在 android/app/src/main/AndroidManifest.xml 中设置 android:enableOnBackInvokedCallback="true"。如果需要，请参阅 Android 的完整指南，了解如何迁移 Android 应用以支持预测返回。
  4. 确保您使用的 Flutter 版本为 3.14.0-7.0.pre 或更高。
  5. 确保您的 Flutter 应用不使用 WillPopScope 小部件。使用它会禁用预测返回。如果需要，请改用 PopScope。
  6. 运行应用并执行返回手势（从屏幕左侧滑动）。

时间线

#

已在版本中推出：3.14.0-7.0.pre
稳定版本：3.16

参考资料

#

API 文档

相关问题

相关 PR

除非另有说明，本网站上的文档反映的是 Flutter 的最新稳定版本。页面最后更新于 2025-06-26。 查看源文件 或 报告问题。