FutureBuilder — mi ez, munka a Future-rel Flutter-ben

Mi az a FutureBuilder a Flutter-ben

FutureBuilder — egy beépített Flutter widget a widgets csomagból, amely Future<T>-t és egy builder függvényt fogad. Amikor a Future állapota megváltozik (fut, adatokkal befejeződött, hibával befejeződött), a FutureBuilder automatikusan átépíti az UI-t, meghívva a buildert az új AsyncSnapshot-tal. Ez kiküszöböli a betöltési állapot manuális kezelésének szükségességét setState és zászlók segítségével.

Ellentétben a StreamBuilder-rel, amely adatfolyamokkal (Stream) dolgozik, a FutureBuilder egyszeri aszinkron műveletekre készült: HTTP-kérés, fájlból olvasás, adatbázis-lekérdezés. A FutureBuilder maga kezeli a Future-re való feliratkozást: az első felépítéskor elindítja a Future-t és követi annak befejezését. A widget megsemmisítésekor a FutureBuilder nem szakítja meg a Future-t — ez a fejlesztő felelőssége.

A Flutter Cookbook (2026) szerint a FutureBuilder olyan esetekben ajánlott, amikor az aszinkron művelet egyszer fut le a képernyő inicializálásakor. Ismétlődő műveletekhez vagy adatfolyamokhoz használja a StreamBuilder-t. Mindkét widget ugyanazt a Reactive UI mintát követi, de a FutureBuilder az egyszeri kérésekre van optimalizálva.

Hogyan működik a FutureBuilder a motorháztető alatt

A FutureBuilder belső implementációja a Future.then és catchError segítségével iratkozik fel a Future-re. Indításkor a FutureBuilder a connectionState-t ConnectionState.waiting-re állítja, és meghívja a buildert üres adatokkal. Sikeres befejezéskor a connectionState ConnectionState.done-ra változik adatokkal. Hiba esetén a snapshot.error feltöltésre kerül a hiba objektummal. Minden változás kiváltja a widget átépítését.

AsyncSnapshot: állapotok és tulajdonságok

AsyncSnapshot — egy konténer objektum, amelyet a FutureBuilder minden állapotváltozáskor átad a builder függvénynek. Tartalmazza az aszinkron művelet aktuális állapotával kapcsolatos összes információt: folyamatban van-e a betöltés, milyen adatok érkeztek, történt-e hiba. Az AsyncSnapshot megértése a kulcs a FutureBuilder-rel való helyes UI-építéshez.

ConnectionState: az aszinkron művelet négy állapota

Az enum ConnectionState határozza meg az aszinkron művelet fázisát. None — kezdeti állapot, amikor a Future még nem indult el (ritkán használt, általában az első felépítéskor initialData nélkül). Waiting — a Future fut, az adatok még nem érkeztek meg. Active — csak a StreamBuilder használja részleges adatokat tartalmazó adatfolyamokhoz. Done — a Future befejeződött, az adatok elérhetők a snapshot.data vagy a hiba a snapshot.error segítségével.

Az AsyncSnapshot összes állapotának helyes kezelése a builder függvényben kötelező követelmény a production kódban. Ha nem kezeli a waiting állapotot, a felhasználó üres képernyőt lát a betöltés során. Ha nem kezeli a hasError-t, a felhasználó magyarázat nélküli Exception-t kap. Ajánlott minta: hasError ellenőrzése → hasData ellenőrzése → alapértelmezés szerint betöltés jelzése.

A FutureBuilder használati mintái

FutureBuilder több standard mintában használható, amelyek mindegyike egy adott feladatot old meg. Tekintsük át a fő forgatókönyveket: adatok betöltése inicializáláskor, betöltés gyorsítótárazással, párhuzamos kérések és hibakezelés újrapróbálkozással.

Adatok betöltése a képernyő inicializálásakor

A leggyakoribb minta — FutureBuilder a StatefulWidget vagy StatelessWidget build metódusában. A Future az initState-ből kerül átadásra vagy közvetlenül a build-ben jön létre. Fontos, hogy ne hozzon létre Future-t a build metódusban minden átépítéskor — ez ismétlődő kérésekhez vezet. Használja a State mezőjében tárolt Future-t.

Betöltés gyorsítótárazással és frissítéssel

Az ismétlődő kérések megelőzése érdekében a FutureBuilder kombinálható a CachedNetworkImage-val vagy helyi gyorsítótárral. Az első betöltés után az adatok memóriában vagy SharedPreferences-ben kerülnek tárolásra, és a FutureBuilder azonnal megjeleníti a gyorsítótárazott adatokat, miközben párhuzamosan frissíti azokat a hálózatról. Ez az azonnali válasz által javítja az UX-et.

A pub.dev (2026) szerint a gyorsítótárazás különösen releváns a képek és adatlisták esetében. A FutureBuilder a CachedNetworkImageProvider-rel automatikusan megjeleníti a gyorsítótárazott képet, hiányában pedig betöltési jelzőt a letöltött fájl későbbi megjelenítésével.

FutureBuilder vs setState: melyiket válasszuk

FutureBuilder és a manuális állapotkezelés setState segítségével — két megközelítés az aszinkron UI-hoz Flutter-ben. Mindegyiknek megvannak a maga előnyei és korlátai. A választás a képernyő összetettségétől és az aszinkron műveletek számától függ.

FutureBuilder az egyszerűségében győz: nem kell mezőket deklarálni a betöltési állapothoz, adatokhoz és hibához — mindent az AsyncSnapshot kezel. Ideális egyszerű képernyőkhöz egy aszinkron művelettel (egy HTTP-kérés, adatbázis olvasás). Azonban 5+ aszinkron művelet esetén egy képernyőn a FutureBuilder túlzott egymásba ágyazást hoz létre — „piramis" alakul ki az egymásba ágyazott FutureBuilder-ekből.

setState manuális állapotjelzőkkel több irányítást és olvashatóságot biztosít összetett logika esetén. Több függő kéréssel rendelkező képernyők esetén (felhasználó betöltése → rendeléseinek betöltése → rendelés részleteinek betöltése) jobb a setState használata ChangeNotifier-rel vagy Bloc-kal. A Flutter State Management Guide (2026) szerint összetett forgatókönyvek esetén a FutureBuilder helyett a Riverpod vagy Bloc használata ajánlott, mivel ezek jobb logikai és prezentációs szétválasztást biztosítanak.

FutureBuilder példa adatok betöltésével hálózatról

Tekintsünk egy gyakorlati példát a FutureBuilder használatára felhasználói lista betöltéséhez REST API-ból. A kód bemutatja az AsyncSnapshot mindhárom állapotának helyes kezelését: betöltés, hiba és kész adatok.

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());
        },
      ),
    );
  }
}

A példában a FutureBuilder mindhárom állapotot kezeli. Hiba esetén egy ikon jelenik meg a hibaüzenettel. Sikeres betöltéskor — ListView avatárokkal és nevekkel. Betöltés közben — CircularProgressIndicator. A Future osztálymezőként van deklarálva, ami megakadályozza az ismételt meghívást átépítéskor. Ez a minta lefedi a FutureBuilder használati eseteinek 90%-át mobilalkalmazásokban.