Flutter版本迁移辅助插件version_migration的使用

简介

VersionMigration 插件是将MTMigration库（MTMigration）转换为Dart包。它用于管理在Flutter应用程序中每次版本更新时需要运行一次的功能。这可以包括数据规范化例程、"本版本的新功能"界面或bug修复等。

安装

在您的pubspec.yaml文件中添加以下内容：

dependencies:
  version_migration: ^2.0.10

然后在终端执行flutter pub get以安装依赖。

使用方法

applicationUpdate 方法

如果您有一个函数，希望每次应用版本更新时都运行，则可以将其传递给applicationUpdate方法。

VersionMigration.applicationUpdate(() {
    metrics.resetStats();
});

migrateToVersion 方法

如果该函数仅针对特定版本，则应使用migrateToVersion方法，VersionMigration会确保该函数仅针对该版本运行一次。

VersionMigration.migrateToVersion("1.1", () {
    newness.presentNewness();
});

假设您有如下迁移代码：

VersionMigration.migrateToVersion("0.9", () {
    // Some 0.9 stuff
});

VersionMigration.migrateToVersion("1.0", () {
    // Some 1.0 stuff
});

如果用户从版本0.8跳过0.9直接升级到1.0，那么0.9和1.0的函数都会被执行。

reset 方法

为了调试/测试目的，您可以调用reset方法来清除VersionMigration记住的最后迁移记录，从而导致所有迁移从头开始执行。

VersionMigration.reset();

注意事项

• VersionMigration假定版本号按逻辑递增，例如1.0.1 -> 1.0.2，1.1 -> 1.2等。
• 如果尝试迁移到高于应用程序指定版本的版本，则迁移不会执行。例如，如果pubspec文件中指定的应用程序版本号为1.2，而您尝试迁移到1.3，则迁移不会执行。

示例Demo

下面是一个完整的示例demo，展示了如何在实际项目中使用VersionMigration插件。

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

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    VersionMigration.migrateToVersion("1.0.1", () async {
      String oldLastSavedCounterKey = "oldLastSavedCounterKey";
      String newLastSavedCounterKey = "newLastSavedCounterKey";

      SharedPreferences sharedPreferences = await SharedPreferences.getInstance();
      int? counter = sharedPreferences.getInt(oldLastSavedCounterKey);

      sharedPreferences.setInt(newLastSavedCounterKey, counter ?? 0);
    });

    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key? key, this.title}) : super(key: key);

  final String? title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  late SharedPreferences sharedPreferences;
  String lastSavedCounterKey = "newLastSavedCounterKey"; // 版本1.0.1之后使用的key
  int _counter = 0;

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

  Future<void> _loadCounter() async {
    sharedPreferences = await SharedPreferences.getInstance();
    setState(() {
      _counter = sharedPreferences.getInt(lastSavedCounterKey) ?? 0;
    });
  }

  void _incrementCounter() {
    setState(() {
      _counter++;
      sharedPreferences.setInt(lastSavedCounterKey, _counter);
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title ?? ""),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: Icon(Icons.add),
      ),
    );
  }
}

在这个示例中，我们演示了如何在版本从1.0.0升级到1.0.1时迁移计数器键名，并确保新版本中使用新的键名保存计数器值。