Flutter 结合 shared_preferences 2.5.4 实现本地轻量级数据存储

在日常 Flutter 开发中,经常会遇到需要存储用户偏好设置、登录状态、简单配置项等轻量级数据的场景。这类数据无需复杂的数据库结构,但要求读写高效、跨平台兼容且接入成本低。此前我尝试过手动封装原生存储逻辑(如 Android 的 SharedPreferences、iOS 的 NSUserDefaults),但存在代码冗余、多平台适配繁琐的问题。了解到 shared_preferences 是 Flutter 生态中专门解决这类问题的官方推荐插件,而 2.5.4 版本作为稳定版,不仅修复了旧版本的异步读写缺陷,还优化了多平台存储逻辑,因此专门深入学习该版本的使用方式,旨在掌握轻量级本地存储的标准化实现方案,提升项目中数据持久化的开发效率,同时规避因缓存、跨隔离区访问导致的数据一致性问题。

Flutter 结合 shared_preferences 2.5.4 实现本地轻量级数据存储

技术背景与需求分析

  • 移动应用数据持久化的常见场景
  • shared_preferences 的定位与适用场景(轻量级键值对存储)
  • 对比其他本地存储方案(SQLite、Hive、文件存储)

shared_preferences 2.5.4 核心特性

  • 支持数据类型:int、double、bool、String、List<String>
  • 跨平台兼容性(iOS/Android/Web)
  • 同步与异步操作差异说明

环境配置与依赖集成

  • 在 pubspec.yaml 中添加依赖:

    yaml 复制代码
    dependencies:
      shared_preferences: ^2.5.4
  • 执行 flutter pub get

  • 导入库:

    dart 复制代码
    import 'package:shared_preferences/shared_preferences.dart';

基础操作实现

  • 初始化 SharedPreferences 实例:

    dart 复制代码
    final prefs = await SharedPreferences.getInstance();
  • 数据写入示例:

    dart 复制代码
    prefs.setInt('counter', 42);
    prefs.setString('username', 'FlutterUser');
  • 数据读取示例:

    dart 复制代码
    int? counter = prefs.getInt('counter');
    String? username = prefs.getString('username');
  • 删除数据与清空存储:

    dart 复制代码
    prefs.remove('counter');
    prefs.clear();

高级应用场景

  • 监听数据变化:通过 Stream 或 ValueNotifier 包装
  • 复杂对象存储:JSON 序列化与反序列化(结合 dart:convert)
  • 安全增强:敏感数据加密建议(如结合 flutter_secure_storage)

性能优化与最佳实践

  • 避免频繁调用 getInstance()
  • 批量写入使用 commit() 替代 set 方法链
  • 异常处理与空安全适配

常见问题排查

  • 数据类型不匹配导致的读取失败
  • Web 平台兼容性注意事项
  • 调试技巧:查看原生平台存储文件位置

实战案例演示

  • 用户偏好设置(主题、语言切换)
  • 应用状态持久化(登录状态、历史记录)
  • 离线缓存策略设计

版本迁移与升级指南

  • 从旧版本迁移到 2.5.4 的改动点
  • 废弃 API 替代方案

参考资料与扩展阅读

  • 官方插件文档链接
  • 社区推荐的最佳实践文章
  • 相关开源项目案例

一、shared_preferences 2.5.4 核心特性与适配说明

1.1 版本核心更新

特性 / 优化点 具体说明
API 稳定性提升 修复 2.3.x 版本中SharedPreferencesAsync异步读写的偶发阻塞问题
多平台适配完善 优化 Windows 端 AppData 目录读写权限,macOS 10.15 + 兼容性增强
缓存机制优化 SharedPreferencesWithCache的缓存刷新逻辑更高效,减少多隔离区数据不一致
迁移工具完善 提供更健壮的旧版 API 向新版异步 API 迁移工具,降低数据丢失风险

1.2 平台存储位置与支持类型

