FutureBuilder

عرض نتيجة Future تلقائيًا FutureBuilder

FutureBuilder يبني الواجهة تلقائيًا حسب حالة Future — انتظار، نجاح، أو خطأ — بلا حاجة لإدارة الحالة يدويًا.

يأخذ future ودالة builder تُستدعى كل مرة تتغيّر فيها حالة الـ AsyncSnapshot. غالبًا يُستخدم لعرض بيانات قادمة من الشبكة أو قاعدة بيانات محلية عند فتح الشاشة أول مرة.

الصياغة

FutureBuilder<T>(
  future: Future<T>,
  builder: (context, AsyncSnapshot<T> snapshot) => Widget,
)

📄 مثال

FutureBuilder<List<String>>(
  future: fetchNames(),
  builder: (context, snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const CircularProgressIndicator();
    }
    if (snapshot.hasError) {
      return Text('خطأ: ${snapshot.error}');
    }
    final names = snapshot.data!;
    return ListView(
      children: names.map((n) => Text(n)).toList(),
    );
  },
)

أهم المعاملات

المعامل	الوظيفة
future	الـ Future الذي تُبنى الواجهة حسب حالته
builder	دالة تُستدعى بكل تغيّر بحالة الـ snapshot (انتظار/نجاح/خطأ)
snapshot.connectionState	حالة الاتصال الحالية — waiting قبل اكتمال Future
snapshot.hasError / snapshot.data	التحقق من نجاح أو فشل النتيجة

💡 نصائح عملية

مرّر future من متغيّر محفوظ بـ initState أو خارج build() — استدعاؤه مباشرة داخل معامل future بـ build() يعيد تنفيذه بكل إعادة رسم

⚠️ أخطاء شائعة

استدعاء دالة async مباشرة داخل معامل future بمكانها بـ build() — يُنفَّذ الطلب من جديد بكل إعادة بناء للويدجت، تكرار غير مقصود لطلبات الشبكة

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار FLUTTER الكامل بالعربي.