Riverpod从0.14.0到1.0.0版本迁移指南

Riverpod从0.14.0到1.0.0版本迁移指南

riverpod A simple way to access state while robust and testable. 项目地址: https://gitcode.com/gh_mirrors/ri/riverpod

Riverpod作为Flutter状态管理库的标杆，终于在1.0.0版本迎来了稳定发布。本文将详细介绍如何从0.14.x版本平滑迁移至1.0.0版本，帮助开发者理解变更内容并顺利完成升级。

自动迁移工具使用

Riverpod团队贴心地提供了命令行工具来自动化迁移过程，大幅降低升级成本。

工具安装与准备

1. 首先全局安装迁移工具：

dart pub global activate riverpod_cli

2. 验证安装成功：

riverpod --help

迁移执行步骤

1. 保持原有版本：切记不要手动升级Riverpod版本，工具会自动处理
2. 确保项目无编译错误：迁移前项目应处于可编译状态
3. 执行迁移命令：

riverpod migrate

迁移过程中，工具会逐个展示变更建议，开发者可以通过以下按键交互：

• y：接受当前变更
• n：拒绝当前变更
• A：接受所有剩余变更
• q：退出迁移

主要变更内容详解

语法统一化

1.0.0版本最重要的改进是统一了provider的访问语法，消除了之前版本中多种访问方式并存的情况。

HookWidget迁移

旧版写法：

class Example extends HookWidget {
  @override
  Widget build(BuildContext context) {
    useState(...);
    int count = useProvider(counterProvider);
    ...
  }
}

新版写法：

class Example extends HookConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    useState(...);
    int count = ref.watch(counterProvider);
    ...
  }
}

关键变化：

• 继承类改为HookConsumerWidget
• 增加WidgetRef ref参数
• 使用ref.watch替代useProvider

ConsumerWidget重构

旧版写法：

class Example extends ConsumerWidget {
  @override
  Widget build(BuildContext context, ScopedReader watch) {
    int count = watch(counterProvider);
    ...
  }
}

新版写法：

class Example extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    int count = ref.watch(counterProvider);
    ...
  }
}

主要变更：

• 参数类型从ScopedReader改为WidgetRef
• 访问方式从watch()改为ref.watch()

context.read移除

旧版写法：

class Example extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    SomeButton(
      onPressed: () => context.read(provider.notifier).doSomething(),
    );
  }
}

新版写法：

class Example extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    SomeButton(
      onPressed: () => ref.read(provider.notifier).doSomething(),
    );
  }
}

注意事项：

• 需要将StatelessWidget改为ConsumerWidget
• 使用ref.read替代context.read

StateProvider行为变更

StateProvider的watch行为发生了变化，现在直接返回状态值而非StateController实例。

简单状态访问

旧版写法：

StateController<int> count = ref.watch(provider);
Text('${count.state}');

新版简化写法：

int count = ref.watch(provider);
Text('$count');

需要StateController的场景

如果需要保留旧版行为，可以使用.state属性：

StateController<int> count = ref.watch(provider.state);
Text('${count.state}');

迁移建议

1. 分阶段迁移：大型项目建议按模块逐步迁移
2. 充分测试：迁移后需全面测试各功能点
3. 团队协作：确保团队成员都了解新语法规范
4. 代码审查：重点关注状态访问方式的变更

通过遵循本指南，开发者可以顺利完成Riverpod 1.0.0的迁移工作，享受更统一、更稳定的状态管理体验。

riverpod A simple way to access state while robust and testable. 项目地址: https://gitcode.com/gh_mirrors/ri/riverpod