【Riverpod】プロバイダーの読み取りのref.xxxを整理して解説

はじめに

皆さん、こんにちは。

Riverpodを学ぶ上で、refを介したプロバイダーの読み取りは最も重要な概念です。しかし、ref.watch、ref.read、ref.listen、そしてselectといった複数のメソッドがあり、それぞれの使い分けに戸惑うこともあるでしょう。この記事では、公式ドキュメントの内容を基に、これらのメソッドの役割と正しい使い方を具体的なコード例を交えて解説します。

サンプルコード

https://github.com/peter-norio/flutter/tree/main/riverpod_watch_sample

ConsumerWidgetを継承してref を使えるように

概要

• Providerを読み取るウィジェットはConsumerWidgetを継承して
• buildメソッドのWidgetRef型引数（ref）を利用する
• Providerの読み取り以外はStatelessWidgetと同じ
• Flutter Riverpod Snippetsでは「stlessConsumer」で雛形

プロバイダーの値を読み取るウィジェットを作成するには、ConsumerWidgetを継承するのが一般的な方法です。

ConsumerWidgetを継承するとbuildメソッドの引数としてWidgetRef型のrefを受け取ります。このrefを通じて、プロバイダーの値をref.watch()、ref.read()、ref.listen()などのメソッドを使います。

ConsumerWidgetは、プロバイダーの読み取り機能を除けば、StatelessWidgetとほとんど同じように記述できます。

Flutter Riverpod Snippets（VS Code拡張機能）を使っている場合は、「stlessConsumer」と入力するだけで、ConsumerWidgetの基本的な雛形が自動生成されます。

例（雛形のまま）

class MyConsumer extends ConsumerWidget {
  const MyConsumer({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // buildメソッド内でrefを使ってProvierを読み取る
    return Container();
  }
}

https://riverpod.dev/ja/docs/concepts/reading#ウィジェットから-ref-を取得する

ref.readでその場限りの利用

概要

• 最もシンプルな読み取り方法
• 現在の状態を一度だけ取得し更新を監視しない
  • 「その場限り」での利用に収めること
  • buildメソッドの直下では利用しないこと
• UIに反映させる必要のないデータを読み取る
• 主にNotifier（更新処理の呼び出し）の参照で利用する

ref.readはプロバイダーの最もシンプルな読み取り方法です。readでの読み取りはプロバイダーの現在の状態を一度だけ取得し、その後の更新を監視しません。

この特性から、ref.readは「その場限り」での利用に留めるべきです。例えば、ボタンのonPressedコールバック内で、その瞬間のデータ値（状態に保存したユーザ名とパスワード等）を取得したり、Notifierのインスタンスを参照して更新処理を呼び出す際に主に利用します。

ElevatedButtonで状態更新処理を行う例

ElevatedButton(
  onPressed: () {
    // 状態更新をメソッドチェーンで
    ref.read(counterProvider.notifier).increment();
  },
  child: Text('+'),
),

例

class MyConsumer extends ConsumerWidget {
  const MyConsumer({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // このようにbuildの直下でのreadはアンチパターン
    // final currentCount = ref.read(counterProvider);
    // final counter = ref.read(counterProvider.notifier);

    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            Text('$counter'),
            SizedBox(width: 10),
            ElevatedButton(
              onPressed: () {
                // 処理内での一次的な値の利用なので推奨される書き方
                final currentCount = ref.read(counterProvider);
                // 更新１：状態更新の呼び出しなので推奨される書き方
                final counter = ref.read(counterProvider.notifier);
                counter.increment();
                // 更新２：状態更新はメソッドチェーンの以下でもOK
                ref.read(counterProvider.notifier).increment();
              },
              child: Text('+'),
            ),
          ],
        ),
      ],
    );
  }
}

https://riverpod.dev/ja/docs/concepts/reading#refread-を使ってプロバイダのステートを取得する

公式ではアンチパターンとして次の言及があります。

• 可能な限りreadの利用は避け、watch を使う
• buildメソッドの直下でreadで読み取った結果を保持しない

公式では次のように言及されています。

readではなく、できる限りwatchメソッドを使うこと

ref.read はリアクティブではないため、可能な限り使用を避けてください。

watch や listen の使用では問題が生じる場合の回避策として存在しています。 ほとんどの場面では watch や listen の使用、特に watch の使用がベターなはずです。

buildメソッド内でread を使った読み取りをしないこと

ソフトウェアに変更はつきものです。そして将来、絶対に変わらないと考えられていた値が、変わる必要に迫られることは十分あり得ることです。 そしてもしこの値の取得に ref.read が使われていたら、その時にはコードを振り返り ref.read が使われているところをすべて ref.watch に変更する必要があります。これはエラーを招くおそれがありますし、変更し忘れる箇所がいくつか出てくる可能性もあります。

一方、最初から ref.watch を使用していれば、リファクタリング時に生じる問題は比較的少ないはずです。

