Integração Flutter com propriedade explícita do container.

ProviderScope pode ser dono de um container ou recebê-lo externamente. As APIs de Consumer mantêm o acesso a WidgetRef compatível com código no estilo Riverpod.

Abrir testes Ler mutações

Propriedade do ProviderScope

A propriedade do container altera a responsabilidade pela liberação.

Container interno

ProviderScope(child: ...) é descartado automaticamente

Container externo

ProviderScope(container: c, ...) exige c.dispose() pelo chamador

Escopo sem controle

UncontrolledProviderScope nunca descarta o container

Armadilha comum

Nos testes de widget, lembre-se de descartar o ProviderContainer injetado externamente para evitar vazamentos de timers pendentes.

Variantes de Consumer

Todas as opções expõem WidgetRef; escolha conforme o estilo do widget e as necessidades de estado local.

Raiz do app

Quando usar cada um

Consumer: local builder block for small reactive areas.
ConsumerWidget: stateless widget with build(context, ref).
ConsumerStatefulWidget: stateful widget with ref inside ConsumerState.

Exemplo: ConsumerStatefulWidget

Use ConsumerState quando precisar de WidgetRef e também de um estado local mutável da interface.

class HomePage extends ConsumerStatefulWidget {
  const HomePage({super.key});

  @override
  ConsumerState<HomePage> createState() => _HomePageState();
}

class _HomePageState extends ConsumerState<HomePage> {
  bool expanded = false;

  @override
  Widget build(BuildContext context) {
    final user = ref.watch(currentUser);
    return Column(
      children: [
        Text('$user'),
        Switch(
          value: expanded,
          onChanged: (v) => setState(() => expanded = v),
        ),
      ],
    );
  }
}

O funcionamento interno do Consumer agenda as reconstruções para depois do frame, reduzindo problemas de setState durante a construção.

Use WidgetRef.watch apenas para valores que devem disparar reconstruções.

Mantenha efeitos colaterais fora do build; use callbacks e métodos invoke/refresh.

Próximos passos

Testes

Valide o ciclo de vida do container, as substituições e as atualizações assíncronas em testes unitários e de widget.

Abrir testes

Referência da API

Veja as assinaturas de ProviderScope, WidgetRef e métodos do container.

Abrir referência da API