(1)各平台存储路径
平台 SharedPreferences(旧版) SharedPreferencesAsync/WithCache(新版)
Android 系统 SharedPreferences(xml 文件) DataStore Preferences(默认)/SharedPreferences
iOS/macOS NSUserDefaults NSUserDefaults
Linux XDG_DATA_HOME 目录下的键值文件 XDG_DATA_HOME 目录下的键值文件
Web 浏览器 LocalStorage 浏览器 LocalStorage
Windows 系统漫游 AppData 目录 系统漫游 AppData 目录
(2)支持的数据类型

该版本仅支持以下基础数据类型,不支持自定义对象(需序列化后以 String 存储):int、double、bool、String、List<String>

二、核心 API 分类与使用场景

2.5.4 版本提供三类核心 API,适配不同的开发场景,开发者可根据性能、数据一致性需求选择:

API 类型 核心特点 适用场景 性能 数据一致性
SharedPreferences(旧版) 带本地缓存,同步 get / 异步 set,未来将废弃 简单场景、低频次读写、无需跨隔离区访问 高 较低
SharedPreferencesAsync 无缓存,全异步读写,直接访问原生存储 多隔离区 / 多引擎实例、跨端数据同步场景 中 高
SharedPreferencesWithCache 带可控缓存,同步 get / 异步 set,可配置白名单 高频次读操作、需平衡性能与数据一致性场景 高 中

三、实操案例:不同 API 的使用方式

3.1 基础配置

首先在pubspec.yaml中引入依赖:

复制代码
dependencies:
  flutter:
    sdk: flutter
  shared_preferences: 2.5.4
  # 如需Android端指定SharedPreferences后端,需额外引入
  # shared_preferences_android: ^2.2.0

3.2 旧版 SharedPreferences(兼容使用)

适合快速实现简单存储,注意该 API 未来将废弃,新工程建议使用新版:

复制代码
import 'package:shared_preferences/shared_preferences.dart';

// 写入数据
Future<void> saveUserData() async {
  // 获取实例(异步)
  final SharedPreferences prefs = await SharedPreferences.getInstance();
  // 写入不同类型数据
  await prefs.setInt('user_age', 25);
  await prefs.setBool('is_login', true);
  await prefs.setString('user_name', 'FlutterDev');
  await prefs.setStringList('hobbies', ['coding', 'reading', 'running']);
}

// 读取数据
Future<void> readUserData() async {
  final SharedPreferences prefs = await SharedPreferences.getInstance();
  // 同步读取,无数据返回null
  final int? age = prefs.getInt('user_age');
  final bool? isLogin = prefs.getBool('is_login');
  final String? name = prefs.getString('user_name');
  final List<String>? hobbies = prefs.getStringList('hobbies');
  
  print('用户名:$name,年龄:$age,是否登录:$isLogin');
}

// 删除数据
Future<void> removeData() async {
  final SharedPreferences prefs = await SharedPreferences.getInstance();
  await prefs.remove('user_age'); // 删除指定键
  // await prefs.clear(); // 清空所有数据
}

3.3 新版 SharedPreferencesAsync(推荐)

无缓存设计,保证数据一致性,适合多场景数据读写:

复制代码
import 'package:shared_preferences/shared_preferences.dart';

// 初始化异步实例
final SharedPreferencesAsync asyncPrefs = SharedPreferencesAsync();

