FutureBuilder — bu nədir, Flutter-də Future ilə iş

Flutter-də FutureBuilder nədir

FutureBuilder — bu, widgets paketindən Future<T> və builder funksiyasını qəbul edən daxili Flutter vidjetidir. Future vəziyyəti dəyişdikdə (icra olunur, məlumatla tamamlanır, xəta ilə tamamlanır) FutureBuilder avtomatik olaraq UI-ni yenidən qurur, builder-i yeni AsyncSnapshot ilə çağırır. Bu, setState və bayraqlar vasitəsilə yükləmə vəziyyətini əl ilə idarə etmək ehtiyacını aradan qaldırır.

Məlumat axınları (Stream) ilə işləyən StreamBuilder-dən fərqli olaraq, FutureBuilder təkrar olunmayan asinxron əməliyyatlar üçün nəzərdə tutulub: HTTP sorğusu, fayldan oxuma, verilənlər bazası sorğusu. FutureBuilder Future-ə abunəliyi özü idarə edir: ilk qurulmada Future-i işə salır və onun tamamlanmasını izləyir. Vidjet məhv edildikdə FutureBuilder Future-i ləğv etmir — bu, tərtibatçının məsuliyyətidir.

Flutter Cookbook (2026)-ə görə, FutureBuilder asinxron əməliyyatın ekranın inisiallaşdırılması zamanı bir dəfə işə salındığı hallar üçün tövsiyə olunur. Təkrarlanan əməliyyatlar və ya məlumat axınları üçün StreamBuilder istifadə edin. Hər iki vidjet Reactive UI nümunəsinə əməl edir, lakin FutureBuilder təkrar sorğular üçün optimallaşdırılıb.

FutureBuilder daxili olaraq necə işləyir

FutureBuilder-in daxili tətbiqi Future.then və catchError vasitəsilə Future-ə abunə olur. Başlanğıcda FutureBuilder connectionState-i ConnectionState.waiting-ə təyin edir və builder-i boş məlumatlarla çağırır. Uğurlu tamamlanmada connectionState məlumatlarla ConnectionState.done-a dəyişir. Xəta olduqda snapshot.error xəta obyekti ilə doldurulur. Hər dəyişiklik vidjetin yenidən qurulmasını tetikler.

AsyncSnapshot: vəziyyətlər və xüsusiyyətlər

AsyncSnapshot — FutureBuilder-in hər vəziyyət dəyişikliyində builder funksiyasına ötürdüyü konteyner obyektidir. O, asinxron əməliyyatın cari statusu haqqında bütün məlumatları ehtiva edir: yükləmə davam edirmi, hansı məlumatlar alınıb, xəta baş veribmi. AsyncSnapshot-u başa düşmək FutureBuilder ilə UI-nin düzgün qurulmasının açarıdır.

ConnectionState: asinxron əməliyyatın dörd vəziyyəti

Enum ConnectionState asinxron əməliyyatın mərhələsini müəyyən edir. None — Future hələ işə salınmadıqda başlanğıc vəziyyət (nadir hallarda, adətən initialData olmadan ilk qurulmada istifadə olunur). Waiting — Future icra olunur, məlumat hələ alınmayıb. Active — yalnız StreamBuilder tərəfindən qismən məlumatlı axınlar üçün istifadə olunur. Done — Future tamamlandı, məlumat snapshot.data və ya xəta snapshot.error vasitəsilə əlçatandır.

Builder funksiyasında AsyncSnapshot-un bütün vəziyyətlərinin düzgün idarə olunması istehsal kodu üçün məcburi tələbdir. Əgər waiting vəziyyətini idarə etməsəniz, istifadəçi yükləmə zamanı boş ekran görəcək. Əgər hasError-ı idarə etməsəniz, istifadəçi izahsız Exception alacaq. Tövsiyə olunan nümunə: hasError yoxlaması → hasData yoxlaması → standart olaraq yükləmə göstərilməsi.

FutureBuilder istifadə nümunələri

FutureBuilder bir neçə standart nümunədə istifadə oluna bilər, hər biri konkret tapşırığı həll edir. Əsas ssenariləri nəzərdən keçirək: inisiallaşdırma zamanı məlumat yükləmə, keşlə yükləmə, paralel sorğular və təkrarlama ilə xəta idarəetməsi.

