FutureBuilder — nedir, Flutter'da Future ile çalışmak

Flutter'da FutureBuilder Nedir

FutureBuilder, widgets paketinden Future ve bir builder fonksiyonu alan yerleşik bir Flutter widget'ıdır. Future'in durumu değiştiğinde (çalışıyor, veriyle tamamlandı, hatayla tamamlandı), FutureBuilder yeni bir AsyncSnapshot ile builder'ı çağırarak UI'yı otomatik olarak yeniden oluşturur. Bu, setState ve bayraklar aracılığıyla yükleme durumunu manuel olarak yönetme ihtiyacını ortadan kaldırır.

Veri akışları (Stream) ile çalışan StreamBuilder'ın aksine, FutureBuilder tek seferlik asenkron işlemler için tasarlanmıştır: HTTP isteği, dosya okuma, veritabanı sorgusu. FutureBuilder, Future aboneliğini kendi yönetir: ilk derlemede Future'i başlatır ve tamamlanmasını izler. Widget yok edildiğinde, FutureBuilder Future'i iptal etmez — bu geliştiricinin sorumluluğundadır.

Flutter Cookbook (2026)'a göre FutureBuilder, ekran başlatılmasında asenkron işlemin bir kez çalıştığı durumlar için önerilir. Tekrarlayan işlemler veya veri akışları için StreamBuilder kullanın. Her iki widget da aynı Reaktif UI desenini izler, ancak FutureBuilder tek seferlik istekler için optimize edilmiştir.

FutureBuilder'ın Dahili Çalışması

FutureBuilder'ın dahili uygulaması, Future'e Future.then ve catchError kullanarak abone olur. FutureBuilder başladığında, connectionState'i ConnectionState.waiting olarak ayarlar ve boş veriyle builder'ı çağırır. Başarılı tamamlanmada, connectionState veriyle ConnectionState.done'a değişir. Hatada, snapshot.error hata nesnesiyle doldurulur. Her değişiklik widget yeniden oluşturmayı tetikler.

AsyncSnapshot: Durumlar ve Özellikler

AsyncSnapshot, FutureBuilder'ın her durum değişikliğinde builder fonksiyonuna ilettiği bir kapsayıcı nesnedir. Asenkron işlemin mevcut durumu hakkında tüm bilgileri içerir: yükleme devam ediyor mu, hangi veriler alındı veya bir hata oluştu mu. AsyncSnapshot'ı anlamak, FutureBuilder ile UI'yı doğru şekilde oluşturmanın anahtarıdır.

ConnectionState: Asenkron İşlemin Dört Durumu

ConnectionState enum'ı, asenkron işlemin aşamasını tanımlar. None — Future henüz başlatılmamış başlangıç durumu (nadiren kullanılır, genellikle initialData olmadan ilk derlemede). Waiting — Future çalışıyor, veri henüz alınmadı. Active — yalnızca StreamBuilder tarafından kısmi verili akışlar için kullanılır. Done — Future tamamlandı, veri snapshot.data veya hata snapshot.error aracılığıyla kullanılabilir.

Builder fonksiyonunda tüm AsyncSnapshot durumlarının doğru şekilde işlenmesi, üretim kodu için zorunlu bir gerekliliktir. waiting durumunu işlemezseniz, kullanıcı yükleme sırasında boş bir ekran görecektir. hasError'ı işlemezseniz, kullanıcı açıklama olmadan bir İstisna alacaktır. Önerilen desen: hasError'ı kontrol et → hasData'yı kontrol et → varsayılan olarak yüklemeyi göster.

FutureBuilder Kullanım Desenleri

FutureBuilder birkaç standart desende kullanılabilir, her biri belirli bir görevi çözer. Ana senaryolara bakalım: başlatmada veri yükleme, önbellekle yükleme, paralel istekler ve yeniden denemeyle hata yönetimi.

Ekran Başlatmada Veri Yükleme

En yaygın desen — StatefulWidget veya StatelessWidget'ın build metodunda FutureBuilder. Future, initState'den iletilir veya doğrudan build'de oluşturulur. Future'i her yeniden derlemede build metodunda oluşturmamak önemlidir — bu tekrarlayan isteklere yol açacaktır. State alanında saklanan bir Future kullanın.

Önbellek ve Yenileme ile Yükleme

Tekrarlayan istekleri önlemek için, FutureBuilder CachedNetworkImage veya yerel bir önbellekle birleştirilebilir. İlk yüklemeden sonra veri bellekte veya SharedPreferences'te saklanır ve FutureBuilder, ağdan paralel olarak güncellerken önbelleğe alınmış veriyi anında görüntüler. Bu, anında yanıt sayesinde kullanıcı deneyimini iyileştirir.

pub.dev (2026)'ya göre önbellekleme özellikle görseller ve veri listeleri için önemlidir. CachedNetworkImageProvider ile FutureBuilder, önbelleğe alınmış görseli otomatik olarak görüntüler ve olmadığında — indirilen dosyanın ardından bir yükleme göstergesi gösterir.

FutureBuilder vs setState: Hangisini Seçmeli

FutureBuilder ve setState aracılığıyla manuel durum yönetimi, Flutter'da asenkron UI'ya iki yaklaşımdır. Her birinin avantajları ve sınırlamaları vardır. Seçim, ekran karmaşıklığına ve asenkron işlem sayısına bağlıdır.

FutureBuilder basitlikte kazanır: yükleme durumu, veri ve hata için alan bildirmeniz gerekmez — her şey AsyncSnapshot aracılığıyla yönetilir. Tek asenkron işlemi (bir HTTP isteği, veritabanı okuma) olan basit ekranlar için idealdir. Ancak, bir ekranda 5+ asenkron işlem olduğunda, FutureBuilder aşırı iç içe geçme yaratır — sonuçta iç içe FutureBuilder'lardan oluşan bir “Piramit” oluşur.

Manuel durum bayraklarıyla setState, karmaşık mantık için daha fazla kontrol ve okunabilirlik sağlar. Birden çok bağımlı isteği olan ekranlar (kullanıcıyı yükle → siparişlerini yükle → sipariş detaylarını yükle) için ChangeNotifier veya Bloc ile setState kullanmak daha iyidir. Flutter Durum Yönetimi Kılavuzu (2026)'na göre karmaşık senaryolarda FutureBuilder yerine Riverpod veya Bloc önerilir, çünkü mantık ve sunumun daha iyi ayrıştırılmasını sağlarlar.

Ağ Verisi Yükleme ile FutureBuilder Örneği

Bir REST API'den kullanıcı listesi yüklemek için pratik bir FutureBuilder örneğini inceleyelim. Kod, AsyncSnapshot'ın üç durumunun (yükleme, hata ve hazır veri) doğru şekilde işlenmesini gösterir.

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('Kullanıcılar')),
      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('Hata: ${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());
        },
      ),
    );
  }
}

Örnekte, FutureBuilder üç durumu da işler. Hatada, hata mesajı içeren bir simge görüntülenir. Başarılı yüklemede — avatar ve isimlerle ListView. Yükleme sırasında — CircularProgressIndicator. Future bir sınıf alanı olarak bildirilir, bu da yeniden derlemede tekrarlanan çağrıyı önler. Bu desen, mobil uygulamalarda FutureBuilder kullanım senaryolarının %90'ını kapsar.