// 写入数据
Future<void> saveDataAsync() async {
  await asyncPrefs.setDouble('score', 98.5);
  await asyncPrefs.setString('token', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
}

// 读取数据
Future<void> readDataAsync() async {
  final double? score = await asyncPrefs.getDouble('score');
  final String? token = await asyncPrefs.getString('token');
  print('分数:$score,Token:$token');
}

// 清空数据(指定白名单,仅删除白名单外数据)
Future<void> clearDataAsync() async {
  await asyncPrefs.clear(allowList: {'token'}); // 保留token键
}

3.4 SharedPreferencesWithCache(高性能读写)

带缓存的新版 API,适合高频读场景,可配置白名单限制可操作的键:

复制代码
import 'package:shared_preferences/shared_preferences.dart';

// 创建带缓存的实例,指定白名单
Future<void> initCachePrefs() async {
  final SharedPreferencesWithCache prefsWithCache = await SharedPreferencesWithCache.create(
    cacheOptions: const SharedPreferencesWithCacheOptions(
      allowList: {'theme_mode', 'font_size'}, // 仅允许操作这两个键
    ),
  );
  
  // 写入数据
  await prefsWithCache.setInt('font_size', 16);
  await prefsWithCache.setBool('theme_mode', true);
  
  // 同步读取缓存数据
  final int? fontSize = prefsWithCache.getInt('font_size');
  print('字体大小:$fontSize');
  
  // 清空数据(白名单已配置,无需重复传)
  await prefsWithCache.clear();
}

3.5 旧版迁移到新版 API

2.5.4 版本提供了便捷的迁移工具,确保旧版数据无缝迁移到新版异步 API:

复制代码
import 'package:shared_preferences/shared_preferences.dart';
import 'package:shared_preferences/util/legacy_to_async_migration_util.dart';

Future<void> migrateData() async {
  // 获取旧版实例
  final SharedPreferences legacyPrefs = await SharedPreferences.getInstance();
  // 执行迁移(仅首次执行,通过migrationCompletedKey标记)
  await migrateLegacySharedPreferencesToSharedPreferencesAsyncIfNecessary(
    legacySharedPreferencesInstance: legacyPrefs,
    sharedPreferencesAsyncOptions: const SharedPreferencesOptions(),
    migrationCompletedKey: 'migration_completed_2025', // 自定义标记键
  );
}

四、注意事项

  1. 数据安全性:该插件仅适用于非敏感数据存储(如用户偏好设置、简单配置),密码、token 等敏感数据需加密后再存储;
  2. 跨隔离区使用 :若在多隔离区中使用带缓存的 API,需在读取前调用reload()刷新缓存,避免数据不一致;
  3. Android 后端选择 :如需兼容原生 Android 的 SharedPreferences 数据,需通过SharedPreferencesAsyncAndroidOptions指定后端类型;
  4. 数据量限制:适合存储 KB 级别的小数据,大量数据建议使用 Hive、SQFlite 等数据库。

五、总结

shared_preferences 2.5.4 版本通过三类差异化 API,满足了 Flutter 开发者在不同场景下的本地轻量级存储需求。新版异步 API(SharedPreferencesAsync/WithCache)解决了旧版缓存导致的数据一致性问题,同时保持了易用性;旧版 API 则可作为过渡方案。开发者可根据项目的性能、一致性需求选择合适的 API,结合平台特性做好适配,高效实现本地数据持久化。

欢迎大家加入开源鸿蒙跨平台开发者社区(https://openharmonycrossplatform.csdn.net),一起共建开源鸿蒙跨平台生态。

相关推荐
SoaringHeart14 小时前
Flutter最佳实践:用 flutter_html 渲染富文本
前端·flutter
恋猫de小郭1 天前
Flutter 3.50.0 Release 的第一个崩溃,修好了,还没 hotfix
android·前端·flutter
程序员老刘2 天前
跨平台开发地图 | 2026年11月
flutter·ai编程·客户端
传奇开心果编程2 天前
【Flutter踩坑排雷】第30课:异常未捕获坑|未捕获异常直接闪退,全局兜底故障处理
android·flutter·ios·移动开发·dart·ui框架·声明式ui
恋猫de小郭2 天前
Flutter Native Interop 稳定了,Platform Channel 要退场了
android·前端·flutter
好的佩奇3 天前
Dart 之可迭代对象与生成器
android·flutter·dart
恋猫de小郭3 天前
Flutter Analyzer 系列坑推进,必看,AI 时代这玩意最吃你内存
android·前端·flutter
LinXunFeng4 天前
拿竞品 App 一扫,技术栈全暴露了
android·flutter·开源
传奇开心果编程4 天前
【Flutter踩坑排雷】第28课:平台目录缺失与修复坑|`flutter create` 的“重建”与“覆盖”边界
android·flutter·ios·移动开发·跨平台·dart·声明式ui
程序员老刘·5 天前
Flutter 3.50更新,开发者应该关注什么?
flutter·ai编程·跨平台开发