Ekranın inisiallaşdırılması zamanı məlumat yükləmə

Ən geniş yayılmış nümunə — StatefulWidget və ya StatelessWidget-in build metodunda FutureBuilder. Future initState-dən ötürülür və ya birbaşa build-də yaradılır. Bu zaman Future-i hər yenidən qurulmada build metodunda yaratmamaq vacibdir — bu, təkrar sorğulara səbəb olacaq. State sahəsində saxlanılan Future-dən istifadə edin.

Keşlə yükləmə və yeniləmə

Təkrar sorğuların qarşısını almaq üçün FutureBuilder CachedNetworkImage və ya yerli keşlə birləşdirilə bilər. İlk yükləmədən sonra məlumat yaddaşda və ya SharedPreferences-də saxlanılır, FutureBuilder isə keşlənmiş məlumatı dərhal göstərir, paralel olaraq onu şəbəkədən yeniləyir. Bu, ani cavab verməklə UX-i yaxşılaşdırır.

pub.dev (2026)-yə görə, keşləmə xüsusilə şəkillər və məlumat siyahıları üçün aktualdır. FutureBuilder CachedNetworkImageProvider ilə avtomatik olaraq keşlənmiş şəkli göstərir, olmadıqda isə yükləmə göstəricisi ilə sonra endirilmiş faylı göstərir.

FutureBuilder vs setState: nə seçməli

FutureBuilder və setState vasitəsilə əl ilə vəziyyət idarəetməsi — Flutter-də asinxron UI-ə iki yanaşma. Hər birinin üstünlükləri və məhdudiyyətləri var. Seçim ekranın mürəkkəbliyindən və asinxron əməliyyatların sayından asılıdır.

FutureBuilder sadəliyi ilə qalib gəlir: yükləmə vəziyyəti, məlumat və xəta üçün sahələr elan etmək lazım deyil — hər şey AsyncSnapshot vasitəsilə idarə olunur. Bir asinxron əməliyyatı olan sadə ekranlar üçün idealdır (bir HTTP sorğusu, verilənlər bazasından oxuma). Lakin bir ekranda 5+ asinxron əməliyyat olduqda FutureBuilder həddindən artıq iç-içəlik yaradır — iç-içə FutureBuilder-lərdən \u201cpiramida\u201d alınır.

setState əl ilə vəziyyət bayraqları ilə mürəkkəb məntiqdə daha çox nəzarət və oxunaqlılıq verir. Çoxsaylı asılı sorğuları olan ekranlar üçün (istifadəçini yüklə → onun sifarişlərini yüklə → sifariş detallarını yüklə) setState-i ChangeNotifier və ya Bloc ilə istifadə etmək daha yaxşıdır. Flutter State Management Guide (2026)-yə görə, mürəkkəb ssenarilər üçün FutureBuilder əvəzinə Riverpod və ya Bloc istifadə etmək tövsiyə olunur, çünki onlar məntiq və təqdimatın daha yaxşı ayrılmasını təmin edir.

Şəbəkədən məlumat yükləmə ilə FutureBuilder nümunəsi

REST API-dən istifadəçi siyahısını yükləmək üçün praktiki FutureBuilder nümunəsini nəzərdən keçirək. Kod AsyncSnapshot-un hər üç vəziyyətinin düzgün idarə olunmasını nümayiş etdirir: yükləmə, xəta və hazır məlumat.

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('İstifadəçilər')),
      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('Xəta: ${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());
        },
      ),
    );
  }
}

Nümunədə FutureBuilder hər üç vəziyyəti idarə edir. Xəta olduqda xəta mesajı ilə ikon göstərilir. Uğurlu yükləmədə — avatarlar və adlarla ListView. Yükləmə zamanı — CircularProgressIndicator. Future sinif sahəsi kimi elan edilib, bu da yenidən qurulmada təkrar çağırışın qarşısını alır. Bu nümunə mobil tətbiqlərdə FutureBuilder istifadə ssenarilərinin 90%-ni əhatə edir.