前端移动开发【免费下载链接】riverpodA reactive caching and>项目地址https://gitcode.com/gh_mirrors/ri/riverpod点击查看免费下载导读hooks_riverpod是 Riverpod 生态中面向Flutter Hooks的集成包它让 Widget 在build方法中既能使用flutter_hooks的 hooks如useState又能通过WidgetRef读写 provider。本文以 packages/hooks_riverpod/CHANGELOG.md覆盖 0.1.0 至 3.4.3 的全部版本为骨架系统梳理 3.x 时代引入的CustomProviderListenable、ref.watch(provider.listenable)、Ref.onManualInvalidation、ProviderContainer.allProviders()等新能力还原 3.0 大版本中 offline、mutation、自动重试、暂停/恢复等特性的落地过程并给出 2.x 到 3.x 的迁移要点与源码级佐证。读完本文你将能够对照 CHANGELOG 逐项评估升级影响并掌握 hooks_riverpod 核心 WidgetHookConsumerWidget等在仓库中的真实实现形态。一、hooks_riverpod 在仓库中的定位1.1 包结构与依赖关系根据 packages/hooks_riverpod/pubspec.yaml当前仓库中的 hooks_riverpod 版本为3.4.3其核心依赖关系是dependencies: flutter: sdk: flutter flutter_hooks: ^0.21.0 flutter_riverpod: 3.4.3 riverpod: 3.4.3注意pubspec.yaml末尾的bound_to声明riverpod、flutter_riverpodhooks_riverpod 每个版本都会与 riverpod / flutter_riverpod 保持同版本号同步升级这正是 CHANGELOG 中几乎每个版本都出现 Dependency changes: flutter_riverpod / riverpod upgraded to x.y.z 的根本原因。例如 3.4.3 只是依赖升级版本flutter_riverpod upgraded to 3.4.3、riverpod upgraded to 3.4.3而 3.4.0 则是一次功能大版本。1.2 入口文件hooks 与 riverpod 的融合点packages/hooks_riverpod/lib/hooks_riverpod.dart 是主入口它从src/internals.dart选择性导出了Consumer、ConsumerWidget、ConsumerStatefulWidget、WidgetRef、ProviderScope以及 hooks_riverpod 特有的HookConsumerWidgetHookConsumerStatefulHookConsumerWidget这些类定义在 packages/hooks_riverpod/lib/src/consumer.dart。从源码结构看它们的实现方式是让 Element 同时混入 Riverpod 的ConsumerStatefulElement与 flutter_hooks 的HookElementfinal class _HookConsumerElement extends ConsumerStatefulElement with HookElement { _HookConsumerElement(HookConsumerWidget super.widget); }也就是说HookConsumerWidget本质上是一个「能同时使用 hooks 与 provider 的 ConsumerWidget」——当你的 Widget 既需要useState/useMemoized等 hooks又需要ref.watch时用它替代ConsumerWidget即可。这正是本包区别于flutter_riverpod的唯一但关键的差异点。1.3 两个补充入口legacy 与 miscCHANGELOG 3.0.0 中有一个重要 Breaking changeChangeNotifierProvider、StateProvider、StateNotifierProvider被移出主入口改由 packages/hooks_riverpod/lib/legacy.dart 提供其中导出了StateNotifier、StateController、StateNotifierProvider、StateProvider、ChangeNotifierProvider及其 Family 变体。而 misc.dart 则导出了面向高级定制的类型如ProviderListenable、Override、ProviderTransformer、SyncProviderTransformerMixin以及Family等详见 packages/hooks_riverpod/lib/misc.dart。二、3.x 时代hooks_riverpod 的新能力全景3.4.x 起2.1 3.4.0自定义 ProviderListenable 与listenable 语法3.4.0 是 3.x 中值得关注的功能版本它引入了两类面向扩展的新 API1CustomProviderListenable——CHANGELOG 描述为 a slightly simplified way of making custom provider extensions。它是用来实现「对 provider 的派生/过滤监听」的基类例如你可以用它实现自己的provider.select变体。仓库中 packages/riverpod/lib/src/core/provider_listenable_transformer2.dart 给出了一个完整的WhereT示例继承CustomProviderListenableT, T实现sourcegetter 与createTransformer()配合SyncProviderTransformer2的initState/onEvent回调完成状态转换最后通过扩展方法暴露为ref.watch(provider.where((previous, value) value 0))。同一文件还保留了ProviderTransformer2的pause()/resume()/read()生命周期以及SyncProviderTransformer2用于同步值的派生。2ref.watch(provider.listenable)与pkg:listen——CHANGELOG 原文Added the ability to doValueListenableint listenable ref.watch(counterProvider.listenable). This uses the newpkg:listen.这意味着你可以把任意 provider 转换成一个标准ValueListenable交给不感知 Riverpod 的组件如ValueListenableBuilder消费。底层实现位于 packages/riverpod/lib/src/common/listenable.dart$ObservableValueT继承自_ValueListenable通过result的 setter 在值变化时触发_notifyValue/_notifyError并维护了可重入安全的监听器列表通知期间删除的监听器会被延迟到迭代结束后再真正收缩数组。2.2 3.4.0 同批次的稳定性修复3.4.0 还修复了一批被反复报告的棘手问题对升级者很有参考价值markNeedsBuild异常修复 markNeedsBuild exception when flushing a provider inside Widget lifecycle并修复ConsumerState.dispose抛错导致的监听器泄漏Fixed a listener leak ifConsumerState.disposethrew。这类问题与 Widget 生命周期中 provider 刷新时机相关3.4.0 及后续 3.4.2Fix a different source ofmarkNeedsBuilderror、3.3.2修复 provider 恢复/销毁调度时的断言都持续在处理。作用域内 invalidate 失效修复从带 overrides 的 scopedProviderContainer/ProviderScope调用invalidate/refresh时若 provider 从未在该作用域内被读过则找不到 provider/family 的问题thanks to itsUndefined。SyncProviderTransformerMixin被弃用由新 API即CustomProviderListenableProviderTransformer2体系取代。devtool 增强对带多个 overrides 的 scoped provider 提供更好的 devtool 支持analyzer约束升级到15.0.0。2.3 3.3.2-dev.1监听、失效转发与调试能力虽然这是 dev 版本但它引入了不少被 3.4.x 沿用的能力Ref.onManualInvalidation()监听手动失效refresh/invalidate/invalidateSelf与依赖变更引起的自动失效区分开。更关键的是回调内可以把失效转发给其他 providerCHANGELOG 给出的完整示例final sourceProvider ProviderString(...); final derivedProvider Provider((ref) { final thing ref.watch(sourceProvider); ref.onManualInvalidation(() { ref.invalidate(sourceProvider); }); return $thing is derived!; }); ref.invalidate(derivedProvider); // also invalidates sourceProvider!这意味着调用方只需失效关心的 provider实现细节可以在内部私下转发处理thanks to TekExplorer。ProviderContainer.allProviders()获取该容器可达的全部 provider可通过allProviders(family: myFamily)限定到某个 family。新增多项ProviderObserver生命周期方法.future在AsyncValue未变化时不再错误通知监听器。devtool 侧新增debugTrackProviderCreation设为true后可让 devtool 跳转到 provider 定义处。2.4 3.2.x 与 3.1.x状态保真与同步组合3.2.0修复了 Notifiers losing their state when one of their dependencies changedthanks to yegair以及ref.mounted对过期 ref 误返回true曾引发异步 provider 竞态。API 层面ConsumerWidget改用 TickerMode notifier 判断可见性以减少不必要的重建为WidgetRef.listen/listenManual补齐缺失的weak标志新增Ref.isPausedfamily.overrideWith弃用并改名为overrideWith2在 4.0.0 中overrideWith2将重命名为overrideWith升级者需注意。3.1.0引入同步组合异步 provider的新写法在FutureProvider/AsyncNotifier的初始化函数内通过AsyncValue.requireValue直接拿到值做同步运算final sumProvider FutureProvider((ref) { // 注意不是 async AsyncValueint a ref.watch(aProvider); AsyncValueint b ref.watch(bProvider); // 仅当用于 provider 的 init 函数内才是安全的 return a.requireValue b.requireValue; })另新增Override.origin可获知 override 关联的是哪个 provider并修复AsyncLoading.isRefreshing/isReloading回归。三、3.0.0稳定版背后的系统性重构3.1 版本定位与实验特性声明CHANGELOG 明确写道 Finally, a stable release for Riverpod 3.0!并称 3.0.0 是 a transition version为解锁后续开发未来可能较快发布 4.0.0。3.0.0 的四个主题词是Offline 与 mutation 支持作为实验特性自动重试automatic retry暂停/恢复pause/resumeAPI 简化如合并AutoDisposeNotifier/Notifier同时给出了关于实验特性的重要提示凡是通过package:riverpod/experimental/....dart导入的功能均不稳定可能在没有 major version 的情况下以破坏性方式修改。hooks_riverpod 包中也同步存在 packages/hooks_riverpod/lib/experimental/mutation.dart 与 persist.dart 两个实验入口与这一声明对应。3.2 必须关注的 Breaking Changes 清单3.0.0 的破坏性变更数量庞大升级时建议逐条对照。按 CHANGELOG 原文整理如下类别变更内容迁移指引入口调整ChangeNotifierProvider、StateProvider、StateNotifierProvider移出主入口改用package:hooks_riverpod/legacy.dart见上文 1.3 节失败重试失败的 provider 在延迟后自动重试延迟可配置无需改动即获得新行为可用ProviderContainer.defaultRetry覆盖默认实现值比较所有 provider 用比较新旧值来过滤更新需要旧行为时在 Notifier 内重写updateShouldNotifyautoDispose 语法Provider.autoDispose()改为Provider(isAutoDispose: true)family 同理统一为构造参数Observer 签名ProviderObserver方法改为接收ProviderObserverContext参数替代旧的providercontainer参数Ref 简化删除全部Ref子类如FutureProviderRef直接用RefFutureProviderRef.future迁移到AsyncNotifier生命周期Notifier 及其变体在 provider 重建时会被重新创建用Ref.mounted判断 dispose监听语义所有 provider 只有在全部监听者含间接都被暂停时才视为 paused影响StreamProvider的StreamSubscription暂停策略错误包装ref.watch/ref.read重抛错误时包装为ProviderException处理错误时注意异常类型变化值语义AsyncValue.value在错误态返回null移除valueOrNull使用.value弱监听新增ref.listen(..., weak: true)不触发 provider 初始化适合只想响应变化、不想发网络请求的场景3.3 3.0 新增的核心能力Ref.mounted判断 provider 是否已被销毁简化异步 provider 中的竞态处理当 provider 重建时会创建新的Ref避免旧的 build 继续执行任务。ProviderContainer.test()专为测试设计的构造函数意图取代旧的createContainer工具。provider.overrideWithBuild(...)只 mockNotifier.build而不 mock 整个 Notifier 对象。ProviderSubscription.pause()/resume()临时暂停对 provider 的订阅配合 autoDispose 时不会丢失状态。ref.invalidate(provider, asReload: true)支持以重载语义失效 provider。AsyncValue.progress字段provider 可设置进度值供 UI 展示自定义进度逻辑。StreamProvider暂停策略未活跃监听时暂停StreamSubscription异步 provider 重建时不再立刻断开旧订阅而是等重建完成后移除影响 autoDispose 行为见官方 issue 1253 的讨论。ProviderContainer嵌套销毁销毁容器会级联销毁其所有子容器同一ProviderContainer内重复 override 同一 provider 会抛错。所有Ref生命周期如ref.onDispose与Notifier.listenSelf改为返回移除监听的函数。新增AsyncValue.retrying判断重试是否已调度/进行中与MutationState.isPending/isIdle/hasError/isSuccess3.0.0-dev.17。四、2.x 时代的关键演进3.0 之前的铺垫4.1 2.6 / 2.5向统一Ref过渡2.6.0弃用了所有Ref子类与Ref的泛型参数建议直接用Ref任何依赖泛型的成员如Ref.state、Ref.listenSelf改用Notifier并新增Notifier.listenSelf作为替代。Ref.watch等成员开始接受 autoDispose provider。2.5.1弃用ProviderScope.parent官方认定其fundamentally not workingref.invalidate在 provider 不再被使用时会正确清理其全部资源修复selectAsync偶发永不 resolve 的问题。4.2 2.4 / 2.3生命周期与容器行为修正container.exists(provider)开始检查父容器的嵌套情况多根ProviderContainer/ProviderScope并存的异常被修复异步 provider 的异常现在能被ProviderObserver.providerDidFail正确接收。2.4.6 修复ProviderScope以不同key重建时的异常——如果你在应用根部给ProviderScope传了key值得留意这条。4.3 2.3 / 2.2 / 2.1流式能力与实用工具2.3.0新增StreamNotifierStreamNotifierProvider配合 riverpod_generator 写riverpod class Example extends _$Example { StreamModel build() {...} }即可在暴露流的同时修改流同时弃用StreamProvider.stream推荐改用ref.listen(provider, ...)或FutureProviderref.watch(b.future)的替代写法。dependencies参数限制放宽不再必须包含那些自身未声明dependencies的 provider。2.1.0是工具性小版本新增provider.overrideWith、FutureProviderRef.future、Ref.notifyListeners()、Ref.exists、AsyncValue.when(skipLoadingOnReload/skipLoadingOnRefresh/skipError)与AsyncValue.requireValueFutureProvider/StreamProvider在回到 loading 时会保留上一个 data/errorAsyncLoading可携带旧值。4.4 2.0.0统一交互语法的里程碑2.0.0 完成了 1.x 遗留的 API 统一弃用useProvider全面转向HookConsumerWidgetref.watch下文 5.2 有完整前后对照。新增WidgetRef.context、WidgetRef.listenManual在 build 之外监听 provider、ref.listenSelf、container.invalidate(provider)/ref.invalidate(provider)/ref.invalidateSelf()。新增ref.onAddListener/ref.onRemoveListener/ref.onCancel/ref.onResume生命周期以及AutoDisposeRef.keepAlive()取代maintainState。新增cacheTime/disposeDelay配置2.0.0-dev 系列cacheTime保证 autoDispose provider 在未被监听时至少存活一段时间disposeDelay则配置不再被监听后多久才真正销毁。AsyncValue家族扩充hasError、hasData、asError、isLoading、copyWithPrevious、unwrapPrevious、valueOrNull。最低 SDK 要求Dart 2.17.0、Flutter 3.0.0。五、1.x 及更早hooks 集成从何而来5.1 0.x 时代hooks_riverpod 的诞生0.1.0为初始版本0.6.0完成Computed与Provider的合并所有 provider 都能监听依赖并重建并把ProviderStateOwner重命名为ProviderContainer。0.7.0加入ConsumerWidget与新的Consumer(builder: (context, watch, child))签名。0.13.0是稳定 null-safety 版本弃用import hooks_riverpod/all.dart一切改由hooks_riverpod/hooks_riverpod.dart提供并放开 watch 只能在 build 内使用 的断言使其能在ListView.builder内使用。0.14.0更新StateNotifierProvider语法泛型从StateNotifierProviderMyStateNotifier变为StateNotifierProviderMyStateNotifier, MyModel读取时用watch(provider.notifier)拿 notifier、watch(provider)拿状态。5.2 1.0.0useProvider正式谢幕1.0.0含 dev 系列是 API 收敛的冲刺阶段其中对 hooks 用户影响最大的迁移是useProvider→HookConsumerWidget// 之前 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); ... } }同一批次还新增了ConsumerStatefulWidgetConsumerState、StatefulHookConsumerWidgetStatefulWidget ConsumerWidget HookWidget 三合一见 1.0.0-dev.11并让所有watch支持provider.select(...)过滤重建。1.0.0 同时宣告 Riverpod is now stable!最低 SDK 提升到 Dart 2.14.0ProviderContainer.debugProviderValues移除、改用getAllProviderElements。六、升级实战建议基于 CHANGELOG 的观察先看版本号绑定关系hooks_riverpod 与 riverpod、flutter_riverpod 严格同版本发布见 pubspec.yaml 的bound_to升级时三者必须一致仓库内test/version_test.dart见 packages/hooks_riverpod/test正是用来校验这类版本一致性的测试。3.0 → 3.4 是渐进路线3.0.0 完成重构后3.1.0~3.4.3 主要是补 APIrequireValue同步组合、listenable、CustomProviderListenable、onManualInvalidation、allProviders与修markNeedsBuild一类生命周期难题。如果你正卡在某个markNeedsBuild/状态丢失的疑难杂症上优先检查是否处于 3.4.0 之前的版本。为 4.0 提前做准备family.overrideWith2将在 4.0.0 更名为overrideWith3.0.0 官方也提示 4.0 可能较快到来。新代码建议直接使用新写法如Provider(isAutoDispose: true)、统一Ref减少日后迁移成本。实验特性要隔离使用offline / mutationexperimental/persist.dart、experimental/mutation.dart属于不稳定 API可破坏性变更而不升大版本生产代码应谨慎引入。充分利用测试设施3.0 起可用ProviderContainer.test()替代createContainer配合provider.overrideWithBuild(...)精准 mock 单个 Notifier 的buildhooks_riverpod 还提供RiverpodWidgetTesterX从 hooks_riverpod.dart 的导出列表可见便于在 Widget 测试中定位ProviderContainer。附本文引用的仓库文件速查主变更记录packages/hooks_riverpod/CHANGELOG.md包配置与依赖绑定packages/hooks_riverpod/pubspec.yaml主入口与 hooks 融合实现packages/hooks_riverpod/lib/hooks_riverpod.dart、packages/hooks_riverpod/lib/src/consumer.dartlegacy / misc 入口packages/hooks_riverpod/lib/legacy.dart、packages/hooks_riverpod/lib/misc.dart底层实现佐证packages/riverpod/lib/src/core/provider_listenable_transformer2.dart、packages/riverpod/lib/src/common/listenable.dart实验特性入口packages/hooks_riverpod/lib/experimental/persist.dart、packages/hooks_riverpod/lib/experimental/mutation.dart赞分享前端移动开发【免费下载链接】riverpodA reactive caching and>项目地址https://gitcode.com/gh_mirrors/ri/riverpod点击查看免费下载相关推荐Riverpod 3.x 版本演进全解读从 CHANGELOG 看 Riverpod 的核心 API 变迁与实战迁移Riverpod 3.x 版本演进全解读从 CHANGELOG 看 Riverpod 的核心 API 变迁与实战迁移 Riverpod 是一个响应式缓存与数据前端移动开发Flutter camera 插件版本演进全解析从 CHANGELOG 看架构变迁与 API 发展史Flutter camera 插件版本演进全解析从 CHANGELOG 看架构变迁与 API 发展史 camera 是 Flutter 团队官方维护的相机插件移动开发跨平台react-select 3.x 版本演进全解析从 docs 包 CHANGELOG 看 classNames、ariaLiveMessages 与 Emotion v11 迁移react select 3.x 版本演进全解析从 docs 包 CHANGELOG 看 classNames、ariaLiveMessages 与 EmotUI组件前端上一篇Klipper文档生成工具API文档自动更新全攻略下一篇metube部署完全指南Docker与传统方式对比教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考