跨平台开发 / 系统课时

用注解声明普通 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 读取它。

dart
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),
        ),
      ),
    );
  }
}

先生成代码,再启动应用。

bash
dart run build_runner build -d
flutter run

预期结果

text
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 函数。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用注解声明普通 Provider

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通