شرح Pagination في Flutter لتحميل صفحات القائمة تدريجيًا، مع منع الطلبات المكررة وإعادة المحاولة وإنهاء التحميل عند نفاد البيانات.
عقد البيانات قبل ScrollController
حدّد هل الواجهة تستخدم رقم صفحة أو offset أو cursor، وكيف تعلن نهاية النتائج. ليس كل API ينتهي عندما يقل العدد عن limit؛ قد يعيد nextCursor أو hasMore صراحة. لا تفترض أن إضافة page++ تصلح لكل خادم، ولا تزيد المؤشر قبل نجاح الصفحة لأن الفشل سيجعل المحاولة التالية تتجاوز بيانات. عند تغير ترتيب البيانات أثناء التصفح قد تظهر عناصر مكررة أو مفقودة حسب العقد؛ فكر في ترتيب ثابت أو cursor مع توثيق ما يضمنه الخادم.
منع التكرار والتعامل مع الخطأ
احفظ isLoading وافحصه قبل بدء الطلب حتى لا ترسل أحداث التمرير عدة طلبات للصفحة نفسها. عند الفشل احتفظ بالمؤشر والبيانات السابقة، واعرض زرًا لمحاولة الصفحة الفاشلة. أعد حالة التحميل في finally مع فحص mounted، ولا تتركها صحيحة إلى الأبد إذا كانت الاستجابة غير 200 أو فشل JSON. لا تمسح القائمة كلها عند كل خطأ تحميل إضافي؛ المستخدم قد يحتاج قراءة العناصر المحملة بالفعل بينما يتعذر الوصول إلى المزيد.
ابدأ التحميل قبل نهاية القائمة
المقارنة الدقيقة بين offset وmaxScrollExtent قد تفوّت الحدث أو تصل متأخرة. يمكن مراقبة extentAfter والبدء حين يقترب المستخدم من نهاية المحتوى، مع وجود client للمتحكم. اختر عتبة مناسبة للتصميم وسرعة الخدمة. إذا كانت الصفحة الأولى أقصر من مساحة الشاشة فقد لا يحدث تمرير أصلًا؛ وفر زر تحميل المزيد أو سياسة محدودة تملأ المساحة، ولا تفتح حلقة طلبات غير محدودة لمجرد أن النتائج قليلة أو الخادم يعيد صفحة فارغة بصورة غير متوقعة.
البحث والتحديث وسباق الردود
إذا تغير مرشح البحث بينما طلب صفحة قديمة جارٍ، يجب ألا يلحق الرد القديم عناصره بالقائمة الجديدة. استخدم جيل طلبات أو إلغاء مدعومًا ومقارنة هوية المورد، ثم أعد المؤشر وحالة النهاية وفق الاستعلام الجديد. احتفظ بمعرّفات مستقرة للعناصر إذا احتجت منع التكرار، ولا تعتمد العنوان كمفتاح فريد عندما يمكن أن يتشابه. عند refresh قرر هل تُبقي البيانات القديمة أثناء التحميل أم تظهر حالة جديدة، واجعل ذلك واضحًا للمستخدم.
ملكية المتحكم والأداء
أنشئ ScrollController مرة واحدة في State وأزل listener وأغلق المتحكم في dispose. استخدم ListView.builder حتى لا تبني جميع العناصر دفعة واحدة، وافصل حالات عنصر القائمة عن منطق جلب البيانات. تحديد image sizes وتقليل حجم payload قد يفيدان أكثر من زيادة عدد العناصر لكل صفحة عشوائيًا. راقب الذاكرة إذا كان المستخدم يستطيع تحميل آلاف الصفحات؛ قد تحتاج سياسة احتفاظ أو نافذة بيانات حسب نوع التطبيق. Pagination تقلل التحميل الأولي لكنها لا تضمن حجم ذاكرة ثابتًا وحدها.
تشغيل المثال والتحقق
مصدر البيانات التالي محلي يعيد أرقامًا على صفحات محدودة، ولذلك لا يحتاج http أو حساب خدمة. استبدله في تطبيقك بدالة repository تتحقق من status وشكل JSON وعقد نهاية البيانات. اختبر الضغط المتكرر على الزر والتمرير السريع والفشل في صفحة وسطية والنهاية والقائمة الفارغة والخروج أثناء الانتظار. لا تضع setState async، ولا تستخدم كودًا يشير إلى http دون إضافة import واعتماد متوافق. حافظ على القراءة منفصلة عن أي كتابة أو حذف كي لا تحول إعادة المحاولة إلى عملية تتكرر آثارها.
المثال التطبيقي
المثال مستقل للتعلم. شغّله داخل مشروع تجريبي، ثم بدّل مصدر البيانات المحلي بخدمة مشروعك بعد اختبار حالات النجاح والفشل. لا تنسخ أكثر من دالة main إلى الملف نفسه.
import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: DemoPage()));
class DemoPage extends StatefulWidget {
const DemoPage({super.key});
@override
State<DemoPage> createState() => _DemoPageState();
}
class _DemoPageState extends State<DemoPage> {
final _controller = ScrollController();
final _items = <int>[];
int _page = 0;
bool _loading = false;
bool _hasMore = true;
String? _error;
@override
void initState() { super.initState(); _controller.addListener(_onScroll); _load(); }
void _onScroll() {
if (_controller.hasClients && _controller.position.extentAfter < 200 && _error == null) _load();
}
Future<List<int>> _fetch(int page) async {
await Future<void>.delayed(const Duration(milliseconds: 200));
return page >= 3 ? [] : List.generate(12, (index) => page * 12 + index);
}
Future<void> _load() async {
if (_loading || !_hasMore) return;
setState(() { _loading = true; _error = null; });
try {
final values = await _fetch(_page);
if (!mounted) return;
setState(() { _items.addAll(values); ++_page; _hasMore = values.length == 12; });
} catch (_) {
if (mounted) setState(() { _error = 'Could not load this page'; });
} finally {
if (mounted) setState(() { _loading = false; });
}
}
@override
void dispose() { _controller.removeListener(_onScroll); _controller.dispose(); super.dispose(); }
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Pagination')),
body: ListView.builder(
controller: _controller,
itemCount: _items.length + 1,
itemBuilder: (context, index) {
if (index < _items.length) return ListTile(title: Text('Item ${_items[index]}'));
if (_loading) return const Center(child: CircularProgressIndicator());
if (!_hasMore) return const Center(child: Text('End of list'));
return Column(children: [
if (_error != null) Text(_error!),
TextButton(onPressed: _load, child: const Text('Load more / retry')),
]);
},
),
);
}التوثيق والتجربة
راجع التوثيق الرسمي عند مطابقة إصدار الأداة. اختبر العودة إلى الصفحة والخروج منها والحالة الفارغة والفشل، وراقب أن الموارد التي تملكها الصفحة تُغلق عند انتهاء حاجتها.
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.
تطبيق Pagination في Flutter في مشروعك
امنع تحميل الصفحة نفسها مرتين، واعرض حالة نهاية القائمة والفشل بشكل منفصل؛ احتفظ برقم الصفحة حتى ينجح طلبها بدل تجاوزه بعد خطأ.
مراجع الموضوع: api.flutter.dev — extentAfter.html






