♻️ Expose more route settings (#693)

AlexV525 · web-flow · commit e1a966b8b6ed · 2025-07-24T17:44:13.000+08:00
diff --git a/.github/workflows/runnable.yml b/.github/workflows/runnable.yml
@@ -1,5 +1,9 @@
 name: Runnable (stable)
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
   push:
     branches:
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,10 @@ that can be found in the LICENSE file. -->
 
 ## Unreleased
 
+**New features**
+
+- Expose more route settings. Users are now be able to control the route settings for the picker and viewer.
+
 **Improvements**
 
 - Improve how `MediaQuery` is being listened.
diff --git a/example/lib/customs/pickers/directory_file_asset_picker.dart b/example/lib/customs/pickers/directory_file_asset_picker.dart
@@ -171,26 +171,10 @@ class _DirectoryFileAssetPickerState extends State<DirectoryFileAssetPicker> {
                   themeData: AssetPicker.themeData(themeColor),
                 ),
               );
-              final PageRouteBuilder<List<File>> pageRoute =
-                  PageRouteBuilder<List<File>>(
-                pageBuilder: (
-                  BuildContext context,
-                  Animation<double> animation,
-                  Animation<double> secondaryAnimation,
-                ) {
-                  return viewer;
-                },
-                transitionsBuilder: (
-                  BuildContext context,
-                  Animation<double> animation,
-                  Animation<double> secondaryAnimation,
-                  Widget child,
-                ) {
-                  return FadeTransition(opacity: animation, child: child);
-                },
-              );
               final List<File>? result =
-                  await Navigator.maybeOf(context)?.push<List<File>>(pageRoute);
+                  await Navigator.maybeOf(context)?.push<List<File>>(
+                AssetPickerViewerPageRoute(builder: (context) => viewer),
+              );
               if (result != null && result != fileList) {
                 fileList
                   ..clear()
@@ -384,27 +368,19 @@ class FileAssetPickerBuilder
     int? index,
     File currentAsset,
   ) async {
+    final Widget viewer = AssetPickerViewer<File, Directory>(
+      builder: FileAssetPickerViewerBuilderDelegate(
+        currentIndex: index ?? provider.selectedAssets.indexOf(currentAsset),
+        previewAssets: provider.selectedAssets,
+        provider: FileAssetPickerViewerProvider(provider.selectedAssets),
+        themeData: AssetPicker.themeData(themeColor),
+        selectedAssets: provider.selectedAssets,
+        selectorProvider: provider,
+      ),
+    );
     final List<File>? result =
         await Navigator.maybeOf(context)?.push<List<File>?>(
-      PageRouteBuilder<List<File>>(
-        pageBuilder: (
-          BuildContext context,
-          Animation<double> animation,
-          Animation<double> secondaryAnimation,
-        ) {
-          return AssetPickerViewer<File, Directory>(
-            builder: FileAssetPickerViewerBuilderDelegate(
-              currentIndex:
-                  index ?? provider.selectedAssets.indexOf(currentAsset),
-              previewAssets: provider.selectedAssets,
-              provider: FileAssetPickerViewerProvider(provider.selectedAssets),
-              themeData: AssetPicker.themeData(themeColor),
-              selectedAssets: provider.selectedAssets,
-              selectorProvider: provider,
-            ),
-          );
-        },
-      ),
+      AssetPickerViewerPageRoute(builder: (context) => viewer),
     );
     if (result != null) {
       Navigator.maybeOf(context)?.maybePop(result);
@@ -430,24 +406,9 @@ class FileAssetPickerBuilder
         selectorProvider: selectorProvider,
       ),
     );
-    final PageRouteBuilder<List<File>> pageRoute = PageRouteBuilder<List<File>>(
-      pageBuilder: (
-        BuildContext context,
-        Animation<double> animation,
-        Animation<double> secondaryAnimation,
-      ) {
-        return viewer;
-      },
-      transitionsBuilder: (
-        BuildContext context,
-        Animation<double> animation,
-        Animation<double> secondaryAnimation,
-        Widget child,
-      ) {
-        return FadeTransition(opacity: animation, child: child);
-      },
+    return await Navigator.maybeOf(context)?.push<List<File>?>(
+      AssetPickerViewerPageRoute(builder: (context) => viewer),
     );
-    return await Navigator.maybeOf(context)?.push<List<File>?>(pageRoute);
   }
 
   @override
