Flutter本地存储插件flutter_app_preferences的使用

Flutter本地存储插件flutter_app_preferences的使用

flutter_app_preferences 是一个用于以类型安全的方式管理共享偏好设置（shared preferences）的插件。它允许你在偏好设置发生变化时接收通知。每个 Preference<T> 都扩展了 ValueNotifier<T>，以最大限度地提高与现有解决方案的兼容性，并在使用 Flutter 时提供无缝体验。

状态

状态	备注
	当前稳定版 Flutter
	当前测试版 Flutter
	最低支持的 Flutter 版本

开始使用

1. 将此包添加到你的依赖项中：

dependencies:
  flutter_app_preferences: latest_version

1. 获取依赖项：

flutter pub get

使用

1. 创建一个包含你偏好的类：

import 'package:flutter_app_preferences/flutter_app_preferences.dart';

// 一个保存偏好设置的类。
class AppPreferences extends BaseAppPreferences {
  // 示例：保存布尔值。
  final highContrast = Preference('high-contrast', true);

  // 示例：保存枚举。
  final fontSize = Preference(
    'font-size',
    FontSize.medium,
    values: FontSize.values,
  );

  // 示例：保存自定义对象。
  final currentUser = Preference(
    'current-user',
    User.initialUser,
    fromJson: User.fromJson,
    toJson: (user) => user.toJson(),
  );

  // 提供所有应用偏好设置的列表，确保 `AppPreferences` 实例可以通知其监听器。
  [@override](/user/override)
  List<Preference<Object?>> get props => [
        highContrast,
        fontSize,
        currentUser,
      ];
}

// 示例枚举。
enum FontSize {
  small,
  medium,
  large,
}

// 示例自定义对象。
class User {
  const User({required this.name});

  factory User.fromJson(Map<String, Object?> json) =>
      User(name: json['name']! as String);

  Map<String, Object?> toJson() => {'name': name};

  static const initialUser = User(name: '');

  final String name;
}

1. 初始化 AppPreferences 实例：

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final prefs = AppPreferences();
  await prefs.initialize();

  runApp(const MaterialApp());
}

1. 在整个应用中提供并使用它：

• 使用 provider：

// 提供
runApp(
  ChangeNotifierProvider.value(
    value: prefs,
    child: const MaterialApp(),
  ),
);

// 读取所有
final prefs = context.watch<AppPreferences>();

// 读取单个
final fontSize = context.select<AppPreferences, FontSize>(
  (prefs) => prefs.fontSize.value,
);

• 使用全局实例：

// 声明
class AppPreferences extends BaseAppPreferences {
  static final i = AppPreferences();
}

// 初始化
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AppPreferences.i.initialize();

  runApp(const MaterialApp());
}

// 写入
AppPreferences.i.highContrast.value = true;

// 读取
print(AppPreferences.i.highContrast.value);

// 读取并响应变化
return ListenableBuilder(
  listenable: AppPreferences.i.highContrast,
  builder: (context, _) => Text(
    'High contrast? ${AppPreferences.i.highContrast.value}',
  ),
);

其他信息

• BaseAppPreferences 扩展了 ChangeNotifier 并在任何 Preference 发生更改时通知其监听器。
• Preference<T> 扩展了 ValueNotifier<T> 并在其值发生更改时通知其监听器。
• 在访问任何 Preference 之前，必须调用 initialize 方法。
• 偏好设置由 SharedPreferencesWithCache 支持，这意味着如果你当前在项目中使用 SharedPreferences.getInstance() 并希望迁移到此包，则需要指定带有 flutter. 前缀的键，并且在 Android 上手动迁移它们。更多信息请参见 官方文档。
• 此插件需要至少 Flutter 3.24 版本才能运行。
• 如果有任何问题，请前往 GitHub Issues 报告错误。

维护者

• Nikodem Bernat

示例代码

以下是一个完整的示例代码，展示了如何使用 flutter_app_preferences 插件来管理偏好设置。

import 'package:example/app_preferences.dart';
import 'package:flutter/material.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AppPreferences.i.initialize();

  runApp(
    MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        useMaterial3: true,
      ),
      home: const MyHomePage(),
    ),
  );
}

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

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('App Preferences Example'),
      ),
      body: ListenableBuilder(
        listenable: AppPreferences.i.counter,
        builder: (context, _) => Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: <Widget>[
              const Text(
                'You have pushed the button this many times:',
              ),
              Text(
                '${AppPreferences.i.counter.value}',
                style: Theme.of(context).textTheme.headlineMedium,
              ),
            ],
          ),
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => AppPreferences.i.counter.value += 1,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}