跨平台开发 / 系统课时
用 SharedPreferences 保存简单配置
用 SharedPreferences 保存简单配置
主题模式、功能开关、首次启动标记这类数据体积小、结构简单,却需要在应用重启后继续保留。shared_preferences 适合保存这类键值配置。本节会完成“启动读取 → 页面展示 → 用户修改 → 立即写回”的最小闭环。
学习目标
- 使用
SharedPreferences保存和读取布尔值、字符串等简单键值数据 - 在
runApp前读取启动配置,避免首屏先显示错误状态再跳变 - 识别 SharedPreferences 的适用边界,避免把敏感或复杂数据放进去
添加依赖并确认可用
先在 Flutter 项目目录添加插件:
flutter pub add shared_preferences预期输出:
Resolving dependencies...
Got dependencies!实际安装版本可能不同。命令成功后,pubspec.yaml 会新增 shared_preferences 依赖,之后即可从 Dart 代码导入插件。
在启动时读取并保存主题设置
下面的完整示例保存一个 darkMode 布尔值。应用启动时先读取本地值,再把它传给根组件;用户切换开关后立即写回。这样重启应用时可以直接使用上次选择的主题。
import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
final prefs = await SharedPreferences.getInstance();
final initialDarkMode = prefs.getBool('darkMode') ?? false;
runApp(
SettingsApp(
prefs: prefs,
initialDarkMode: initialDarkMode,
),
);
}
class SettingsApp extends StatefulWidget {
const SettingsApp({
super.key,
required this.prefs,
required this.initialDarkMode,
});
final SharedPreferences prefs;
final bool initialDarkMode;
@override
State<SettingsApp> createState() => _SettingsAppState();
}
class _SettingsAppState extends State<SettingsApp> {
late bool _darkMode;
@override
void initState() {
super.initState();
_darkMode = widget.initialDarkMode;
}
Future<void> _setDarkMode(bool value) async {
// 先持久化,写入成功后再更新界面状态。
final saved = await widget.prefs.setBool('darkMode', value);
if (!saved || !mounted) return;
setState(() {
_darkMode = value;
});
}
@override
Widget build(BuildContext context) {
return MaterialApp(
themeMode: _darkMode ? ThemeMode.dark : ThemeMode.light,
theme: ThemeData.light(),
darkTheme: ThemeData.dark(),
home: Scaffold(
appBar: AppBar(title: const Text('本地配置')),
body: SwitchListTile(
title: const Text('深色模式'),
value: _darkMode,
onChanged: _setDarkMode,
),
),
);
}
}预期结果:
首次启动时默认使用浅色主题。
打开“深色模式”后界面切换为深色主题。
完全关闭并重新启动应用后,仍保持上一次保存的主题选择。getBool('darkMode') ?? false 表示本地没有这个键时使用默认值。SharedPreferences 还可保存 int、double、String 和 List<String> 等简单类型,因此登录标记、是否看过引导页、排序方式等配置也可以使用同样模式。
设计键名和默认值
键名一旦上线就相当于本地数据协议。建议集中定义,避免在不同页面手写 'darkMode'、'dark_mode' 等近似名称。读取时始终给出明确默认值,否则首次安装、清除应用数据或旧版本升级后都可能得到 null。
对于需要迁移的配置,可以在版本升级时读取旧键、写入新键,再删除旧键。不要因为 SharedPreferences 使用简单,就忽略键名变化带来的兼容问题。
不要把它当成数据库或安全存储
SharedPreferences 适合“小、简单、低频”的配置,不适合大量列表、复杂对象、关系数据或高频写入。复杂离线数据应使用 SQLite、Isar 等更合适的持久化方案。
还要注意写入是异步操作。若某个后续流程依赖“已经持久化成功”,应像示例一样等待 setBool 的结果,而不是调用后立刻假定磁盘状态已经可靠更新。
对于简单配置,稳定做法是:启动阶段统一读取默认值,界面修改时立即写回,并为键名、默认值和迁移策略建立清晰约定。