
# 非同期の状態

`Future` や `Stream` を返す `@Computed` ゲッターは、非同期の状態です。リクエストは、値が最初に読まれたときに行われ、それが依存するものが変わると、もう一度行われます。

## 使う理由

読み込んだデータを表示する画面は、三つのものを手で保持します。データ、読み込みが実行中かどうか、最後のエラーです。そして、フィルターが変わればもう一度求め、前のリクエストの応答を捨てなければなりません。ここでは、ゲッターがリクエストであり、残りはそこから決まります。

## 例

```dart
@Component()
class Catalog {
  Catalog(this.client);

  final CatalogClient client;

  @Signal()
  String genre = 'fiction';

  @Computed()
  Future<List<Book>> get books => client.byGenre(genre);
}
```

## 振る舞い

- リクエストは、`books` が最初に読まれたときに行われます。`genre` が代入されるまで、すべての読み手が同じ Future を受け取ります。代入されると、別のリクエストが行われます。
- コードの中では、普通の Future です: `final books = await catalog.books;`。
- より新しいリクエストが行われた後に届いた応答は、捨てられます。
- 失敗は状態であり、ウィジェットの中に投げられる例外ではありません。

## 状態

状態は、ゲッターが返したものの拡張です。`catalog.books.state` で、`AsyncValue<List<Book>>` です。

| `AsyncValue<T>` のメンバー | 意味 |
|---|---|
| `isLoading` | 読み込みが実行中かどうか。最初の読み込み、または `refresh()` |
| `hasValue` | 値があるかどうか。この読み込みの値、または別の読み込みの実行中や失敗の後に保持されている最後の値 |
| `value` | 値。なければ `null` |
| `requireValue` | 値。読み込みが値なしで失敗したときはそのエラーを投げ、最初の読み込みの実行中は `StateError` を投げる |
| `error`、`stackTrace`、`hasError` | 最後の読み込みが投げたもの |
| `isRefreshing` | 最後の値がまだ表示されている間に、読み込みが実行中かどうか |
| `when(data: ..., loading: ..., error: ...)` | 三つのうちの一つ。値があれば `data` (リフレッシュ中も)、なければ `error`、それもなければ `loading` |

```dart
final state = catalog.books.state;
return state.when(
  data: (books) => BookList(books),
  loading: () => const Spinner(),
  error: (error, _) => Text('$error'),
);
```

ウィジェットの `build` (Spring のウィジェット、`Watch`、`AsyncView`) の中で読むと、状態が動いたときにウィジェットが再構築されます。

`state` は、コンテナーが渡す Bean の `@Computed` ゲッターの値のためのものです。それ以外の Future では、そのことを伝える `StateError` を投げます。

## もう一度求める

| 呼び出し | 働き |
|---|---|
| `catalog.books.refresh()` | もう一度求め、その間は最後の値を画面に保つ (`isRefreshing`) |
| `catalog.books.reload()` | 何もない状態からもう一度求める。その間、状態は `loading` |

どちらも、新しい応答が届いたときに完了します。値が依存するものの変化 (`genre` の代入) も、何もない状態から始まります。

## Stream

`Stream` も同じです。

```dart
@Computed()
Stream<double> get price => client.prices(genre);
```

`catalog.price.state` は、その最後のイベントです。最初のイベントの前は `loading`、その後は `data`、またはエラーです。新しいジャンルは、新しい Stream を与えます。スターターが自分で Stream を聞くので、単一購読の Stream を二度目に聞いてはいけません。

## 依存するものは最初の await の前に読む

**値が依存するものは、最初の `await` の前に読まなければなりません。** `await` の後は、何も追跡されません。これはシグナルの仕組みであり、スターターの制限ではありません。

```dart
@Computed()
Future<List<Book>> get books async {
  final genre = this.genre;                 // 先に読む: 追跡される
  final token = await auth.token();
  return client.byGenre(genre, token);      // ここでの `this.genre` は追跡されない
}
```

ビルドはこれをチェックしません。`await` の後に読んだフィールドはコンパイルされ、そのフィールドが変わっても値は読み込み直されません。

## 表示する

`AsyncView` は、データ、読み込み、または失敗を表示します。[ウィジェットの中で](widgets.md#asyncview) を参照してください。

## 関連項目

- [ウィジェットの中で](widgets.md)
- [フィールドと計算された値](fields-and-computed.md)
- [ビルドがチェックするもの](build-checks.md)
