エフェクト

@Effect のメソッドは、Bean が作られたときに一度実行され、読んだものが変わるたびに再び実行されます。自分の Bean や別の Bean の、フィールドまたは計算された値です。

使う理由

求められなくても状態に従う仕事があります。バスケットが変わったら保存する、価格を計算し直す、などです。手で書くと、追加し、取り除き、メソッドが実際に読むものと合わせ続けるリスナーになります。エフェクトは、読んだものに従います。

例

@Effect()                          // items が変わるたびに再び実行される
void save() => storage.write(items);
@Effect()
void recalc() {
  final user = untracked(() => session.user);   // 読むが、追跡されない
  price = pricing.of(basket.items, user);        // basket.items のためにだけ実行される
}

ルール

エフェクトが実行される時

エフェクトは、読んだものが代入されるとただちに実行されます。代入したメソッドの終わりであり、後のフレームではありません。そのため、basket.add(book) が戻ったとき、save はすでに実行されています。

例外を投げるエフェクト

例外を投げるエフェクトは、それを実行させた代入を失敗させません。エラーは報告され (ChangeNotifier のリスナーと同じく FlutterError.reportError)、フィールドは新しい値を保ち、代入したコードはそのまま進み、エフェクトは追跡していたものの次の変化でまた実行されます。Bean が作られるときの最初の実行で例外を投げると、Bean は作られません。

例外を投げる @Computed ゲッターは、投げた例外そのもので読み手を失敗させます。失敗は保持されません。次に読むときに、もう一度計算されます。

エフェクトは、読んだものに代入してもかまいません (値を範囲内に保つためなど)。何も変わらなくなるまで、もう一度実行されます。

メソッドは一つの変化

このようなメンバーを持つ Bean のメソッドは、何を代入しても、一つの変化です。

void clear() {
  items.clear();
  coupon = null;
}                    // 読み手には、戻るときに一度だけ伝えられる

両方を読むエフェクトは一度だけ実行され、二つの間の状態を見ることはありません。両方を読むウィジェットは、一度だけ再構築されます。追跡されるフィールドではないセッターも、一つの変化です。

非同期のメソッドは、最初の await までが一つの変化です。その後は、代入ごとに別の変化になります (まとめて伝えるには batch で包みます)。例外を投げるメソッドも、代入したものを一度だけ伝え、エラーは呼び出し元に届きます。

外からの複数の呼び出しには、batch(() { ... }) が同じ働きをします。

batch(() {
  basket.add(dune);
  basket.apply('TEN');
});

batch と untracked は、スターターが signals_core から再エクスポートする二つの関数です。

トランザクションやほかのアドバイスと一緒に

追跡される状態を持つ Bean には、ほかのアドバイス (@Transactional、@Cacheable、アスペクト) も付けられます。どちらも、一つのプロキシの中で実行されます。

@Service()
class Checkout {
  @Signal()
  OrderStatus status = OrderStatus.open;

  @Transactional()
  Future<void> pay(Order order) async {
    await orders.save(order);
    status = OrderStatus.paid;     // 失敗するかもしれない処理の後で
  }
}

状態を追跡するアドバイスは、既定の順序のアドバイスすべての外側にあります。それより前の順序を持つアドバイス (メソッドセキュリティ、@Order を付けたアスペクト) はその外側にあり、読むたびに実行されます。

関連項目