النافذة السفلية (modal bottom sheet) تبدو شيئًا بسيطًا إلى أن تضع داخلها قائمة. يسحب المستخدم إلى الأسفل فوق القائمة: هل تتحرك القائمة أم تتحرك النافذة؟ إن كانت القائمة في أعلاها، يجب أن تتبع النافذة الإصبع وتبقى القائمة ثابتة. وإن غيّر المستخدم الاتجاه، يجب أن تعود النافذة إلى مكانها قبل أن تبدأ القائمة بالتمرير. إذا أخطأت في هذا التسليم بين الاثنين، ينزلق المحتوى داخل النافذة أو يقفز عند عكس اتجاه السحب.

ثم تأتي بقية التفاصيل: لوحة المفاتيح، المنطقة الآمنة (safe area)، إيماءة الرجوع في Android، وPopScope يريد منع الإغلاق، و router ينتظر Page وليس استدعاء دالة.

sheet_route حزمة (package) لـ Flutter تعامل النافذة السفلية كمسار (route) حقيقي. توفّر أنماط Material و bar و iOS، وسحبًا للإغلاق يتعاون مع القوائم الداخلية، ونقاط توقف (snap points)، وأصناف Page تعمل مع Navigator.pages ومع go_router.

ماذا تقدّم

أربع طرق لإظهار النافذة. showSheet هي الدالة الأساسية، وتستطيع معها وضع زخرفتك الخاصة عبر containerBuilder. أما showMaterialStyleSheet وshowBarSheet وshowCupertinoStyleSheet فتعطيك الأشكال الثلاثة الشائعة. كل دالة تُرجع Future يحمل القيمة التي أُغلقت بها النافذة.

مسارات وصفحات حقيقية. SheetRoute وCupertinoSheetRoute يعملان مع Navigator.push. وSheetPage وCupertinoSheetPage يعملان مع Navigator.pages ومع pageBuilder في go_router، فيمكن أن يكون للنافذة مسارها الخاص.

سحب للإغلاق يتفاهم مع القوائم. السحب يتعاون مع ListView وGridView وCustomScrollView داخل النافذة. عندما تكون القائمة في أعلاها، السحب إلى الأسفل يحرّك النافذة وتبقى القائمة ثابتة، مهما كان نوع الـ scroll physics. والسحب إلى الأعلى يعيد النافذة أولًا ثم تبدأ القائمة بالتمرير. تفعل الحزمة ذلك بتمرير السحب عبر ScrollPosition الخاص بالقائمة قبل أن تعمل الـ physics.

نقاط التوقف (snap points). مرّر snapPoints: [0.4, 0.7, 1.0] فتستقر النافذة عند هذه النسب من الارتفاع المتاح. والقذف السريع (fling) ينقلها إلى نقطة التوقف التالية.

تأثير iOS حيث تتراجع الصفحة السابقة. مبني على ModalRoute.delegatedTransition، فلا تحتاج widget يغلّف التطبيق ولا page route خاصًا تحت النافذة. والنوافذ المتراكمة فوق بعضها تتقلص أيضًا.

لوحة المفاتيح والمنطقة الآمنة. تبقى النافذة فوق لوحة المفاتيح، والمحتوى الداخلي يرى viewInsets.bottom == 0، فلا يُطبَّق الـ padding مرتين. النافذة لا تغطي شريط الحالة أبدًا، ومع useSafeArea يتجنب المحتوى مؤشر الصفحة الرئيسية (home indicator).

قواعد إغلاق واضحة. isDismissible: false يمنع الإغلاق بالنقر على الخلفية (barrier)، وبزر الرجوع، وبإيماءة predictive back. وأي PopScope داخل النافذة يستطيع رفض السحب والقذف والنقر على الخلفية والرجوع، ويُستدعى onPopInvokedWithResult الخاص به. وفي Android، تعرض النافذة معاينة لإيماءة predictive back وتُغلق عند تأكيدها.

إمكانية الوصول واتجاه الواجهة. النافذة تُعرَّف كـ route scope له اسم في الـ semantics، والخلفية تحمل تسمية للإغلاق وإجراء نقر. واجهات RTL وتقليل الحركة (MediaQueryData.disableAnimations) مدعومة.

الـ callbacks. onDragUpdate يعطيك الارتفاع الظاهر أثناء السحب، وonDismiss يُستدعى عندما تُغلق النافذة دون نتيجة.

طريقة الاستعمال

أضِفها من GitHub:

dependencies: sheet_route: git: https://github.com/AbdeldjalilChougui/sheet_route 

تحتاج Flutter 3.27 أو أحدث، وهو أول إصدار فيه ModalRoute.delegatedTransition.

نافذة بنمط Material تُرجع قيمة:

import 'package:flutter/material.dart'; import 'package:sheet_route/sheet_route.dart'; Future<void> pickAction(BuildContext context) async { final String? action = await showMaterialStyleSheet<String>( context: context, showDragHandle: true, builder: (BuildContext context) => Column( mainAxisSize: MainAxisSize.min, children: <Widget>[ ListTile( title: const Text('Share'), onTap: () => Navigator.of(context).pop('share'), ), ], ), ); debugPrint('picked $action'); } 

نافذة مع snap points:

showSheet<void>( context: context, snapPoints: const <double>[0.4, 0.7, 1.0], initialSnapPoint: 0.4, topRadius: const Radius.circular(16), builder: (BuildContext context) => ListView(children: const <Widget>[]), ); 

ونافذة بنمط iOS كصفحة في go_router:

GoRoute( path: 'details', pageBuilder: (BuildContext context, GoRouterState state) => CupertinoSheetPage<void>(key: state.pageKey, child: const Details()), ), 

