插件介绍

Shared Preferences 是 Flutter 官方提供的一个轻量级数据持久化插件，用于存储简单的键值对数据。它能够将数据持久化到设备的本地存储中，支持多种数据类型，并且提供了简洁易用的 API 接口。

主要功能特点：

• 跨平台支持：支持 Android、iOS、Linux、macOS、Web、Windows 和鸿蒙平台
• 简单易用：提供简洁的异步 API，易于集成到 Flutter 应用中
• 多种数据类型：支持存储 int、double、bool、String 和 List<String> 类型
• 性能优化：在 Dart 层面实现了缓存机制，提高读取效率
• 鸿蒙平台适配：完全支持鸿蒙 API 12+ 版本，功能与其他平台保持一致

依赖配置

由于这是针对鸿蒙平台的自定义修改版本，需要通过 Git 形式引入依赖。在项目的 pubspec.yaml 文件中添加以下配置：

dependencies:
  shared_preferences:
    git:
      url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/shared_preferences/shared_preferences"

添加依赖后，执行以下命令获取包：

flutter pub get

API 调用

1. 获取 SharedPreferences 实例

在使用任何 SharedPreferences API 之前，需要先获取其实例：

import 'package:shared_preferences/shared_preferences.dart';

// 异步获取 SharedPreferences 实例
final SharedPreferences prefs = await SharedPreferences.getInstance();

2. 存储数据

SharedPreferences 提供了针对不同数据类型的存储方法：

// 存储整数值
await prefs.setInt('counter', 10);

// 存储布尔值
await prefs.setBool('isLoggedIn', true);

// 存储浮点数值
await prefs.setDouble('score', 98.5);

// 存储字符串
await prefs.setString('username', 'flutter_user');

// 存储字符串列表
await prefs.setStringList('favoriteColors', ['red', 'blue', 'green']);

3. 读取数据

对应的读取方法会返回存储的值，如果键不存在则返回 null：

// 读取整数值
final int? counter = prefs.getInt('counter');

// 读取布尔值
final bool? isLoggedIn = prefs.getBool('isLoggedIn');

// 读取浮点数值
final double? score = prefs.getDouble('score');

// 读取字符串
final String? username = prefs.getString('username');

// 读取字符串列表
final List<String>? favoriteColors = prefs.getStringList('favoriteColors');

4. 删除数据

可以删除特定键的值或清空所有存储的数据：

// 删除特定键的值
await prefs.remove('counter');

// 清空所有存储的数据
await prefs.clear();

5. 检查键是否存在

// 检查键是否存在
final bool hasCounter = prefs.containsKey('counter');

6. 获取所有键

// 获取所有存储的键
final Set<String> keys = prefs.getKeys();
print('所有存储的键: $keys');

7. 重新加载数据

如果数据可能被其他进程或实例修改，可以使用 reload() 方法刷新缓存：

// 重新加载数据以更新缓存
await prefs.reload();

8. 设置键前缀

默认情况下，SharedPreferences 只会读取以 flutter. 为前缀的键。可以通过设置前缀来更改此行为：

// 在获取实例之前设置前缀
SharedPreferences.setPrefix('my_app.');

// 现在所有键都会自动添加 'my_app.' 前缀
final SharedPreferences prefs = await SharedPreferences.getInstance();
await prefs.setString('username', 'flutter_user'); // 实际存储的键为 'my_app.username'

使用示例：计数器应用

下面是一个简单的计数器应用示例，展示如何使用 SharedPreferences 持久化存储计数器的值：

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

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      title: 'Shared Preferences Demo',
      home: CounterPage(),
    );
  }
}

class CounterPage extends StatefulWidget {
  const CounterPage({super.key});

  @override
  State<CounterPage> createState() => _CounterPageState();
}

class _CounterPageState extends State<CounterPage> {
  int _counter = 0;
  late SharedPreferences _prefs;
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    _loadCounter();
  }

  Future<void> _loadCounter() async {
    _prefs = await SharedPreferences.getInstance();
    setState(() {
      _counter = _prefs.getInt('counter') ?? 0;
      _isLoading = false;
    });
  }

  Future<void> _incrementCounter() async {
    setState(() {
      _counter++;
    });
    await _prefs.setInt('counter', _counter);
  }

  Future<void> _resetCounter() async {
    setState(() {
      _counter = 0;
    });
    await _prefs.setInt('counter', _counter);
  }

  @override
  Widget build(BuildContext context) {
    if (_isLoading) {
      return const Scaffold(
        body: Center(child: CircularProgressIndicator()),
      );
    }

    return Scaffold(
      appBar: AppBar(
        title: const Text('Counter App'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text('You have pushed the button this many times:'),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline4,
            ),
          ],
        ),
      ),
      floatingActionButton: Column(
        mainAxisAlignment: MainAxisAlignment.end,
        children: [
          FloatingActionButton(
            onPressed: _incrementCounter,
            tooltip: 'Increment',
            child: const Icon(Icons.add),
          ),
          const SizedBox(height: 10),
          FloatingActionButton(
            onPressed: _resetCounter,
            tooltip: 'Reset',
            child: const Icon(Icons.refresh),
          ),
        ],
      ),
    );
  }
}

注意事项

1. 鸿蒙平台兼容性

• 确保项目的鸿蒙 API 版本不低于 12
• 使用 Flutter 3.7.12-ohos-1.0.6 或更高版本进行开发
• 所有功能与其他平台保持一致，无需特殊处理

2. 数据类型限制

• 仅支持 int、double、bool、String 和 List<String> 类型
• 不支持存储复杂对象，如果需要存储复杂数据，可以先序列化为 JSON 字符串

3. 性能考虑

• SharedPreferences 适用于存储少量简单数据，不建议存储大量数据
• 读取操作是同步的，因为 Dart 层面实现了缓存
• 写入操作是异步的，会持久化到设备存储中

4. 多实例和多进程

• 在多 isolate 或多引擎实例环境中，每个实例都有自己的缓存
• 如果数据可能被外部修改，建议在读取前调用 reload() 方法刷新缓存

5. 键前缀

• 默认前缀为 flutter.，可以通过 setPrefix() 方法修改
• 更改前缀必须在获取实例之前进行
• 可以设置为空字符串以访问非 Flutter 应用创建的偏好设置

总结

Shared Preferences 是 Flutter 应用中常用的数据持久化解决方案，它提供了简单易用的 API，支持多种数据类型，并具有良好的跨平台兼容性。在鸿蒙平台上，它的使用方式与其他平台完全一致，开发者可以轻松迁移现有代码或开发新的鸿蒙应用。

适用场景

• 存储用户偏好设置
• 保存应用状态信息
• 存储简单的用户数据
• 实现应用的记住密码功能
• 保存应用的计数器或分数等简单数据

通过使用 Shared Preferences，开发者可以轻松实现数据的持久化存储，提高应用的用户体验，同时减少开发复杂度。在鸿蒙平台上，它的完整支持为 Flutter 开发者提供了更多的选择和灵活性。