用途:在 Riverpod 中启用自动销毁(auto dispose),当 Provider 在一帧内没有任何监听者时销毁其状态,从而释放内存并停止不再需要的任务(如网络请求),避免内存泄漏。
启用方式:代码生成模式默认启用,可用 @Riverpod(keepAlive: true) 关闭;手动创建时添加 isAutoDispose: true,例如 Provider.autoDispose(...) 或 FutureProvider.autoDispose(...)。当 Provider 带有参数(family)时,应启用自动销毁,以免缓存所有参数组合导致内存泄漏。
销毁时机:Riverpod 统计来自 ref.watch、ref.listen 等的监听者数量,当数量归零后等待一帧,若仍为零则执行 ref.onCancel,随后销毁状态并运行 ref.onDispose。
相关 API:用 ref.onDispose 注册销毁回调(如关闭 StreamController),可多次调用,但不要在 onDispose 内触发修改其他 Provider 的副作用;ref.onCancel 在最后一个监听者移除时运行,ref.onResume 在取消后新增监听者时运行。用 ref.invalidate(provider) 可强制销毁当前状态,若仍有监听者则重新计算,否则保持销毁直到再次被读取。用 ref.keepAlive() 可在自动销毁启用时阻止销毁直到下次重新计算,返回值可调用以恢复自动销毁;若 Provider 被重新计算,自动销毁会重新启用。
限制:Riverpod 没有内置的“缓存 X 秒”功能,可借助 Timer 配合 ref.keepAlive,或用 ref.onCancel/onResume 在无监听者一段时间后销毁来实现。