riverpod-consumers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Riverpod — Consumers

Instructions

说明

Consumers are widgets that give you a Ref (here, WidgetRef) so you can read and listen to providers. Without a Consumer, widgets cannot access the provider tree.

Consumers是一类组件，它会为你提供一个Ref（此处为WidgetRef），让你可以读取和监听providers。如果没有Consumer，组件将无法访问provider树。

Consumer (builder)

Use

Consumer

when you want to keep extending

StatelessWidget

StatefulWidget

. The builder callback receives

(context, ref, child)

dart

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Consumer(
      builder: (context, ref, _) {
        final value = ref.watch(myProvider);
        return Text(value.toString());
      },
    );
  }
}

如果你希望继续继承

StatelessWidget

或

StatefulWidget

，可以使用

Consumer

。builder回调会接收

(context, ref, child)

参数。

dart

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Consumer(
      builder: (context, ref, _) {
        final value = ref.watch(myProvider);
        return Text(value.toString());
      },
    );
  }
}

ConsumerWidget

Subclass

ConsumerWidget

instead of

StatelessWidget

. The

build

method receives

(BuildContext context, WidgetRef ref)

dart

class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final value = ref.watch(myProvider);
    return Text(value.toString());
  }
}

继承

ConsumerWidget

来替代

StatelessWidget

。其

build

方法会接收

(BuildContext context, WidgetRef ref)

参数。

dart

class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final value = ref.watch(myProvider);
    return Text(value.toString());
  }
}

ConsumerStatefulWidget + ConsumerState

When you need a

State

(e.g. for lifecycle or local state), use

ConsumerStatefulWidget

and

ConsumerState

. The state object has a

ref

property.

dart

class MyWidget extends ConsumerStatefulWidget {
  @override
  ConsumerState<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends ConsumerState<MyWidget> {
  @override
  Widget build(BuildContext context) {
    final value = ref.watch(myProvider);
    return Text(value.toString());
  }
}

当你需要使用

State

（例如处理生命周期或本地状态）时，可以使用

ConsumerStatefulWidget

和

ConsumerState

。状态对象会拥有一个

ref

属性。

dart

class MyWidget extends ConsumerStatefulWidget {
  @override
  ConsumerState<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends ConsumerState<MyWidget> {
  @override
  Widget build(BuildContext context) {
    final value = ref.watch(myProvider);
    return Text(value.toString());
  }
}

Which to use

如何选择

Consumer — Use for everything if you prefer not to change your widget base class; slightly more verbose.
ConsumerWidget — Recommended when you don't need State; one less nesting level.
ConsumerStatefulWidget — Use when you need State (e.g. TabController, animations).

Consumer — 如果你不想更改组件的基类，可用于所有场景；写法略为繁琐。
ConsumerWidget — 当你不需要State时推荐使用；减少一层嵌套。
ConsumerStatefulWidget — 当你需要State时使用（例如TabController、动画等场景）。

Why not StatelessWidget + context.watch?

为什么不使用StatelessWidget + context.watch？

Riverpod does not use

BuildContext

to watch providers because that would break auto-dispose and other features that rely on knowing when a widget stops listening. Ref-based consumers allow reliable disposal and correct behavior. The hooks_riverpod package also offers HookConsumerWidget etc. for use with flutter_hooks. Enable riverpod_lint for IDE refactors (e.g. "Convert to ConsumerWidget").

Riverpod不使用

BuildContext

来监听providers，因为这会破坏**自动销毁（auto-dispose）**以及其他依赖于知晓组件何时停止监听的特性。基于Ref的消费者组件可以实现可靠的资源销毁和正确的行为。hooks_riverpod包还提供了HookConsumerWidget等组件，可与flutter_hooks配合使用。启用riverpod_lint插件可支持IDE重构（例如“转换为ConsumerWidget”）。