القائمة الأساسية (primary scroll view) داخل النافذة تأخذ الـ controller الخاص بالنافذة تلقائيًا. أما القائمة غير الأساسية (قائمة متداخلة، أو قائمة لها controller خاص، أو أي قائمة على سطح المكتب حيث لا يُورَّث PrimaryScrollController تلقائيًا) فتستطيع الانضمام هكذا:

ListView(controller: SheetRoute.scrollControllerOf(context), children: items); 

أهم الخيارات: expand (ملء الارتفاع المتاح بدل التقيّد بحجم المحتوى)، وisDismissible، وenableDrag، وcloseProgressThreshold (الإغلاق عند رفع الإصبع إذا كان الجزء الظاهر أقل من هذه النسبة، والقيمة الافتراضية 0.6)، وduration وanimationCurve لحركة الفتح والإغلاق، إضافة إلى خيارات الشكل المعتادة مثل backgroundColor وshape وtopRadius. أما سحب المستخدم فحركته خطية دائمًا.

الانتقال من modal_bottom_sheet

في الـ README جدول انتقال كامل. باختصار: showMaterialModalBottomSheet تصبح showMaterialStyleSheet، وshowBarModalBottomSheet تصبح showBarSheet، وshowCupertinoModalBottomSheet تصبح showCupertinoStyleSheet، وModalScrollController.of(context) تصبح SheetRoute.scrollControllerOf(context) وغالبًا لا تحتاجها. أما MaterialWithModalsPageRoute وCupertinoScaffold فتحذفهما ببساطة، لأن أي PageRoute تحت النافذة يتراجع تلقائيًا. وWillPopScope وshouldClose يُستبدلان بـ PopScope.

بعض الخيارات حُذفت: bounce (السحب فوق القمة يتوقف عند الحد)، وsecondAnimation، وpreviousRouteAnimationCurve، وtransitionBackgroundColor، وoverlayStyle (غلِّف المحتوى بـ AnnotatedRegion<SystemUiOverlayStyle> بدلًا منه).

أشياء يجب معرفتها

  • نقاط التوقف تحرّك النافذة ولا تغيّر حجمها. عند نقطة توقف منخفضة يكون الجزء السفلي من المحتوى خارج الشاشة. ضع الأزرار المهمة قرب الأعلى، أو استعمل قائمة قابلة للتمرير.
  • القوائم التي لا تستعمل controller النافذة تتصرف بشكل مختلف. تستطيع سحب النافذة إلى الأسفل عبر الـ overscroll عند الحافة العليا مع clamping physics، لكن السحب إلى الأعلى بعدها يمرّر القائمة بدل رفع النافذة، ومع bouncing physics ترتدّ القائمة بدل ذلك. وعجلات الاختيار (ListWheelScrollView) والقوائم الأفقية لا تحرّك النافذة أبدًا.
  • تأثير الصفحة السابقة له نطاق. يُطبَّق فقط على المسارات الموجودة في نفس الـ Navigator والتي يقبل canTransitionTo فيها النافذة. PageRoute وMaterialPageRoute وCupertinoPageRoute وصفحات go_router كلها تقبل. ومع useRootNavigator: true و navigator متداخل، يتقلص فقط المسار العلوي في الـ root navigator.
  • تحديث SheetPage يجدّد child فقط. عند تحديث صفحة بنفس الـ key، تبقى بقية الخيارات كما كانت عند إنشاء المسار.
  • isDismissible: false يمنع الرجوع أيضًا: زر الرجوع، وNavigator.maybePop، و predictive back. أما السحب فيتحكم فيه enableDrag.
  • تعارض في الأسماء. مكتبة cupertino في Flutter (من 3.29) تعرّف هي أيضًا CupertinoSheetRoute. في الملف الذي يستورد الاثنين استعمل import 'package:flutter/cupertino.dart' hide CupertinoSheetRoute;.
  • ما الذي اختُبر. كل فرق في السلوك عن الحزمة القديمة يغطيه widget test (مشكلة القفز عند التمرير، PopScope داخل النافذة، التخطيط مع لوحة المفاتيح). إيماءات السحب تم التحقق منها بـ widget tests، ولم تُقَس على أجهزة حقيقية.

لماذا بنيتها

يشرح الـ README المشكلة من خلال المقارنة مع modal_bottom_sheet. تلك الحزمة كانت تتفاعل مع إشعارات التمرير بعد أن تكون القائمة قد تحركت فعلًا، فمع bouncing physics كان المحتوى ينزلق داخل النافذة أو يقفز عند عكس السحب. والـ route فيها كان يعتمد على hasScopedWillPopCallback وwillPop() اللذين أصبحا deprecated منذ Flutter 3.12، وعلى onPopInvoked الذي استُبدل لاحقًا. والنتيجة أن PopScope داخل النافذة كان يُتجاهل أو يسبب crash في إصدارات Flutter الأحدث. والنافذة بنمط iOS كانت تحتاج CupertinoScaffold حول التطبيق، وترمي خطأ null-check بدونه.

أردت نوافذ تتبع واجهات Flutter الحالية: popDisposition وonPopInvokedWithResult للإغلاق، وModalRoute.delegatedTransition لتأثير تراجع الصفحة، وScrollPosition الخاص بالقائمة لتسليم السحب. وأردت أصناف Page في نفس الحزمة، حتى تعمل النافذة نفسها مع Navigator.push ومع go_router.

احصل على الكود

المصدر، وجدول الانتقال، والاختبارات، وتطبيق example/ الذي يعرض كل الأنماط والميزات، كلها على GitHub: https://github.com/AbdeldjalilChougui/sheet_route. الرخصة MIT. الملاحظات (issues) وطلبات الدمج (pull requests) مرحّب بها.

نُشر في الأصل على abdeldjalilchougui.biz.