Flutter偏好设置管理插件notified_preferences的使用

notified_preferences 是一个用于读取和写入键值对的Flutter插件。它是 shared_preferences 的封装，提供了监听偏好设置值变化的简便方法。

Index

• Usage
  • Getting started
  • Widgets
  • Listeners
  • Json
  • Enums
• Advanced usage
  • Custom shared prefs
  • Manual notifiers
  • Custom Read/Write
  • Decentralised settings

Usage

Getting started

为了开始使用 notified_preferences，你需要创建一个自定义的 Settings 类，并初始化它。以下是一个简单的例子：

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

class Settings with NotifiedPreferences {
  late final PreferenceNotifier<bool> hasSeenTutorial =
      createSetting(key: 'hasSeenTutorial', initial: false);

  late final PreferenceNotifier<int> clicked =
      createSetting(key: 'buttonClicks', initial: 0);
}

Future<void> main() async {
  Settings settings = Settings();
  await settings.initialize();
  runApp(
    // 使用 Provider 或其他方式注入你的 settings
    Provider.value(
      value: settings,
      child: MyApp(),
    ),
  );
}

Widgets

你可以使用 ValueListenableBuilder 来监听偏好设置的变化：

ValueListenableBuilder<int>(
  valueListenable: settings.clicked,
  builder: (context, value, child) => Text('You have clicked the button $value times!'),
)

当改变值时，所有监听器将被通知并重新构建：

FloatingActionButton(
  onPressed: () => settings.clicked.value++,
  tooltip: 'Increment',
  child: const Icon(Icons.add),
),

Listeners

你也可以通过 addListener 监听偏好设置的变化：

void _onClicked() {
  print('The user has clicked ${settings.clicked.value} times!');
}

settings.clicked.addListener(_onClicked);

记得在适当的时候移除监听器以避免内存泄漏：

@override
void dispose() {
  settings.clicked.removeListener(_onClicked);
  super.dispose();
}

Json

对于非基本类型的数据，可以将其作为 JSON 存储：

late final PreferenceNotifier<ComplexObject> complexObject = createJsonSetting(
  key: 'complexObject',
  initialValue: ComplexObject(
    someInt: 0,
    someString: 'a',
  ),
  fromJson: (json) => ComplexObject.fromJson(json),
);

Enums

对于枚举类型，提供了便利的方法：

late final PreferenceNotifier<SomeEnum> someEnum = createEnumSetting(
  key: 'someEnum',
  initialValue: SomeEnum.a,
  values: SomeEnum.values,
);

Advanced usage

Custom shared prefs

如果你已经在使用其他 SharedPreferences 封装库（如 encrypted_shared_preferences），或想要为测试模拟实现，可以在初始化时传递不同的 SharedPreferences 实现：

await settings.initialize(otherSharedPrefs);

Manual notifiers

如果不使用 NotifiedPreferences，可以手动实例化 PreferenceNotifier：

final myNotifier = PreferenceNotifier<T>(
  preferences: preferences,
  key: key,
  initialValue: initialValue,
  read: read,
  write: write,
);

注意，这样会失去清除所有设置的功能。

Custom Read/Write

如果需要在读写偏好设置时实现自定义逻辑：

late final PreferenceNotifier<ComplexObject> complexObject = createSetting(
  key: 'complexObject',
  initialValue: ComplexObject(
    someInt: 0,
    someString: 'a',
  ),
  read: (prefs, key) {
    String? value = prefs.getString(key);
    ComplexObject? result;
    if (value != null) {
      result = ComplexObject.fromJson(jsonDecode(value));
    }
    return result;
  },
  write: (prefs, key, value) => prefs.setStringOrNull(
    key,
    json.encode(value.toJson()),
  ),
);

注意，read 方法不能是异步的。

Decentralised settings

如果你想在多个类中存储偏好设置，可以使用 NotifiedSettings：

NotifiedSettings settings = await NotifiedSettings.getInstance();

class SomeController {
  final ValueNotifier<String?> someValue = settings.createSettings(
    key: 'someString',
    initialValue: null,
  );
}

这样可以保留清除所有设置的能力。

示例代码

以下是完整的示例代码，展示了如何使用 notified_preferences：

import 'package:flutter/material.dart';
import 'package:notified_preferences/notified_preferences.dart';
import 'package:provider/provider.dart';

class Settings with NotifiedPreferences {
  late final PreferenceNotifier<int> clicked =
      createSetting(key: 'buttonClicks', initial: 0);
}

class SettingsProvider extends InheritedWidget {
  final Settings settings;

  const SettingsProvider({
    Key? key,
    required this.settings,
    required Widget child,
  }) : super(key: key, child: child);

  static Settings of(BuildContext context) =>
      context.dependOnInheritedWidgetOfExactType<SettingsProvider>()!.settings;

  @override
  bool updateShouldNotify(covariant InheritedWidget oldWidget) => true;
}

Future<void> main() async {
  Settings settings = Settings();
  await settings.initialize();
  runApp(
    SettingsProvider(
      settings: settings,
      child: const MyApp(),
    ),
  );
}

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

  @override
  Widget build(BuildContext context) => const MaterialApp(home: MyHomePage());
}

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Notified Preferences Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'You have pushed the button this many times:',
            ),
            ValueListenableBuilder<int>(
              valueListenable: SettingsProvider.of(context).clicked,
              builder: (context, value, child) => Text(
                '$value',
                style: Theme.of(context).textTheme.headline4,
              ),
            ),
          ],
        ),
      ),
      bottomNavigationBar: Padding(
        padding: const EdgeInsets.all(8),
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            const Text(
              'Close the app and reopen it to see your state persist.',
            ),
            TextButton(
              onPressed: SettingsProvider.of(context).clicked.reset,
              child: const Text('RESET'),
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => SettingsProvider.of(context).clicked.value++,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

这个示例展示了如何使用 notified_preferences 创建、初始化和监听偏好设置，并在UI中反映这些设置的变化。