Flutter状态恢复与持久化插件widget_hydrator的使用

Widget Hydrator 🌊

🚧 Under Active Development 🚧

Widget Hydrator 是一个强大的 Flutter 包，它通过提供一种简单且灵活的方式来在应用重启时保存和恢复 StatefulWidgets 的状态，从而革新了状态管理。通过使用单一的 mixin，您可以以最小的努力为您的小部件添加强大的状态持久性，从而增强用户体验并简化开发。

📚 Table of Contents

• 🌟 Key Features
• 📦 Installation
• 🚀 Basic Usage
• 🛠 Advanced Features
  • Configuration
  • 📸 State Snapshots
  • ↩️ Undo/Redo Functionality
  • 🎯 Selective Persistence
  • 🔧 Custom Serialization
  • 📊 Performance Metrics
  • 🔄 State Migration
• 💡 Best Practices
• 🚫 Common Pitfalls and Solutions
• 📱 Full Example: Task List Application
• 📝 To-Do List
• 🤝 Contributing
• 📄 License
• 👨‍💻 Contact and Support

🌟 Key Features

Widget Hydrator 提供了一整套功能来增强您的 Flutter 应用的状态管理：

• ✅ 自动状态持久化：无缝地跨应用重启保存和恢复小部件的状态。
• ❌ 压缩支持：使用内置数据压缩优化存储使用。
• ❌ 加密功能：使用加密保护敏感状态数据。
• ✅ 内存缓存：通过智能缓存机制提高性能。
• ✅ 撤销/重做功能：轻松实现应用中的撤销和重做功能。
• ✅ 状态迁移支持：平滑处理应用版本之间状态结构的变化。
• ✅ 选择性持久化：选择特定部分的状态进行持久化。
• ✅ 状态快照：创建和恢复应用状态的命名快照。
• ✅ 性能指标：监控和优化水合和持久化操作。
• ✅ 自定义序列化：处理复杂对象的自定义序列化逻辑。
• ✅ 灵活配置：根据您的应用需求调整水合过程。

📦 Installation

要在您的 Flutter 项目中使用 Widget Hydrator，请将其添加到您的 pubspec.yaml 文件中：

dependencies:
  widget_hydrator: ^0.0.1

然后运行：

flutter pub get

🚀 Basic Usage

1. 在您的 Dart 文件中导入包：

import 'package:widget_hydrator/widget_hydrator.dart';

1. 将 UltimateHydrationMixin 添加到您的 StatefulWidget 的 State 类中：

class _MyWidgetState extends State<MyWidget> with UltimateHydrationMixin {
  String _myStateVariable = '';

  [@override](/user/override)
  void initState() {
    super.initState();
    _initializeHydration();
  }

  Future<void> _initializeHydration() async {
    await initializeHydration(HydrationConfig(
      // useCompression: true,
      // enableEncryption: true,
      // encryptionKey: 'your-secret-key',
    ));
    await ensureHydrated();
  }

  [@override](/user/override)
  Map<String, dynamic> persistToJson() {
    return {
      'myStateVariable': _myStateVariable,
    };
  }

  [@override](/user/override)
  void hydrateFromJson(Map<String, dynamic> json) {
    _myStateVariable = json['myStateVariable'] as String? ?? '';
  }

  [@override](/user/override)
  void initializeDefaultState() {
    _myStateVariable = 'Default Value';
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return FutureBuilder(
      future: ensureHydrated(),
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.done) {
          return Text(_myStateVariable);
        } else {
          return CircularProgressIndicator();
        }
      },
    );
  }
}

🛠 Advanced Features

Configuration

Widget Hydrator 提供了灵活的配置选项，可以根据您的应用需求调整其行为：

HydrationConfig config = HydrationConfig(
  // useCompression: true,
  // enableEncryption: true,
  // encryptionKey: 'your-secret-key',
  // version: 1,
  // autoSaveInterval: Duration(minutes: 5),
  stateExpirationDuration: Duration(days: 7),
  // maxRetries: 3,
  // debounceDuration: Duration(milliseconds: 300),
);

await initializeHydration(config);

📸 State Snapshots

状态快照允许您保存和恢复应用状态中的特定点：

// 创建快照
await createSnapshot('before_important_change');

// 恢复快照
await restoreSnapshot('before_important_change');

// 获取快照列表
List<String> snapshots = await getSnapshots();

// 获取快照详情
Map<String, dynamic> details = await getSnapshotDetails('snapshot_name');

// 删除快照
await deleteSnapshot('old_snapshot');

↩️ Undo/Redo Functionality

轻松实现撤销和重做功能：

void undoLastAction() {
  undo();
  // 额外的逻辑如果需要
}

void redoLastUndo() {
  redo();
  // 额外的逻辑如果需要
}

🎯 Selective Persistence

选择性地持久化您的状态的一部分：

await persistSelectedKeys(['user', 'preferences']);

🔧 Custom Serialization

处理复杂的对象使用自定义序列化：

setCustomSerializer(
  (obj) => (obj as ComplexObject).toJson(),
  (json) => ComplexObject.fromJson(json as Map<String, dynamic>)
);

📊 Performance Metrics

监控水合和持久化操作的性能：

Map<String, int> metrics = getPerformanceMetrics();
print('Hydration took ${metrics['hydrationDuration']}ms');
print('Persistence took ${metrics['persistDuration']}ms');

🔄 State Migration

处理应用版本之间的状态结构变化：

[@override](/user/override)
Future<Map<String, dynamic>> migrateState(Map<String, dynamic> oldState) async {
  if (oldState['version'] == 1) {
    // 从版本 1 迁移到版本 2
    oldState['newField'] = 'default value';
    oldState['version'] = 2;
  }
  return oldState;
}

