跨平台开发 / 系统课时
用注解声明普通 Provider
用注解声明普通 Provider
代码生成模式下,普通 Provider 不再从 Provider(...) 构造器起步,而是先写一个带 @riverpod 的顶层函数,再由生成器创建可供 ref.watch 使用的 Provider。本节用一个可运行的最小 Flutter 页面验证声明方式,并把函数名到 Provider 名的映射讲清楚。
学习目标
- 使用
@riverpod声明同步普通 Provider - 理解函数名与生成 Provider 名之间的对应关系
- 在
ConsumerWidget中读取生成后的 Provider
写出最小声明
当前 Riverpod 代码生成语法使用统一的 Ref 类型。函数保持顶层声明,首个参数接收 Ref,返回值类型就是 Provider 暴露的值类型。文件还必须通过 part 指向生成文件。
下面的 lib/main.dart 是完整示例。environment 会生成 environmentProvider,页面通过 ref.watch 读取它。
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';
part 'main.g.dart';
@riverpod
String environment(Ref ref) {
return 'development';
}
void main() {
runApp(
const ProviderScope(
child: App(),
),
);
}
class App extends ConsumerWidget {
const App({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final value = ref.watch(environmentProvider);
return MaterialApp(
home: Scaffold(
body: Center(
child: Text(value),
),
),
);
}
}先生成代码,再启动应用。
dart run build_runner build -d
flutter run预期结果
main.g.dart 成功生成;应用页面中央显示 development。具体设备启动日志、端口和构建耗时会因运行环境不同而变化。理解生成名称
命名规则的核心很直接:生成器以被注解函数的 Dart 名称为基础,并追加 Provider。例如 environment 对应 environmentProvider,apiClient 对应 apiClientProvider。消费端引用的是生成后的变量,而不是直接调用被注解函数。
这个规则让声明和使用保持可预测,也意味着重命名函数后必须重新运行生成器。若只改了函数名却保留旧 .g.dart,编辑器可能短暂看到旧符号;重新生成后应同步修改所有引用。
注意默认生命周期
使用代码生成时,Provider 默认启用自动释放:当它不再被监听时,Riverpod 可以销毁其状态。普通配置值、派生值和按页面使用的数据通常适合这个默认行为。
只有明确需要在无监听者时继续保留状态,才使用 @Riverpod(keepAlive: true)。不要为了“省事”给所有 Provider 都开启保活,否则会削弱自动清理带来的生命周期管理优势。
处理常见声明错误
如果生成器没有产出文件,优先检查 part 'main.g.dart'; 的文件名是否与当前 Dart 文件对应,以及是否已经导入 riverpod_annotation。如果生成成功但代码里找不到 environmentProvider,先确认函数名没有改动,再重新执行 dart run build_runner build -d。
普通同步 Provider 的声明尽量保持纯粹:从 Ref 读取其他 Provider,计算并返回一个值。需要对外暴露修改状态的方法时,应改用注解类形式的 Notifier,而不是把可变操作硬塞进普通 Provider 函数。