跨平台开发 / 系统课时

用 SharedPreferences 保存简单配置

用 SharedPreferences 保存简单配置

主题模式、功能开关、首次启动标记这类数据体积小、结构简单,却需要在应用重启后继续保留。shared_preferences 适合保存这类键值配置。本节会完成“启动读取 → 页面展示 → 用户修改 → 立即写回”的最小闭环。

学习目标

  • 使用 SharedPreferences 保存和读取布尔值、字符串等简单键值数据
  • 在 runApp 前读取启动配置,避免首屏先显示错误状态再跳变
  • 识别 SharedPreferences 的适用边界,避免把敏感或复杂数据放进去

添加依赖并确认可用

先在 Flutter 项目目录添加插件:

bash
flutter pub add shared_preferences

预期输出:

text
Resolving dependencies...
Got dependencies!

实际安装版本可能不同。命令成功后,pubspec.yaml 会新增 shared_preferences 依赖,之后即可从 Dart 代码导入插件。

在启动时读取并保存主题设置

下面的完整示例保存一个 darkMode 布尔值。应用启动时先读取本地值,再把它传给根组件;用户切换开关后立即写回。这样重启应用时可以直接使用上次选择的主题。

dart
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,
        ),
      ),
    );
  }
}

预期结果:

text
首次启动时默认使用浅色主题。
打开“深色模式”后界面切换为深色主题。
完全关闭并重新启动应用后,仍保持上一次保存的主题选择。

getBool('darkMode') ?? false 表示本地没有这个键时使用默认值。SharedPreferences 还可保存 int、double、String 和 List<String> 等简单类型,因此登录标记、是否看过引导页、排序方式等配置也可以使用同样模式。

设计键名和默认值

键名一旦上线就相当于本地数据协议。建议集中定义,避免在不同页面手写 'darkMode'、'dark_mode' 等近似名称。读取时始终给出明确默认值,否则首次安装、清除应用数据或旧版本升级后都可能得到 null。

对于需要迁移的配置,可以在版本升级时读取旧键、写入新键,再删除旧键。不要因为 SharedPreferences 使用简单,就忽略键名变化带来的兼容问题。

不要把它当成数据库或安全存储

SharedPreferences 适合“小、简单、低频”的配置,不适合大量列表、复杂对象、关系数据或高频写入。复杂离线数据应使用 SQLite、Isar 等更合适的持久化方案。

还要注意写入是异步操作。若某个后续流程依赖“已经持久化成功”,应像示例一样等待 setBool 的结果,而不是调用后立刻假定磁盘状态已经可靠更新。

对于简单配置,稳定做法是:启动阶段统一读取默认值,界面修改时立即写回,并为键名、默认值和迁移策略建立清晰约定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 SharedPreferences 保存简单配置

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通