diff --git a/lib/src/delegates/asset_picker_builder_delegate.dart b/lib/src/delegates/asset_picker_builder_delegate.dart
@@ -25,6 +25,7 @@ import '../models/path_wrapper.dart';
 import '../provider/asset_picker_provider.dart';
 import '../widget/asset_picker.dart';
 import '../widget/asset_picker_app_bar.dart';
+import '../widget/asset_picker_page_route.dart';
 import '../widget/asset_picker_viewer.dart';
 import '../widget/builder/asset_entity_grid_item_builder.dart';
 
@@ -48,6 +49,9 @@ abstract class AssetPickerBuilderDelegate<Asset, Path> {
     this.pathNameBuilder,
     this.assetsChangeCallback,
     this.assetsChangeRefreshPredicate,
+    this.viewerUseRootNavigator = false,
+    this.viewerPageRouteSettings,
+    this.viewerPageRouteBuilder,
     Color? themeColor,
     AssetPickerTextDelegate? textDelegate,
     Locale? locale,
@@ -131,6 +135,10 @@ abstract class AssetPickerBuilderDelegate<Asset, Path> {
   final AssetsChangeRefreshPredicate<AssetPathEntity>?
       assetsChangeRefreshPredicate;
 
+  final bool viewerUseRootNavigator;
+  final RouteSettings? viewerPageRouteSettings;
+  final AssetPickerViewerPageRouteBuilder<List<Asset>>? viewerPageRouteBuilder;
+
   /// [ThemeData] for the picker.
   /// 选择器使用的主题
   ThemeData get theme => pickerTheme ?? AssetPicker.themeData(themeColor);
@@ -828,6 +836,9 @@ class DefaultAssetPickerBuilderDelegate
     super.pathNameBuilder,
     super.assetsChangeCallback,
     super.assetsChangeRefreshPredicate,
+    super.viewerUseRootNavigator,
+    super.viewerPageRouteSettings,
+    super.viewerPageRouteBuilder,
     super.themeColor,
     super.textDelegate,
     super.locale,
@@ -1175,6 +1186,9 @@ class DefaultAssetPickerBuilderDelegate
       maxAssets: p.maxAssets,
       shouldReversePreview: revert,
       shouldAutoplayPreview: shouldAutoplayPreview,
+      useRootNavigator: viewerUseRootNavigator,
+      pageRouteSettings: viewerPageRouteSettings,
+      pageRouteBuilder: viewerPageRouteBuilder,
     );
     if (result != null) {
       Navigator.maybeOf(context)?.maybePop(result);
diff --git a/lib/src/delegates/asset_picker_delegate.dart b/lib/src/delegates/asset_picker_delegate.dart
@@ -68,6 +68,7 @@ class AssetPickerDelegate {
     AssetPickerConfig pickerConfig = const AssetPickerConfig(),
     PermissionRequestOption? permissionRequestOption,
     bool useRootNavigator = true,
+    RouteSettings? pageRouteSettings,
     AssetPickerPageRouteBuilder<List<AssetEntity>>? pageRouteBuilder,
   }) async {
     permissionRequestOption ??= PermissionRequestOption(
@@ -83,6 +84,7 @@ class AssetPickerDelegate {
         pageRouteBuilder?.call(const SizedBox.shrink()) ??
             AssetPickerPageRoute<List<AssetEntity>>(
               builder: (_) => const SizedBox.shrink(),
+              settings: pageRouteSettings,
             );
     final DefaultAssetPickerProvider provider = DefaultAssetPickerProvider(
       maxAssets: pickerConfig.maxAssets,
@@ -127,7 +129,10 @@ class AssetPickerDelegate {
       rootNavigator: useRootNavigator,
     )?.push<List<AssetEntity>>(
       pageRouteBuilder?.call(picker) ??
-          AssetPickerPageRoute<List<AssetEntity>>(builder: (_) => picker),
+          AssetPickerPageRoute<List<AssetEntity>>(
+            builder: (_) => picker,
+            settings: pageRouteSettings,
+          ),
     );
     return result;
   }
@@ -157,6 +162,7 @@ class AssetPickerDelegate {
         const PermissionRequestOption(),
     Key? key,
     bool useRootNavigator = true,
+    RouteSettings? pageRouteSettings,
     AssetPickerPageRouteBuilder<List<Asset>>? pageRouteBuilder,
   }) async {
     await permissionCheck(requestOption: permissionRequestOption);
@@ -170,7 +176,10 @@ class AssetPickerDelegate {
       rootNavigator: useRootNavigator,
     )?.push<List<Asset>>(
       pageRouteBuilder?.call(picker) ??
-          AssetPickerPageRoute<List<Asset>>(builder: (_) => picker),
+          AssetPickerPageRoute<List<Asset>>(
+            builder: (_) => picker,
+            settings: pageRouteSettings,
+          ),
     );
     return result;
   }
diff --git a/lib/src/widget/asset_picker.dart b/lib/src/widget/asset_picker.dart
@@ -53,6 +53,7 @@ class AssetPicker<Asset, Path> extends StatefulWidget {
     PermissionRequestOption? permissionRequestOption,
     AssetPickerConfig pickerConfig = const AssetPickerConfig(),
     bool useRootNavigator = true,
+    RouteSettings? pageRouteSettings,
     AssetPickerPageRouteBuilder<List<AssetEntity>>? pageRouteBuilder,
   }) {
     return _pickerDelegate.pickAssets(
@@ -61,6 +62,7 @@ class AssetPicker<Asset, Path> extends StatefulWidget {
       pickerConfig: pickerConfig,
       permissionRequestOption: permissionRequestOption,
       useRootNavigator: useRootNavigator,
+      pageRouteSettings: pageRouteSettings,
       pageRouteBuilder: pageRouteBuilder,
     );
   }
@@ -73,6 +75,7 @@ class AssetPicker<Asset, Path> extends StatefulWidget {
     PermissionRequestOption permissionRequestOption =
         const PermissionRequestOption(),
     Key? key,
+    RouteSettings? pageRouteSettings,
     AssetPickerPageRouteBuilder<List<Asset>>? pageRouteBuilder,
     bool useRootNavigator = true,
   }) {
@@ -82,6 +85,7 @@ class AssetPicker<Asset, Path> extends StatefulWidget {
       delegate: delegate,
       permissionRequestOption: permissionRequestOption,
       useRootNavigator: useRootNavigator,
+      pageRouteSettings: pageRouteSettings,
       pageRouteBuilder: pageRouteBuilder,
     );
   }
diff --git a/lib/src/widget/asset_picker_page_route.dart b/lib/src/widget/asset_picker_page_route.dart
@@ -76,3 +76,67 @@ class AssetPickerPageRoute<T> extends PageRoute<T> {
     );
   }
 }
