Almacenar datos clave-valor en el disco

Aprende cómo usar el paquete shared_preferences para almacenar datos de clave-valor.

Si tienes una colección relativamente pequeña de clave-valor para guardar, puedes usar el plugin shared_preferences.

Normalmente, tendrías que escribir integraciones nativas de la plataforma para almacenar datos en cada plataforma. Afortunadamente, el plugin shared_preferences se puede utilizar para persistir datos de clave-valor en el disco en cada plataforma que soporta Flutter.

Esta receta utiliza los siguientes pasos:

Agregar la dependencia.
Guardar datos.
Leer datos.
Eliminar datos.

Antes de comenzar, agrega el paquete shared_preferences como dependencia.

Para agregar el paquete shared_preferences como dependencia, ejecuta flutter pub add:

flutter pub add shared_preferences

Para persistir los datos, utiliza los métodos setter proporcionados por la clase SharedPreferences. Los métodos setter están disponibles para varios tipos primitivos, como setInt, setBool, y setString.

Los métodos setter hacen dos cosas: primero, actualizan de forma síncrona el par clave-valor en memoria. Luego, persisten los datos en el disco.

dart

// Load and obtain the shared preferences for this app.
final prefs = await SharedPreferences.getInstance();

// Save the counter value to persistent storage under the 'counter' key.
await prefs.setInt('counter', counter);

Para leer datos, utiliza el método getter adecuado proporcionado por la clase SharedPreferences. Para cada setter hay un getter correspondiente. Por ejemplo, puedes usar los métodos getInt, getBool, y getString.

dart

final prefs = await SharedPreferences.getInstance();

// Try reading the counter value from persistent storage.
// If not present, null is returned, so default to 0.
final counter = prefs.getInt('counter') ?? 0;

Ten en cuenta que los métodos getter lanzan una excepción si el valor persistido tiene un tipo diferente al que espera el método getter.

Para eliminar datos, utiliza el método remove().

dart

final prefs = await SharedPreferences.getInstance();

// Remove the counter key-value pair from persistent storage.
await prefs.remove('counter');

Aunque el almacenamiento de clave-valor proporcionado por shared_preferences es fácil y conveniente de usar, tiene limitaciones:

Solo se pueden utilizar tipos primitivos: int, double, bool, String, y List<String>.
No está diseñado para almacenar grandes cantidades de datos.
No hay garantía de que los datos persistan entre reinicios de la aplicación.

Es una buena idea probar el código que persiste datos utilizando shared_preferences. Para habilitar esto, el paquete proporciona una implementación simulada (mock) en memoria del almacén de preferencias.

Para configurar tus pruebas para usar la implementación simulada (mock), llama al método estático setMockInitialValues en un método setUpAll() en tus archivos de prueba. Pasa un mapa de pares clave-valor para usar como los valores iniciales.

dart

SharedPreferences.setMockInitialValues(<String, Object>{'counter': 2});

dart

import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      title: 'Shared preferences demo',
      home: MyHomePage(title: 'Shared preferences demo'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;

  @override
  void initState() {
    super.initState();
    _loadCounter();
  }

  /// Load the initial counter value from persistent storage on start,
  /// or fallback to 0 if it doesn't exist.
  Future<void> _loadCounter() async {
    final prefs = await SharedPreferences.getInstance();
    setState(() {
      _counter = prefs.getInt('counter') ?? 0;
    });
  }

  /// After a click, increment the counter state and
  /// asynchronously save it to persistent storage.
  Future<void> _incrementCounter() async {
    final prefs = await SharedPreferences.getInstance();
    setState(() {
      _counter = (prefs.getInt('counter') ?? 0) + 1;
      prefs.setInt('counter', _counter);
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text(widget.title)),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Text('You have pushed the button this many times: '),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

¿Te resultó útil el contenido de esta página?

A menos que se indique lo contrario, la documentación de este sitio refleja Flutter 3.44.0. Página actualizada por última vez el 2026-05-05. Ver código fuente oreportar un problema.

Almacenar datos clave-valor en el disco

1. Agregar la dependencia

2. Guardar datos

3. Leer datos

4. Eliminar datos

Tipos soportados

Soporte para pruebas

Ejemplo completo