これらは共通の話をしていると推測します。buildメソッド直下はそのウィジェット全体で利用可能なスコープであるため、UIの挙動を管理するリアクティブな値をおくべきであると考えられます。

そのためbuild メソッドの直下ではread ではリアクティブ性がなく不適格となります。また、プロバイダーが提供する値がリアクティブな状態でなかったとしてもwatch で読み取るようにすることで、今後状態の扱いがリアクティブに仕様変更されたとしてもコードの変更を少なく対処可能であるとも言及されています。

簡単にまとめてしまうと、ref.read の記述は操作に対応したコールバック内であれば推奨の書き方と考えることができます。

https://riverpod.dev/ja/docs/concepts/reading#重要-refread-は-build-メソッドの中で使わない

ref.watchで変更を監視してUIに反映

概要

• プロバイダーを読み取りリアクティブな値（状態）を取得
• 状態の変更を監視し、変更に伴いUIを自動更新
• 値（状態）の読み取りはできるだけwatch を使う

ref.watchは、最も基本的でかつ推奨される読み取り方法です。ref.watchは単に現在の値を取得するだけでなく、状態の変更を監視し、変更に伴ってUIを自動的に更新する「リアクティブな値」を取得します。

例えば、カウンターアプリの画面に現在の数字を表示する場合、ref.watchを使ってカウンターのプロバイダーを監視します。カウンターの値が増えるたびに、ref.watchがその変更を検知し、カウンターの数字を表示しているウィジェットだけを自動的に再構築してくれるため、常に最新の数字が画面に反映されます。

このため、UIに表示するデータや、UIの振る舞いを決定するような状態を扱う際は、できるだけref.watchを使うことが推奨されます。

例

class MyConsumer extends ConsumerWidget {
  const MyConsumer({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 状態の読み取り
    final counter = ref.watch(counterProvider);
    final hello = ref.watch(helloProvider);
    // このように静的な値でもreadで読み取るのはアンチパターン
    // final hello = ref.read(helloProvider);

    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        // 値の利用は通常の変数と同じ
        Text('$counter'),
        Text(hello),
      ],
    );
  }
}

https://riverpod.dev/ja/docs/concepts/reading#refwatch-を使ってプロバイダを監視する

静的なプロバイダーでもUIに利用する値ならばref.watchで読み取るべきとされています。

公式では次のように言及されています。

「プロバイダが公開する値が変わることはない。だから ref.read の使用は安全である」。 しかし、そのプロバイダは今は値が変わることがないかもしれませんが、明日も同じことが言えるとは保証できません。 その点でこの推測には問題があると言えます。

ソフトウェアに変更はつきものです。そして将来、絶対に変わらないと考えられていた値が、変わる必要に迫られることは十分あり得ることです。 そしてもしこの値の取得に ref.read が使われていたら、その時にはコードを振り返り ref.read が使われているところをすべて ref.watch に変更する必要があります。これはエラーを招くおそれがありますし、変更し忘れる箇所がいくつか出てくる可能性もあります。

一方、最初から ref.watch を使用していれば、リファクタリング時に生じる問題は比較的少ないはずです。

将来的に変更が発生する可能性がゼロとは言えないので最初からref.watchを使いましょうということだと考えます。

https://riverpod.dev/ja/docs/concepts/reading#重要-refread-は-build-メソッドの中で使わない

ref.listenで状態更新に伴う副作用

概要

• 状態更新を監視し、任意の関数を実行
• 更新前の値と更新後の値を利用可能
• 状態更新をきっかけにした副作用処理で利用
  • 画面遷移、スナックバー表示、など

ref.listenは、状態更新に伴う副作用を処理するためのメソッドです。プロバイダーの状態更新を監視し、状態が変化するたびにUIの再構築を伴わずに任意の関数を実行できます。

コールバック内では、previous（更新前の値）とnext（更新後の値）の両方を利用することができます。ref.listenの主な用途は、状態更新をきっかけにした副作用処理です。

例えば、ユーザーの認証状態が「ログイン済み」に変わった際に画面遷移を行ったり、フォームの送信結果（成功/失敗）に応じて「保存しました」といったスナックバー表示やエラーダイアログを表示したりなどです。UIとは直接関係ないログ出力やアナリティクスイベントの送信などにも利用できます。

watchがUIの再構築を伴うのに対し、listenはUIとは独立した副作用を実行するために使われます。これにより、UIの描画ロジックと、それに付随する非UI的な処理を明確に分離することができます。

例