+
+/// Build [AssetPickerViewerPageRoute] with the given generic type.
+/// 构建匹配泛型的 [AssetPickerViewerPageRoute]
+typedef AssetPickerViewerPageRouteBuilder<T> = AssetPickerViewerPageRoute<T>
+    Function(Widget viewer);
+
+/// Built a fade transition for the viewer.
+/// 为预览器构造一个渐变的页面过渡动画
+class AssetPickerViewerPageRoute<T> extends PageRoute<T> {
+  AssetPickerViewerPageRoute({
+    required this.builder,
+    this.transitionCurve = Curves.easeIn,
+    this.transitionDuration = const Duration(milliseconds: 250),
+    this.barrierColor,
+    this.barrierDismissible = false,
+    this.barrierLabel,
+    this.maintainState = true,
+    this.opaque = true,
+    this.canTransitionFromPredicate,
+    super.settings,
+  });
+
+  final WidgetBuilder builder;
+
+  final Curve transitionCurve;
+  @override
+  final Duration transitionDuration;
+
+  @override
+  final Color? barrierColor;
+  @override
+  final bool barrierDismissible;
+  @override
+  final String? barrierLabel;
+  @override
+  final bool opaque;
+  @override
+  final bool maintainState;
+
+  final bool Function(TransitionRoute<dynamic>)? canTransitionFromPredicate;
+
+  @override
+  bool canTransitionFrom(TransitionRoute<dynamic> previousRoute) =>
+      canTransitionFromPredicate?.call(previousRoute) ?? false;
+
+  @override
+  Widget buildPage(
+    BuildContext context,
+    Animation<double> animation,
+    Animation<double> secondaryAnimation,
+  ) {
+    return builder(context);
+  }
+
+  @override
+  Widget buildTransitions(
+    BuildContext context,
+    Animation<double> animation,
+    Animation<double> secondaryAnimation,
+    Widget child,
+  ) {
+    return FadeTransition(opacity: animation, child: child);
+  }
+}
diff --git a/lib/src/widget/asset_picker_viewer.dart b/lib/src/widget/asset_picker_viewer.dart
@@ -14,6 +14,7 @@ import '../delegates/asset_picker_viewer_builder_delegate.dart';
 import '../provider/asset_picker_provider.dart';
 import '../provider/asset_picker_viewer_provider.dart';
 import 'asset_picker.dart';
