FutureBuilder — ما هو، العمل مع Future في Flutter

ما هو FutureBuilder في Flutter

FutureBuilder هو عنصر واجهة مدمج في Flutter من حزمة widgets يأخذ Future ودالة builder. عندما تتغير حالة Future (قيد التشغيل، مكتمل مع بيانات، مكتمل مع خطأ)، يقوم FutureBuilder تلقائياً بإعادة بناء واجهة المستخدم باستدعاء builder مع AsyncSnapshot جديد. هذا يلغي الحاجة لإدارة حالة التحميل يدوياً عبر setState والأعلام.

على عكس StreamBuilder الذي يعمل مع تدفقات البيانات (Stream)، FutureBuilder مصمم للعمليات غير المتزامنة لمرة واحدة: طلب HTTP، قراءة ملف، استعلام قاعدة بيانات. FutureBuilder يدير الاشتراك في Future بنفسه: عند البناء الأول، يبدأ Future ويتتبع اكتماله. عندما يتم تدمير العنصر، لا يلغي FutureBuilder الـ Future — هذه مسؤولية المطور.

وفقاً لـ Flutter Cookbook (2026)، يُوصى باستخدام FutureBuilder للحالات التي تُنفذ فيها عملية غير متزامنة مرة واحدة عند تهيئة الشاشة. للعمليات المتكررة أو تدفقات البيانات، استخدم StreamBuilder. كلا العنصرين يتبعان نفس نمط واجهة المستخدم التفاعلية، لكن FutureBuilder محسّن للطلبات لمرة واحدة.

كيف يعمل FutureBuilder داخلياً

التنفيذ الداخلي لـ FutureBuilder يشترك في Future باستخدام Future.then و catchError. عند بدء FutureBuilder، يضبط connectionState على ConnectionState.waiting ويستدعي builder ببيانات فارغة. عند الاكتمال بنجاح، يتغير connectionState إلى ConnectionState.done مع البيانات. عند الخطأ، يمتلئ snapshot.error بكائن الخطأ. كل تغيير يؤدي إلى إعادة بناء العنصر.

AsyncSnapshot: الحالات والخصائص

AsyncSnapshot هو كائن حاوية يمرره FutureBuilder إلى دالة builder عند كل تغيير حالة. يحتوي على كل المعلومات حول الحالة الحالية للعملية غير المتزامنة: هل التحميل قيد التقدم، ما البيانات المستلمة، أو هل حدث خطأ. فهم AsyncSnapshot هو مفتاح بناء واجهة المستخدم بشكل صحيح مع FutureBuilder.

ConnectionState: أربع حالات لعملية غير متزامنة

التعداد ConnectionState يحدد مرحلة العملية غير المتزامنة. None — الحالة الأولية عندما لم يبدأ Future بعد (نادر الاستخدام، عادة في البناء الأول بدون initialData). Waiting — Future قيد التنفيذ، البيانات لم تستلم بعد. Active — يُستخدم فقط بواسطة StreamBuilder للتدفقات ذات البيانات الجزئية. Done — اكتمل Future، البيانات متاحة عبر snapshot.data أو الخطأ عبر snapshot.error.

المعالجة الصحيحة لجميع حالات AsyncSnapshot في دالة builder هي شرط إلزامي لكود الإنتاج. إذا لم يتم معالجة حالة waiting، سيرى المستخدم شاشة فارغة أثناء التحميل. إذا لم يتم معالجة hasError، سيتلقى المستخدم استثناءً بدون شرح. النمط الموصى به: تحقق من hasError → تحقق من hasData → عرض التحميل افتراضياً.

أنماط استخدام FutureBuilder

FutureBuilder يمكن استخدامه بعدة أنماط قياسية، كل منها يحل مهمة محددة. دعنا ننظر إلى السيناريوهات الرئيسية: تحميل البيانات عند التهيئة، التحميل مع التخزين المؤقت، الطلبات المتوازية ومعالجة الأخطاء مع إعادة المحاولة.

تحميل البيانات عند تهيئة الشاشة

النمط الأكثر شيوعاً — FutureBuilder في دالة build لـ StatefulWidget أو StatelessWidget. يتم تمرير Future من initState أو إنشاؤه مباشرة في build. من المهم عدم إنشاء Future في دالة build عند كل إعادة بناء — سيؤدي ذلك إلى طلبات متكررة. استخدم Future مخزناً في حقل State.