💡 Best Practices

1. 尽早初始化：在小部件的 initState() 方法中调用 initializeHydration() 以确保在需要时水合已经准备就绪。
2. 使用 FutureBuilder：使用 FutureBuilder 包裹您的小部件内容，并将 ensureHydrated() 作为未来值处理水合的异步性质。
3. 保持简洁：仅持久化需要在应用重启后存活的状态。避免持久化可以轻松重新创建或获取的大数据量。
4. 优雅地处理错误：在 hydrateFromJson() 中实现错误处理以应对持久化数据中的潜在问题。
5. 对敏感数据启用加密：在处理用户特定或敏感信息时启用加密。
6. 定期清理：实施一种机制以清除旧的或不必要的持久化状态，以有效管理存储。
7. 彻底测试：确保您的应用在首次安装和更新后都能正常工作，测试各种状态持久性和恢复场景。

🚫 Common Pitfalls and Solutions

1. 持久化过多的数据：

   • 问题：由于持久化大量数据导致性能缓慢。
   • 解决方案：仅持久化必要状态，对于大数据集使用选择性持久化。

2. 更新后状态不一致：

   • 问题：应用在更新后崩溃或表现异常。
   • 解决方案：在 migrateState() 方法中实现适当的迁移逻辑。

3. 加密密钥管理：

   • 问题：丢失或泄露加密密钥。
   • 解决方案：使用安全的密钥存储解决方案并实施密钥轮换机制。

4. 性能问题：

   • 问题：由于水合导致应用启动缓慢。
   • 解决方案：使用内存缓存，优化持久化的数据量，并考虑异步加载模式。

📱 Full Example: Task List Application

这是一个更全面的例子，展示了如何在任务列表应用中使用 Widget Hydrator 进行状态持久化：

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

class Task {
  final String id;
  String title;
  bool isCompleted;

  Task({required this.id, required this.title, this.isCompleted = false});

  Map<String, dynamic> toJson() => {
    'id': id,
    'title': title,
    'isCompleted': isCompleted,
  };

  factory Task.fromJson(Map<String, dynamic> json) => Task(
    id: json['id'],
    title: json['title'],
    isCompleted: json['isCompleted'],
  );
}

class TaskListScreen extends StatefulWidget {
  [@override](/user/override)
  _TaskListScreenState createState() => _TaskListScreenState();
}

class _TaskListScreenState extends State<TaskListScreen> with UltimateHydrationMixin {
  List<Task> _tasks = [];

  [@override](/user/override)
  void initState() {
    super.initState();
    _initializeAndHydrate();
  }

  Future<void> _initializeAndHydrate() async {
    await initializeHydration(HydrationConfig(
      // useCompression: false,
      // enableEncryption: true,
      // encryptionKey: 'bXktc2VjcmV0LWtleS0xMjM0NTY3ODkwMTIzNDU2Nzg5MDEyMzQ1Njc4OTA=', // 256-bit Base64 encoded key
      stateExpirationDuration: const Duration(days: 7),
    ));
    await _loadTasks();
  }

  Future<void> _loadTasks() async {
    await ensureHydrated();
    setState(() {});
  }

  [@override](/user/override)
  Map<String, dynamic> persistToJson() {
    return {
      'tasks': _tasks.map((task) => task.toJson()).toList(),
    };
  }

  [@override](/user/override)
  void hydrateFromJson(Map<String, dynamic> json) {
    final taskList = json['tasks'] as List<dynamic>?;
    if (taskList != null) {
      _tasks = taskList.map((taskJson) => Task.fromJson(taskJson)).toList();
    }
  }

  [@override](/user/override)
  void initializeDefaultState() {
    _tasks = [];
  }

  void _addTask(String title) {
    setState(() {
      _tasks.add(Task(id: DateTime.now().toString(), title: title));
    });
  }

  void _toggleTask(String id) {
    setState(() {
      final task = _tasks.firstWhere((task) => task.id == id);
      task.isCompleted = !task.isCompleted;
    });
  }

  void _deleteTask(String id) {
    setState(() {
      _tasks.removeWhere((task) => task.id == id);
    });
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Task List')),
      body: FutureBuilder(
        future: ensureHydrated(),
        builder: (context, snapshot) {
          if (snapshot.connectionState == ConnectionState.done) {
            return ListView.builder(
              itemCount: _tasks.length,
              itemBuilder: (context, index) {
                final task = _tasks[index];
                return ListTile(
                  title: Text(task.title),
                  leading: Checkbox(
                    value: task.isCompleted,
                    onChanged: (_) => _toggleTask(task.id),
                  ),
                  trailing: IconButton(
                    icon: Icon(Icons.delete),
                    onPressed: () => _deleteTask(task.id),
                  ),
                );
              },
            );
          } else {
            return Center(child: CircularProgressIndicator());
          }
        },
      ),
      floatingActionButton: FloatingActionButton(
        child: Icon(Icons.add),
        onPressed: () {
          showDialog(
            context: context,
            builder: (context) {
              String newTaskTitle = '';
              return AlertDialog(
                title: Text('Add New Task'),
                content: TextField(
                  autofocus: true,
                  onChanged: (value) => newTaskTitle = value,
                ),
                actions: [
                  TextButton(
                    child: Text('Cancel'),
                    onPressed: () => Navigator.pop(context),
                  ),
                  TextButton(
                    child: Text('Add'),
                    onPressed: () {
                      if (newTaskTitle.isNotEmpty) {
                        _addTask(newTaskTitle);
                        Navigator.pop(context);
                      }
                    },
                  ),
                ],
              );
            },
          );
        },
      ),
    );
  }
}