+import 'asset_picker_page_route.dart';
 
 class AssetPickerViewer<Asset, Path> extends StatefulWidget {
   const AssetPickerViewer({
@@ -44,6 +45,9 @@ class AssetPickerViewer<Asset, Path> extends StatefulWidget {
     PermissionRequestOption permissionRequestOption =
         const PermissionRequestOption(),
     bool shouldAutoplayPreview = false,
+    bool useRootNavigator = false,
+    RouteSettings? pageRouteSettings,
+    AssetPickerViewerPageRouteBuilder<List<AssetEntity>>? pageRouteBuilder,
   }) async {
     if (previewAssets.isEmpty) {
       throw StateError('Previewing empty assets is not allowed.');
@@ -72,15 +76,13 @@ class AssetPickerViewer<Asset, Path> extends StatefulWidget {
         shouldAutoplayPreview: shouldAutoplayPreview,
       ),
     );
-    final PageRouteBuilder<List<AssetEntity>> pageRoute =
-        PageRouteBuilder<List<AssetEntity>>(
-      pageBuilder: (_, __, ___) => viewer,
-      transitionsBuilder: (_, Animation<double> animation, __, Widget child) {
-        return FadeTransition(opacity: animation, child: child);
-      },
+    final List<AssetEntity>? result = await Navigator.maybeOf(
+      context,
+      rootNavigator: useRootNavigator,
+    )?.push<List<AssetEntity>>(
+      pageRouteBuilder?.call(viewer) ??
+          AssetPickerViewerPageRoute(builder: (context) => viewer),
     );
-    final List<AssetEntity>? result =
-        await Navigator.maybeOf(context)?.push<List<AssetEntity>>(pageRoute);
     return result;
   }
 
@@ -91,17 +93,19 @@ class AssetPickerViewer<Asset, Path> extends StatefulWidget {
     required AssetPickerViewerBuilderDelegate<A, P> delegate,
     PermissionRequestOption permissionRequestOption =
         const PermissionRequestOption(),
+    bool useRootNavigator = false,
+    RouteSettings? pageRouteSettings,
+    AssetPickerViewerPageRouteBuilder<List<A>>? pageRouteBuilder,
   }) async {
     await AssetPicker.permissionCheck(requestOption: permissionRequestOption);
     final Widget viewer = AssetPickerViewer<A, P>(builder: delegate);
-    final PageRouteBuilder<List<A>> pageRoute = PageRouteBuilder<List<A>>(
-      pageBuilder: (_, __, ___) => viewer,
-      transitionsBuilder: (_, Animation<double> animation, __, Widget child) {
-        return FadeTransition(opacity: animation, child: child);
-      },
+    final List<A>? result = await Navigator.maybeOf(
+      context,
+      rootNavigator: useRootNavigator,
+    )?.push<List<A>>(
+      pageRouteBuilder?.call(viewer) ??
+          AssetPickerViewerPageRoute(builder: (context) => viewer),
     );
-    final List<A>? result =
-        await Navigator.maybeOf(context)?.push<List<A>>(pageRoute);
     return result;
   }
 }
diff --git a/test/test_utils.dart b/test/test_utils.dart
