FutureBuilder — apa itu, bekerja dengan Future di Flutter

Apa itu FutureBuilder di Flutter

FutureBuilder — adalah widget bawaan Flutter dari paket widgets yang menerima Future<T> dan fungsi builder. Ketika status Future berubah (sedang berjalan, selesai dengan data, selesai dengan error) FutureBuilder secara otomatis membangun ulang UI dengan memanggil builder dengan AsyncSnapshot baru. Ini menghilangkan kebutuhan untuk mengelola status pemuatan secara manual melalui setState dan flag.

Tidak seperti StreamBuilder yang bekerja dengan aliran data (Stream), FutureBuilder dirancang untuk operasi asinkron satu kali: permintaan HTTP, membaca dari file, kueri database. FutureBuilder mengelola sendiri langganan ke Future: pada pembangunan pertama ia menjalankan Future dan melacak penyelesaiannya. Saat widget dihancurkan, FutureBuilder tidak membatalkan Future — ini adalah tanggung jawab pengembang.

Menurut Flutter Cookbook (2026), FutureBuilder direkomendasikan untuk kasus di mana operasi asinkron dijalankan sekali saat inisialisasi layar. Untuk operasi berulang atau aliran data, gunakan StreamBuilder. Kedua widget mengikuti pola Reactive UI yang sama, tetapi FutureBuilder dioptimalkan untuk permintaan satu kali.

Bagaimana FutureBuilder bekerja di balik layar

Implementasi internal FutureBuilder berlangganan ke Future melalui Future.then dan catchError. Saat dimulai, FutureBuilder mengatur connectionState ke ConnectionState.waiting dan memanggil builder dengan data kosong. Saat berhasil, connectionState berubah menjadi ConnectionState.done dengan data. Saat error, snapshot.error diisi dengan objek error. Setiap perubahan memicu pembangunan ulang widget.

AsyncSnapshot: status dan properti

AsyncSnapshot — adalah objek wadah yang diteruskan FutureBuilder ke fungsi builder pada setiap perubahan status. Ini berisi semua informasi tentang status terkini operasi asinkron: apakah pemuatan sedang berlangsung, data apa yang diterima, apakah terjadi error. Memahami AsyncSnapshot adalah kunci untuk membangun UI dengan FutureBuilder dengan benar.

ConnectionState: empat status operasi asinkron

Enum ConnectionState menentukan tahap operasi asinkron. None — status awal ketika Future belum dijalankan (jarang digunakan, biasanya saat pembangunan pertama tanpa initialData). Waiting — Future sedang berjalan, data belum diterima. Active — hanya digunakan oleh StreamBuilder untuk stream dengan data parsial. Done — Future selesai, data tersedia melalui snapshot.data atau error melalui snapshot.error.

Penanganan yang benar dari semua status AsyncSnapshot dalam fungsi builder adalah persyaratan wajib untuk kode produksi. Jika Anda tidak menangani status waiting, pengguna akan melihat layar kosong selama pemuatan. Jika Anda tidak menangani hasError, pengguna akan mendapatkan Exception tanpa penjelasan. Pola yang direkomendasikan: periksa hasError → periksa hasData → default tampilkan pemuatan.

Pola penggunaan FutureBuilder

FutureBuilder dapat digunakan dalam beberapa pola standar, masing-masing memecahkan tugas tertentu. Mari kita lihat skenario utama: memuat data saat inisialisasi, memuat dengan cache, permintaan paralel, dan penanganan error dengan pengulangan.

Memuat data saat inisialisasi layar

Pola paling umum — FutureBuilder dalam metode build StatefulWidget atau StatelessWidget. Future diteruskan dari initState atau dibuat langsung di build. Penting untuk tidak membuat Future dalam metode build setiap kali pembangunan ulang — ini menyebabkan permintaan berulang. Gunakan Future yang disimpan di bidang State.

Memuat dengan cache dan penyegaran

Untuk mencegah permintaan berulang, FutureBuilder dapat dikombinasikan dengan CachedNetworkImage atau cache lokal. Setelah pemuatan pertama, data disimpan di memori atau SharedPreferences, dan FutureBuilder menampilkan data cache secara instan, sambil memperbaruinya secara paralel dari jaringan. Ini meningkatkan UX dengan respons instan.

Menurut pub.dev (2026), caching sangat relevan untuk gambar dan daftar data. FutureBuilder dengan CachedNetworkImageProvider secara otomatis menampilkan gambar yang di-cache, dan jika tidak ada — indikator pemuatan dengan tampilan file yang diunduh selanjutnya.

FutureBuilder vs setState: mana yang dipilih

FutureBuilder dan manajemen status manual melalui setState — dua pendekatan untuk UI asinkron di Flutter. Masing-masing memiliki kelebihan dan keterbatasan. Pilihan tergantung pada kompleksitas layar dan jumlah operasi asinkron.

FutureBuilder unggul dalam kesederhanaan: tidak perlu mendeklarasikan bidang untuk status pemuatan, data, dan error — semuanya dikelola melalui AsyncSnapshot. Ini ideal untuk layar sederhana dengan satu operasi asinkron (satu permintaan HTTP, membaca database). Namun, dengan 5+ operasi asinkron pada satu layar, FutureBuilder menciptakan sarang yang berlebihan — terbentuk “piramida” dari FutureBuilder bersarang.

setState dengan flag status manual memberikan lebih banyak kontrol dan keterbacaan dalam logika kompleks. Untuk layar dengan banyak permintaan dependen (memuat pengguna → memuat pesanannya → memuat detail pesanan) lebih baik menggunakan setState dengan ChangeNotifier atau Bloc. Menurut Flutter State Management Guide (2026), untuk skenario kompleks disarankan menggunakan Riverpod atau Bloc daripada FutureBuilder, karena mereka memberikan pemisahan logika dan presentasi yang lebih baik.

Contoh FutureBuilder dengan pemuatan data dari jaringan

Mari kita lihat contoh praktis FutureBuilder untuk memuat daftar pengguna dari REST API. Kode ini mendemonstrasikan penanganan yang benar dari ketiga status AsyncSnapshot: pemuatan, error, dan data siap.

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('Users')),
      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('Error: ${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());
        },
      ),
    );
  }
}

Dalam contoh, FutureBuilder menangani ketiga status. Saat error, ikon dengan pesan error ditampilkan. Saat berhasil dimuat — ListView dengan avatar dan nama. Selama pemuatan — CircularProgressIndicator. Future dideklarasikan sebagai bidang kelas, yang mencegah pemanggilan ulang saat pembangunan ulang. Pola ini mencakup 90% skenario penggunaan FutureBuilder dalam aplikasi seluler.