التحميل مع التخزين المؤقت والتحديث

لمنع الطلبات المتكررة، يمكن دمج FutureBuilder مع CachedNetworkImage أو ذاكرة تخزين مؤقت محلية. بعد التحميل الأول، تُحفظ البيانات في الذاكرة أو SharedPreferences، ويعرض FutureBuilder البيانات المخزنة مؤقتاً فورياً مع تحديثها من الشبكة بالتوازي. هذا يحسن تجربة المستخدم من خلال الاستجابة الفورية.

وفقاً لـ pub.dev (2026)، التخزين المؤقت مهم بشكل خاص للصور وقوائم البيانات. FutureBuilder مع CachedNetworkImageProvider يعرض تلقائياً الصورة المخزنة مؤقتاً، وعند غيابها — مؤشر تحميل يليه عرض الملف الذي تم تنزيله.

FutureBuilder مقابل setState: أيهما تختار

FutureBuilder وإدارة الحالة اليدوية عبر setState هما نهجان لواجهة المستخدم غير المتزامنة في Flutter. لكل منهما مزاياه وقيوده. يعتمد الاختيار على تعقيد الشاشة وعدد العمليات غير المتزامنة.

FutureBuilder يتفوق في البساطة: لا تحتاج لإعلان حقول لحالة التحميل والبيانات والخطأ — كل شيء يُدار عبر AsyncSnapshot. إنه مثالي للشاشات البسيطة بعملية غير متزامنة واحدة (طلب HTTP واحد، قراءة قاعدة بيانات). ومع ذلك، مع 5+ عمليات غير متزامنة على شاشة واحدة، يُنشئ FutureBuilder تداخلاً مفرطاً — مما ينتج “هرماً” من FutureBuilders المتداخلة.

setState مع أعلام الحالة اليدوية يعطي تحكماً أكبر وقابلية قراءة أفضل للوغاريتمات المعقدة. للشاشات ذات الطلبات المتعددة والمترابطة (تحميل مستخدم → تحميل طلباته → تحميل تفاصيل الطلب)، من الأفضل استخدام setState مع ChangeNotifier أو Bloc. وفقاً لدليل إدارة حالة Flutter (2026)، للسيناريوهات المعقدة يُوصى باستخدام Riverpod أو Bloc بدلاً من FutureBuilder، حيث أنها توفر فصلاً أفضل بين المنطق والعرض.

مثال FutureBuilder مع تحميل بيانات من الشبكة

لنفكر في مثال عملي لـ FutureBuilder لتحميل قائمة مستخدمين من REST API. يوضح الكود المعالجة الصحيحة لحالات AsyncSnapshot الثلاث: التحميل والخطأ والبيانات الجاهزة.

class UserListPage extends StatefulWidget {
  const UserListPage({super.key});

  @override
  State<UserListPage> createState() => _UserListPageState();
}

class _UserListPageState extends State<UserListPage> {
  final Future<List<User>> usersFuture = UserRepository().fetchUsers();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('المستخدمين')),
      body: FutureBuilder<List<User>>(
        future: usersFuture,
        builder: (context, AsyncSnapshot<List<User>> snapshot) {
          if (snapshot.hasError) {
            return Center(
              child: Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  const Icon(Icons.error_outline, size: 48, color: Colors.red),
                  const SizedBox(height: 16),
                  Text('خطأ: ${snapshot.error}'),
                ],
              ),
            );
          }

          if (snapshot.hasData) {
            final users = snapshot.data!;
            return ListView.builder(
              itemCount: users.length,
              itemBuilder: (context, index) {
                return ListTile(
                  leading: CircleAvatar(backgroundImage: NetworkImage(users[index].avatarUrl)),
                  title: Text(users[index].name),
                  subtitle: Text(users[index].email),
                );
              },
            );
          }

          return const Center(child: CircularProgressIndicator());
        },
      ),
    );
  }
}

في المثال، FutureBuilder يعالج الحالات الثلاث. عند الخطأ، يتم عرض أيقونة مع رسالة خطأ. عند التحميل الناجح — ListView مع الصور الرمزية والأسماء. أثناء التحميل — CircularProgressIndicator. يُعلن Future كحقل فئة، مما يمنع الاستدعاء المتكرر عند إعادة البناء. هذا النمط يغطي 90% من سيناريوهات استخدام FutureBuilder في تطبيقات الجوال.