Conectar una aplicación Flutter con una API REST es solo la mitad del trabajo. La otra mitad consiste en mostrar esos datos en pantalla de forma eficiente, y para eso existe un widget diseñado específicamente para manejar operaciones asíncronas: el FutureBuilder. A continuación se explica paso a paso cómo implementarlo, construir listas dinámicas y resolver errores comunes que aparecen en el proceso.
¿Cómo funciona FutureBuilder para consumir una API?
El FutureBuilder es un widget que se construye a sí mismo en función del resultado de un Future, es decir, una operación que aún no ha terminado. Requiere dos propiedades fundamentales [0:30]:
- future: la operación asíncrona que retornará los datos. En este caso, la llamada al método
API.getPhotos().
- builder: una función que recibe el
BuildContext y un AsyncSnapshot, y devuelve el widget correspondiente según el estado de la conexión.
Para comenzar, se reemplaza el contenedor existente por un FutureBuilder. Antes de asignarle el futuro, es necesario inicializar la instancia de la API con final api = API(); e importar el archivo correspondiente en la parte superior del código [1:05].
El AsyncSnapshot es el objeto que contiene tanto el estado de la conexión como los datos recibidos. Es recomendable tipar el snapshot con el modelo que se espera recibir, por ejemplo AsyncSnapshot<List<Photo>>, para tener autocompletado y evitar errores en tiempo de ejecución [1:30].
¿Cómo manejar los estados de conexión?
Dentro del builder, se evalúan las propiedades del snapshot para decidir qué mostrar [2:00]:
- Si
snapshot.hasData es verdadero y snapshot.connectionState == ConnectionState.done, significa que la petición terminó con éxito y los datos están disponibles.
- En caso contrario, se retorna un CircularProgressIndicator envuelto en un
Center, que muestra una animación de carga mientras la petición se completa.
Este patrón permite que el usuario vea retroalimentación visual inmediata en lugar de una pantalla vacía.
¿Qué es ListView.builder y por qué usarlo?
Cuando los datos están listos, se construye un ListView.builder [2:50]. Este widget genera elementos de lista bajo demanda, lo que lo hace eficiente para listas largas. Requiere dos propiedades principales:
- itemCount: la cantidad total de elementos, que se obtiene con
snapshot.data!.length.
- itemBuilder: una función que recibe el contexto y un index, y retorna el widget para cada elemento.
¿Cómo construir cada elemento de la lista con Card y ListTile?
Dentro del itemBuilder se utiliza un Card como contenedor visual, y dentro de él un ListTile para organizar la información de forma estructurada [3:40].
Para el title se accede a snapshot.data![index].id. Aquí aparece un error común: el id es de tipo int, pero el widget Text espera un String. La solución es sencilla gracias a que en Dart todo es un objeto, por lo que basta con llamar .toString() para convertir el valor [4:20].
Para mostrar la imagen se usa la propiedad leading del ListTile con un CircularAvatar [5:10]:
- Se define un
radius de 30.
- Se asigna
backgroundImage con un NetworkImage que toma la URL desde snapshot.data![index].url.
Para el subtitle se emplea interpolación de strings para mostrar información adicional como el albumId [5:50]:
dart
Text('Descripción del álbum ${snapshot.data![index].albumId}')
Al ejecutar la aplicación, se observan las imágenes a la izquierda, el ID como título y la descripción del álbum debajo. Los primeros elementos pertenecen al álbum uno, y al hacer scroll hacia abajo el albumId cambia, reflejando la estructura del JSON original [6:20].
¿Por qué FutureBuilder es mejor que onInit para peticiones API?
Otra alternativa es usar el método onInit para ejecutar la petición durante la inicialización de la pantalla y luego construir los widgets cuando los datos estén disponibles [6:50]. Sin embargo, este enfoque presenta desventajas:
- La pantalla permanece vacía hasta que la petición termine.
- No ofrece un mecanismo integrado para mostrar estados de carga.
- El código resulta menos limpio y menos óptimo.
Con FutureBuilder, la carga se muestra desde el primer momento, la construcción de widgets es reactiva y el resultado es una experiencia de usuario más fluida. Si estás trabajando con datos provenientes de una API REST en Flutter, este widget es la herramienta indicada.
¿Ya implementaste FutureBuilder en algún proyecto? Comparte tu experiencia o dudas en los comentarios.
