FutureBuilder — cos’è, lavorare con Future in Flutter

Cos’è FutureBuilder in Flutter

FutureBuilder è un widget integrato di Flutter del pacchetto widgets che prende un Future e una funzione builder. Quando lo stato del Future cambia (in esecuzione, completato con dati, completato con errore), FutureBuilder ricostruisce automaticamente l’interfaccia chiamando il builder con un nuovo AsyncSnapshot. Questo elimina la necessità di gestire manualmente lo stato di caricamento tramite setState e flag.

A differenza di StreamBuilder, che lavora con flussi di dati (Stream), FutureBuilder è progettato per operazioni asincrone singole: richiesta HTTP, lettura file, query database. FutureBuilder gestisce autonomamente la sottoscrizione al Future: al primo build, avvia il Future e ne traccia il completamento. Quando il widget viene distrutto, FutureBuilder non cancella il Future — questa è responsabilità dello sviluppatore.

Secondo il Flutter Cookbook (2026), FutureBuilder è raccomandato per i casi in cui un’operazione asincrona viene eseguita una volta all’inizializzazione dello schermo. Per operazioni ricorrenti o flussi di dati, usate StreamBuilder. Entrambi i widget seguono lo stesso pattern di UI Reattiva, ma FutureBuilder è ottimizzato per richieste singole.

Come funziona FutureBuilder internamente

L’implementazione interna di FutureBuilder si sottoscrive al Future usando Future.then e catchError. All’avvio, FutureBuilder imposta connectionState su ConnectionState.waiting e chiama il builder con dati vuoti. Al completamento con successo, connectionState passa a ConnectionState.done con i dati. In caso di errore, snapshot.error viene riempito con l’oggetto errore. Ogni cambiamento attiva una ricostruzione del widget.

AsyncSnapshot: stati e proprietà

AsyncSnapshot è un oggetto contenitore che FutureBuilder passa alla funzione builder ad ogni cambiamento di stato. Contiene tutte le informazioni sullo stato corrente dell’operazione asincrona: se il caricamento è in corso, quali dati sono stati ricevuti o se si è verificato un errore. Comprendere AsyncSnapshot è la chiave per costruire correttamente l’interfaccia con FutureBuilder.

ConnectionState: quattro stati di un’operazione asincrona

L’enum ConnectionState definisce la fase di un’operazione asincrona. None — stato iniziale quando il Future non è ancora stato avviato (usato raramente, tipicamente al primo build senza initialData). Waiting — il Future è in esecuzione, dati non ancora ricevuti. Active — usato solo da StreamBuilder per stream con dati parziali. Done — il Future è completato, i dati sono disponibili tramite snapshot.data o l’errore tramite snapshot.error.

La corretta gestione di tutti gli stati di AsyncSnapshot nella funzione builder è un requisito obbligatorio per il codice di produzione. Se non gestite lo stato waiting, l’utente vedrà una schermata vuota durante il caricamento. Se non gestite hasError, l’utente riceverà un’Eccezione senza spiegazione. Il pattern raccomandato: verificare hasError → verificare hasData → mostrare caricamento per default.

Pattern di utilizzo di FutureBuilder

FutureBuilder può essere usato in diversi pattern standard, ciascuno che risolve un compito specifico. Esaminiamo gli scenari principali: caricamento dati all’inizializzazione, caricamento con cache, richieste parallele e gestione errori con ripetizione.

Caricamento dati all’inizializzazione dello schermo

Il pattern più comune — FutureBuilder nel metodo build di un StatefulWidget o StatelessWidget. Il Future viene passato da initState o creato direttamente in build. È importante non creare il Future nel metodo build ad ogni ricostruzione — questo porterà a richieste ripetute. Usate un Future memorizzato in un campo dello State.

Caricamento con cache e aggiornamento

Per evitare richieste ripetute, FutureBuilder può essere combinato con CachedNetworkImage o una cache locale. Dopo il primo caricamento, i dati vengono salvati in memoria o SharedPreferences, e FutureBuilder mostra i dati in cache istantaneamente mentre li aggiorna dalla rete in parallelo. Questo migliora l’esperienza utente grazie a una risposta immediata.

Secondo pub.dev (2026), la cache è particolarmente rilevante per immagini e liste di dati. FutureBuilder con CachedNetworkImageProvider mostra automaticamente un’immagine in cache e, in sua assenza — un indicatore di caricamento seguito dal file scaricato.

FutureBuilder vs setState: cosa scegliere

FutureBuilder e la gestione manuale dello stato tramite setState sono due approcci all’interfaccia asincrona in Flutter. Ciascuno ha i propri vantaggi e limiti. La scelta dipende dalla complessità dello schermo e dal numero di operazioni asincrone.

FutureBuilder vince in semplicità: non è necessario dichiarare campi per lo stato di caricamento, dati ed errore — tutto è gestito tramite AsyncSnapshot. È ideale per schermi semplici con una operazione asincrona (una richiesta HTTP, lettura database). Tuttavia, con 5+ operazioni asincrone su uno schermo, FutureBuilder crea un annidamento eccessivo — risultando in una “Piramide” di FutureBuilder annidati.

setState con flag di stato manuali dà più controllo e leggibilità per logiche complesse. Per schermi con molte richieste dipendenti (caricare utente → caricare suoi ordini → caricare dettagli ordine), è meglio usare setState con ChangeNotifier o Bloc. Secondo la Guida alla Gestione dello Stato di Flutter (2026), per scenari complessi si raccomanda Riverpod o Bloc invece di FutureBuilder, poiché forniscono una migliore separazione tra logica e presentazione.

Esempio FutureBuilder con caricamento dati di rete

Consideriamo un esempio pratico di FutureBuilder per caricare una lista di utenti da un’API REST. Il codice dimostra la corretta gestione di tutti e tre gli stati di AsyncSnapshot: caricamento, errore e dati pronti.

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

Nell’esempio, FutureBuilder gestisce tutti e tre gli stati. In caso di errore, viene mostrata un’icona con un messaggio di errore. In caso di caricamento riuscito — una ListView con avatar e nomi. Durante il caricamento — un CircularProgressIndicator. Il Future è dichiarato come campo di classe, impedendo chiamate ripetute durante la ricostruzione. Questo pattern copre il 90% degli scenari di utilizzo di FutureBuilder nelle app mobili.