Flutter本地数据存储插件local_value的使用

Flutter应用开发中，数据持久化是必不可少的一环。无论是保存用户偏好设置、缓存网络请求结果还是保存应用程序状态，都离不开对本地数据的操作。local_value 是一个用于Flutter项目的本地数据存储插件，它提供了简单且类型安全的方式来读取、写入和删除本地数据。下面将详细介绍如何使用这个插件，并提供完整的示例代码。

Quickstart 快速开始

单例模式保存

// 保存单个值到本地
final localCounterValue = LocalSingleton<int>(id: 'counter_val');
await localCounterValue.write(5);
print(await localCounterValue.read()); // 输出：5

多对象保存

// 保存多个相关对象
final localUserScores = LocalValue<int>(basePath: ['user_scores']);
await localUserScores.write('user_1', 15); 
await localUserScores.write('user_2', 24);

print(await localUserScores.read('user_1')); // 输出：15
print(await localUserScores.read('user_2')); // 输出：24

Features 功能特性

• 支持保存/加载/删除单例到本地存储。
• 可以指定文档类型为应用文档、临时文档、支持文件或共享偏好设置。具体区别可以参考 path_provider 文档。
• Web平台使用 shared_preferences 实现后台存储，因为Web端没有文件系统的概念。

文档类型说明

• DocumentType.document: 用户生成的数据，无法重新创建（例如：本地游戏中的最高分）。
• DocumentType.support: 非用户生成的数据，无法重新创建（例如：自动配置文件）。
• DocumentType.temporary: 可以随时清除的数据（例如：缓存下载的JSON）。
• DocumentType.secure: 必须安全存储的数据（例如：用户的API密钥）。
• DocumentType.prefs: 用户偏好设置（例如：是否以浅色模式打开应用）。

Use cases 使用场景

登录用户信息保存

class CurrentUser {
    final int id;
    final String name;
    final Color favoriteColor;

    // 添加 toJson 和 fromJson 方法
}

final locallyPersistedUser = localSingleton<CurrentUser>(
      id: 'current_user',
      fromJson: CurrentUser.fromJson,
      toJson: (currentUser) => currentUser.toJson());

// 保存和加载用户信息
CurrentUser? myCurrentUser = await locallyPersistedUser.read();
await locallyPersistedUser.write(someUser);

缓存避免重复网络请求

final localUsers = LocalValue<User>(toJson: ..., fromJson: ...);
await localUsers.read(userOneId);
await localUsers.write(userTwoId, userTwo);

类型安全地保存偏好设置

final isDarkMode = LocalSingleton<bool>(documentType: DocumentType.prefs, id: 'isDarkMode');
await isDarkMode.write(true);
final darkMode = await isDarkMode.read() ?? false;

LocalValue vs LocalSingleton

该包暴露了 LocalValue 和 LocalSingleton 两个类。它们具有非常相似的API，但有一个关键区别：LocalSingleton 总是保存到同一个文件中，适用于只需要存储一个值的情况，如当前用户的数据；而 LocalValue 则需要在读取、写入和删除时提供一个 id 参数，适合存储多个用户的数据。

Usage 示例用法

创建并操作本地存储对象

import 'package:local_value/local_value.dart';

class CounterObj {
  int value;
  CounterObj(this.value);
}

// 创建本地存储实例
final counterFile = localSingleton<CounterObj>(
  documentType: DocumentType.document,
  id: 'counter',
  fromJson: (counterJson) => CounterObj(counterJson['value'] as int),
  toJson: (counterObj) => {'value': counterObj.value}
);

// 从本地读取
CounterObj? myCurrentCounter = await counterFile.read();

// 写入本地
await counterFile.write(myCurrentCounter ?? CounterObj(8));

// 清除本地存储
await counterFile.clear();

完整示例Demo

以下是一个完整的Flutter项目示例，展示了如何结合 local_value 插件实现计数器功能，并将计数结果保存到本地。

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

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  final counterStorage = LocalSingleton<int>(id: 'counter');

  MyHomePage({Key? key}) : super(key: key);

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

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

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Local Data Manager Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline4,
            ),
          ],
        ),
      ),
      floatingActionButtonLocation: FloatingActionButtonLocation.centerDocked,
      floatingActionButton: Builder(
        builder: (context) => Row(
          mainAxisSize: MainAxisSize.max,
          mainAxisAlignment: MainAxisAlignment.spaceEvenly,
          children: [
            FloatingActionButton(
              onPressed: () async {
                final value = await widget.counterStorage.read();
                if (value == null) {
                  ScaffoldMessenger.of(context).showSnackBar(
                    const SnackBar(content: Text('no local data saved')),
                  );
                  return;
                }
                setState(() {
                  _counter = value;
                });
              },
              backgroundColor: Colors.orange,
              child: const Icon(Icons.replay),
            ),
            FloatingActionButton(
              onPressed: () async {
                await widget.counterStorage.write(_counter);
                ScaffoldMessenger.of(context).showSnackBar(
                  const SnackBar(content: Text('saved!')),
                );
              },
              backgroundColor: Colors.green,
              child: const Icon(Icons.save),
            ),
            FloatingActionButton(
              onPressed: _incrementCounter,
              child: const Icon(Icons.add),
            ),
          ],
        ),
      ),
    );
  }
}

此示例创建了一个简单的计数器应用，用户可以通过点击按钮增加计数器的值，并可以选择保存当前计数值到本地或者从本地恢复计数值。通过这种方式，即使应用程序关闭后重新启动，也可以保留之前的计数状态。

Additional information 其他信息

如果您在使用过程中遇到任何问题，请前往GitHub提交Issue。作者正在积极维护这个包，并欢迎提出功能需求。由于该包基于两个经过充分测试的底层库 (shared_preferences 和 path_provider) 构建，因此整体稳定性较高。