class MyConsumer extends ConsumerWidget {
  const MyConsumer({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 状態の読み取り
    final counter = ref.watch(counterProvider);

    // Counterが更新されたら実行したい関数を登録
    ref.listen(counterProvider, (int? pre, int next) {
      print('$pre -> $next changed!');
    });

    return Column( 省略 );
  }
}

https://riverpod.dev/ja/docs/concepts/reading#reflisten-を使ってプロバイダを監視する

プロバイダー.select で状態の一部のみを監視

概要

• watchやlistenの引数をプロバイダー.select(監視対象の指定) にする
• オブジェクトの一部のプロパティのみを監視対象にしたい時に利用
  • オブジェクト全体を監視すると無関係な変更で不必要なUIの再構築が発動してしまう
• パフォーマンス最適化の観点で利用する機能

状態がオブジェクトの場合はref.watch()やref.listen()の引数をプロバイダー.select() とすることで、状態の一部のみを監視対象とすることができます。

オブジェクトを状態としている場合、ref.watch()でそのまま監視すると、無関係なプロパティが変更されただけでも不必要なUIの再構築が発動してしまいます。例えば、ユーザーオブジェクトのageが変わっただけで、nameしか表示していないウィジェットが再構築されるといった事態です。

これを避けるために、ref.watch()やref.listen()の引数に、provider.select((state) => state.property)のように監視したいプロパティを返す関数を指定します。これにより、指定したプロパティの値が変更されたときだけウィジェットが更新されるようになります。

selectは、無駄な再構築を防ぎ、アプリケーションのパフォーマンスを最適化する観点で重要な機能です。

例（Userオブジェクトのnameだけを監視するウィジェット）

class MyConsumer extends ConsumerWidget {
  const MyConsumer({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // Userオブジェクトのnameだけを監視対象にする
    final userName = ref.watch(
      userNotifierProvider.select((user) => user.name),
    );

    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            // Userオブジェクトのnameを利用
            Text(userName),
            ElevatedButton(
              onPressed: () {
　              // 状態の一部を更新する処理の呼び出し
                ref.read(userNotifierProvider.notifier).updateState(newName: '新しい名前');
              },
              child: Text('名前変更'),
            ),
          ],
        ),
      ],
    );
  }
}

例（プロバイダーとUser型の定義）

import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'user.g.dart';

@riverpod
class UserNotifier extends _$UserNotifier {
  @override
  User build() {
    return User(name: 'John', age: 10);
  }

  // 状態の更新
  void updateState({String? newName, int? newAge}) {
    state = state.copyWith(name: newName, age: newAge);
  }
}

// User型
class User {
  String name;
  int age;

  User({required this.name, required this.age});

  // 渡された引数の項目のみ更新した新しいオブジェクトを生成
  User copyWith({String? name, int? age}) {
    return User(name: name ?? this.name, age: age ?? this.age);
  }
}

https://riverpod.dev/ja/docs/concepts/reading#selectを使って更新の条件を限定する

オブジェクトを状態として扱いたい場合はモデルクラスにcopywithメソッドを用意します。

Riverpodの状態更新はstate = 新しい値;のようにstateへの代入によって状態を更新します。そして状態がオブジェクトの場合は新しいオブジェクトとすることで状態の更新が検知されます。

一部のプロパティを更新した新しいオブジェクトを生成するためにcopyWithメソッドを用意します。引数はプロパティに対応した省略可能引数を用意し、戻り値は新しいオブジェクトとします。引数に新しい値が渡されなかったプロパティには既存の値を利用します。

  // 渡された引数の項目のみ更新した新しいオブジェクトを生成
  User copyWith({String? name, int? age}) {
    return User(name: name ?? this.name, age: age ?? this.age);
  }

プロバイダーはcopyWith を使った状態更新メソッドを提供するようにします。

  // 状態の更新
  void updateState({String? newName, int? newAge}) {
    state = state.copyWith(name: newName, age: newAge);
  }

https://riverpod.dev/ja/docs/providers/state_notifier_provider

freezedを使う場合: このcopyWithメソッドや、toString、==演算子のオーバーライドといった定型コードを、@freezedアノテーションを付けるだけで自動生成してくれます。

https://pub.dev/packages/freezed/example

おわりに

この記事では、Riverpodのrefを介したプロバイダーの読み取り方法について、それぞれの役割と使い分けを詳細に解説しました。

• ref.read: UIに直接反映させる必要のない、その場限りのデータ取得やメソッド呼び出しに使います。buildメソッド直下での使用はアンチパターンです。
• ref.watch: 状態の変化を監視し、UIを自動で更新するための、最も基本的なリアクティブな読み取り方法です。UIに表示するデータには基本的にwatchを使用します。
• ref.listen: 状態変化をトリガーに、UIの再構築を伴わない副作用（画面遷移やスナックバー表示など）を実行するために使います。
• select: オブジェクトの状態の一部のみを監視対象に絞り込み、不要な再構築を防ぐことで、パフォーマンスを最適化します。

これらのメソッドは、それぞれ異なる目的とユースケースを持っています。使い分けを理解し実践することで、Riverpodの持つ強力なリアクティブ性を最大限に活かし、クリーンでパフォーマンスの高いアプリケーションを構築できるようになります。