تحديث البيانات باستخدام RefreshIndicator في Flutter مع Future واضحة ومنع الطلب المتكرر وحفظ البيانات السابقة عند الفشل ودعم السحب مع قائمة قصيرة أو فارغة.
التحديث ليس تحميل الصفحة التالية
السحب من أعلى القائمة قد يعيد طلب بياناتها، بينما الوصول إلى أسفلها لتحميل صفحة إضافية هو pagination بتدفق مختلف. حدد هل تستبدل البيانات أم تدمجها، وما الذي يراه المستخدم أثناء الانتظار. المثال يحدّث قائمة محلية عبر loader يمكن استبداله في الاختبار، ولا يخلط تحديثها بإضافة عناصر عشوائية بلا هوية. التأخير الافتراضي يوضح التحميل فقط ولا يمثل اتصال API حقيقيًا أو وصول أخبار جديدة من خادم.
لا تجعل الفراغ يعني انتظارًا دائمًا
قائمة فارغة قد تكون نتيجة ناجحة، لذلك نملك _busy و_error و_data بصورة منفصلة. عند أول تحميل نظهر مؤشرًا، وبعد نجاح بلا عناصر نظهر No lessons yet. إذا فشل التحديث بعد وجود بيانات نبقيها ونعرض رسالة خطأ إضافية بدل مسحها وإظهار مؤشر لا ينتهي. هذه سياسة عرض واضحة، ويمكن لمنتج آخر اختيار سياسة مختلفة إذا شرحها. لا تستخدم data.isEmpty وحدها لتحديد أن الطلب ما زال قيد التنفيذ.
Future ومنع تكرار الطلب
onRefresh يحتاج Future تنتهي عند اكتمال محاولة التحديث. _load تحرس _busy قبل بدء العمل، وتعيد ضبطها في finally، وتتحقق من mounted قبل تحديث State بعد await. لا تجعل callback async داخل setState، ولا تطلق طلبًا جديدًا في itemBuilder عند كل إعادة بناء. إذا كان التطبيق يسمح بإلغاء الطلب أو تبديل مرشح أثناءه فقد تحتاج معرّف طلب وإلغاء حتى لا تستبدل نتيجة قديمة بيانات أحدث. المثال يمنع التوازي محليًا ولا يدعي أنه يغطي كل سياسة تحديث معقدة.
قائمة قصيرة قابلة للسحب
RefreshIndicator يحتاج Scrollable مناسبًا، والقائمة القصيرة قد لا تتجاوز مساحة العرض. AlwaysScrollableScrollPhysics في المثال يتيح إيماءة التحديث حتى عندما تكون البيانات قليلة أو فارغة. هذا لا يعني إنشاء SingleChildScrollView حول ListView طويلة مع shrinkWrap فقط ليعمل السحب؛ حافظ على تمرير واحد وقيود واضحة. واجهة CupertinoSliverRefreshControl تحتاج بنية slivers مناسبة، ولا يصبح الشكل iOS صحيحًا لمجرد وضع قائمة كاملة داخل SliverToBoxAdapter دون مراجعة الكلفة والسلوك.
الفشل وإعادة المحاولة
loader يرجع List
حالات المراجعة
اختبر نجاح أول تحميل، ونجاحًا فارغًا، وفشلًا قبل البيانات وبعدها، وطلبين متقاربين، ومغادرة الصفحة قبل اكتمال loader. تحقق أن المؤشر ينتهي وأن البيانات القديمة تبقى عند فشل التحديث حسب السياسة المعلنة. جرّب السحب على قائمة قصيرة وخطًا كبيرًا واتجاه العربية. الاختبار بخدمة وهمية يثبت تدفق الحالة في المثال، ولا يقيس سرعة شبكة حقيقية أو يدعم كل إيماءات المنصات تلقائيًا. لا تستبدل اختبارات عقد API بهذا المثال عند نقله إلى تطبيق مستخدمين فعليين.
مثال مستقل للتجربة
شغّل المثال داخل مشروع Flutter تجريبي. يعتمد على Material فقط ولا يحتاج assets أو أصنافًا من مشروع خاص. غيّر مساحة النافذة وجرّب تكبير النص أثناء الفحص، ثم انقل المكوّن إلى مشروعك بعد تحديد سياق قيوده الفعلي.
import 'dart:async';
import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: DemoPage()));
typedef LessonLoader = Future<List<String>> Function();
Future<List<String>> loadDemoLessons() async {
await Future<void>.delayed(const Duration(milliseconds: 200));
return ['Dart basics', 'Flutter layout', 'Async review'];
}
class DemoPage extends StatefulWidget {
const DemoPage({super.key, this.loader = loadDemoLessons});
final LessonLoader loader;
@override
State<DemoPage> createState() => _DemoPageState();
}
class _DemoPageState extends State<DemoPage> {
List<String> _data = [];
String? _error;
bool _busy = false;
@override
void initState() { super.initState(); unawaited(_load()); }
Future<void> _load() async {
if (_busy) return;
setState(() { _busy = true; _error = null; });
try {
final data = await widget.loader();
if (mounted) setState(() { _data = List.of(data); });
} catch (_) {
if (mounted) setState(() { _error = 'Could not refresh lessons'; });
} finally {
if (mounted) setState(() { _busy = false; });
}
}
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Refresh lessons'), actions: [
IconButton(tooltip: 'Reload', onPressed: _busy ? null : _load, icon: const Icon(Icons.refresh)),
]),
body: RefreshIndicator(onRefresh: _load, child: ListView.builder(
physics: const AlwaysScrollableScrollPhysics(),
itemCount: _data.isEmpty ? 1 : _data.length + (_error == null ? 0 : 1),
itemBuilder: (_, index) {
if (_data.isEmpty) return SizedBox(height: 220, child: Center(child: _busy
? const CircularProgressIndicator() : Text(_error ?? 'No lessons yet')));
if (index == _data.length) return Padding(padding: const EdgeInsets.all(16), child: Text(_error!));
return ListTile(title: Text(_data[index]));
},
)),
);
}مرجع الواجهة البرمجية
راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.







