
# モーションとアニメーション

テーマのモーションには二つの部分があります。`motion` は、名前を付けた**長さ**と**カーブ**、そして**ページのトランジション**を持ちます。`animations` は、自動的に再生される名前付きの**アニメーション**を持ちます。長さ、カーブ、繰り返すかどうかです。

```yaml
spring:
  flutter:
    theme:
      motion:
        page-transition: fade-upwards
        durations:
          fast: 120ms
          medium: 250ms
        curves:
          out: ease-out
          emphasized: [0.2, 0, 0, 1]
      animations:
        border-spin:
          duration: 4s
          curve: linear
          repeat: loop
        glow-pulse:
          duration: 1.6s
          curve: ease-in-out
          repeat: reverse
```

## プロパティ

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `motion.enabled` | bool | `true`、`false` | `true` | `false` はアプリのすべての動きを、端末の「視差効果を減らす」と同じように即座にする: ページのトランジション、テキストとコンテンツの変化、先頭へのスクロール、テーマのアニメーション、Flutter 自身のもの。デバッグパネルの Motion タブは実行時にこれを切り替える |
| `motion.page-transition` | 列挙、またはマップ | `platform`、`fade-upwards`、`zoom`、`cupertino`、`fade`、`content`、`none` | `platform` | すべての画面のページのトランジション。デフォルトは Flutter と同じくアプリの種類固有のもの。`none` はページを即座に切り替える。`zoom` には `spring_boot_starter_flutter_material`、`cupertino` には `spring_boot_starter_flutter_cupertino` が必要 |
| `motion.page-transition.type` / `.duration` / `.curve` | 列挙 / 期間 / カーブ | 上と同じ、`200ms`、カーブの名前 | 種類固有のもの | マップの形: 種類とその長さとカーブ |
| `motion.text-change` | 列挙、またはマップ | `none`、`fade`、`morph` | `none` | 例えば別の言語になって `ThemeText` のテキストが変わるときの動き |
| `motion.text-change.type` / `.duration` / `.curve` / `.stagger` / `.keep-unchanged` / `.glyphs` / `.glyph-duration` | 列挙 / 期間 / カーブ / 期間 / 真偽値 / テキスト / 期間 | 上と同じ、`450ms`、カーブの名前、`12ms`、`true` / `false`、任意の文字、ゼロより長い期間 | `none`、`450ms`、`ease-out`、`12ms`、`false`、`▓▒░<>/\|=+*#%&@$?!01`、`40ms` | マップの形。`stagger` は `morph` の各文字がどれだけ遅れて始まるか。`keep-unchanged` は同じままの文字をその場に残す |
| `motion.overscroll` | `platform`、`none` | | `platform` | スクロール領域を端を越えて引いたときに表示するもの: アプリの種類固有のもの (Android での Material のストレッチ。一瞬コンテンツを歪める)、または何もなし |
| `motion.wheel-scroll` | `none`、または `duration`、`speed`、`inertia` のマップ | | `none` (マップでは `250ms`、`1`、慣性なし) | マウスホイールがすべてのスクロール領域をスクロールする方法: `none` は Flutter と同じくホイールの刻みごとにジャンプする。マップは各刻みを `duration` にわたって滑らかにし、`speed` で倍率をかけ、ポインターの種類ごとに `inertia` を与える ([慣性](#慣性)) |
| `motion.scroll-to-top` | `none`、または `duration` と `curve` のマップ | | `400ms`、`ease-out-cubic` | 画面が別のページを表示するときに先頭に戻る方法 (`RouteContentView`)。`none` はジャンプする |
| `motion.content-change` | 種類、またはマップ | `none`、`fade`、`fade-up`、`morph`、またはアプリ独自の種類 | `none` | 画面の一部が、その場所に別のコンテンツを表示する方法 (`RouteContentView` の別のページ) |
| `motion.content-change.type` / `.duration` / `.curve` | 種類 / 期間 / カーブ | 上と同じ、`200ms`、カーブの名前 | `none`、`200ms`、`ease-out` | マップの形 |
| `motion.content-change.stagger` / `.delay` | 期間 / 期間 | `40ms`、`650ms` | `30ms`、なし | `morph` 用: 各行が前の行よりどれだけ遅れて始まるか、そして新しいページが最初の行の前にどれだけ待つか |
| `motion.durations.<name>` | 期間 | `120ms`、`1.5s`、`2m`、`1h` | `short` 100ms、`medium` 250ms、`long` 450ms | 名前付きの長さ |
| `motion.curves.<name>` | カーブ | カーブの名前、または四つの数値 | `standard` | 名前付きのカーブ |
| `animations.<name>.duration` | 期間 | `4s`、`250ms` | 必須 | 一回の実行にかかる時間 |
| `animations.<name>.curve` | カーブ | カーブの名前、または四つの数値 | `linear` | 一回の実行のカーブ |
| `animations.<name>.repeat` | 列挙 | `none`、`loop`、`reverse` | `none` | 実行の終わりに起きること |

`motion` の中には、`enabled`、`page-transition`、`text-change`、`content-change`、`scroll-to-top`、`wheel-scroll`、`overscroll`、`durations`、`curves` だけが存在します。アニメーションの中には `duration`、`curve`、`repeat` だけが存在します。別のキーは起動を止め、最も近いものを示します。

## ページのトランジション

`motion.page-transition` は、アプリ全体について、画面の入り方と出方を設定します。[`spring_boot_starter_flutter_navigation`](../../spring-boot-starter-flutter-navigation/index.md) のルーターは、どのアプリの種類 (Material、Cupertino、`widgets`) でもこれに従い、Material 自身のページのルートもこれに従います。

`zoom` と `cupertino` はデザインライブラリのものです。`zoom` には [spring_boot_starter_flutter_material](../../spring-boot-starter-flutter-material/index.md) が、`cupertino` には [spring_boot_starter_flutter_cupertino](../../spring-boot-starter-flutter-cupertino/index.md) が必要です。そのスターターが依存関係にあれば、それぞれどの種類のアプリでも動きます。スターターがないテーマでは、起動が失敗し、そのスターターの名前を挙げます。`platform` はアプリのデザインによります。`fade-upwards`、`fade`、`content`、`none` は Flutter のスターター自身のもので、すべてのアプリで動きます。

| 値 | 働き |
|---|---|
| `none` | トランジションなし: 新しいページは即座に表示される |
| `platform` | アプリの種類固有のもの: `MaterialApp` ではプラットフォームごとの Material のもの (`MaterialPageRoutes`)、`CupertinoApp` では iOS のスライド (`CupertinoPageRoutes`)、デザインライブラリのないアプリではなし (デフォルト) |
| `fade-upwards` | 新しいページが少し上にスライドしながらフェードインする |
| `zoom` | 新しいページが中央から大きくなりながらフェードインする (Android 10 のスタイル)。Material のもの: `spring_boot_starter_flutter_material` が必要 |
| `cupertino` | 右からの iOS のスライド。スワイプで戻るジェスチャー付き。どのアプリの種類でも。`spring_boot_starter_flutter_cupertino` が必要 |
| `fade` | 新しいページがフェードインする |
| `content` | 新しいページが、`motion.content-change` が別のコンテンツを表示するのと同じように入ってくる (`fade-up`、アプリ独自の種類)。マップの形で指定しない限り、その期間とカーブを使う。サイトの画面がそのページと同じように変わる |

デフォルトでは、Flutter と同じく、画面はアプリの種類固有のルートと同じように入ってきます (`platform`)。どのアプリの種類でもページを即座に切り替えるには:

```yaml
spring:
  flutter:
    theme:
      motion:
        page-transition: none
```

または一つを選んで調整します。マップの形は種類にその長さとカーブを与え、それはテーマ自身のもの (`$motion.durations.fast`) を参照できます。

```yaml
spring:
  flutter:
    theme:
      motion:
        durations: { fast: 150ms }
        page-transition: { type: fade, duration: $motion.durations.fast, curve: ease-out }
      themes:
        cinema:
          motion:
            page-transition: zoom      # spring_boot_starter_flutter_material が必要
```

`themes.<name>` のテーマは独自のものを選べます。テーマの切り替えは次のナビゲーションに適用されます。デバイスで視差効果を減らす設定が有効なら、すべてのトランジションは即座になります。一つの画面も独自のものを選べ (`@ScreenRoute(transition: PageTransition.none)`)、一回のナビゲーションもそうできます (`context.route.go(path, transition: PageTransition.none)`)。ナビゲーションのスターターを参照してください。スターターのない画面独自の `zoom` や `cupertino` は、そのスターターの名前とともにログに出され、ページはトランジションなしで表示されます。

### Flutter との共通点と違い

Flutter では、トランジションを選ぶのはルートで、ルートのクラスを選ぶのはそれぞれの `Navigator.push` です。

| アプリ | Flutter のトランジション |
|---|---|
| `MaterialApp` (`MaterialPageRoute`) | `ThemeData.pageTransitionsTheme`。プラットフォームごとに一つのビルダー: Android では `PredictiveBackPageTransitionsBuilder`、iOS と macOS では `CupertinoPageTransitionsBuilder`、Windows と Linux では `ZoomPageTransitionsBuilder` |
| `CupertinoApp` (`CupertinoPageRoute`) | 端からのスワイプで戻れる iOS のスライド |
| `WidgetsApp` | 独自のものはなし: アプリが `pageRouteBuilder` を渡す |

ここでのデフォルトも同じ `platform` なので、何も設定しないアプリは Flutter で書いた場合と同じ見た目になります。

**プラットフォームごとのビルダーではなく、テーマの一つの値。** 見た目は設定です。`motion.page-transition` は `application.yml` にあり、テーマごと (`themes.<name>`)、プロファイルごとに設定でき、プラットフォームもプロファイルです。

```yaml
# lib/resources/application-web.yml: Web ではページを即座に切り替える
spring.flutter.theme.motion.page-transition: none
```

同じ値が、ルーターの画面と Material 自身のルートの両方を決めます (コードが push する `MaterialPageRoute` は `pageTransitionsTheme` を通じてそれを受け取ります)。コードでのプラットフォームごとのビルダーも使えます。`pageTransitionsTheme` を設定する `ThemeCustomizer` があれば ([コードでのテーマ](../../spring-boot-starter-flutter-material/themes-in-code.md))、`platform` を求めるページはそれを使います。

**Flutter に対応するもののない機能:**

- 画面が独自のものを選べ (`@ScreenRoute(transition: PageTransition.fade)`)、一回のナビゲーションも選べます (`go(path, transition: PageTransition.none)`)。独自のルートのクラスは要りません。
- 長さとカーブは、`platform` も含め、どの種類でもテーマから来ます (`{ type: platform, duration: 250ms, curve: ease-out }`)。
- `content`: 画面が、`motion.content-change` が別のコンテンツを表示するのと同じように入ってきます。
- デバイスで視差効果を減らす設定が有効なら、すべてのトランジションは即座になります。
- シェルのブランチの切り替えは決してアニメーションしません。
- `zoom` と `cupertino` は、そのスターターがあればどのアプリの種類でも動きます。`MaterialApp` での iOS のスライド、`WidgetsApp` での Material のズームです。

**以前はなしだった理由と、`none` を書くとき。** 0.8 までは、`motion.page-transition` のないテーマには、どのアプリの種類でもトランジションがありませんでした。デザインライブラリーのないアプリ (farum-azula.org のような Web サイト) はどのみちページを即座に切り替えますし、コンテンツのサイトやダッシュボードは即座のページを望むことがよくあります。一方で Material や Cupertino のアプリは、Flutter が与えるものより少ないものしか持っていませんでした。ページを即座に切り替えるには、`motion.page-transition: none` と書きます。

## テキストの変化

アプリの言語が切り替わると、すべてのテキストが即座に変わります。`motion.text-change` を書くと、`ThemeText` で表示されるテキストは代わりにテーマの方法で変わります。

```yaml
spring:
  flutter:
    theme:
      motion:
        text-change: { type: morph, duration: 600ms, curve: ease-out, stagger: 12ms }
```

```dart
ThemeText(context.messages.home.title, style: theme.typography.displaySmall);
```

- `morph`: 文字が行の先頭から一つずつ変わり、それぞれがいくつかのグリフを経てから新しいものに落ち着きます。`stagger` は一つの文字から次の文字までの遅れです。デフォルトでは、波は同じままの文字も含め、行全体に流れます。`keep-unchanged: true` はそれらをその場に残すため、変わった部分だけが流れます (最後の部分が変わるパンくずリスト)。`glyphs` は経由する文字 (`$` も含め書いたとおりに解釈されます)、`glyph-duration` はそれぞれが表示される時間です。

```yaml
text-change:
  type: morph
  duration: 650ms
  stagger: 14ms
  glyphs: '01<>/'          # デフォルト ▓▒░<>/\|=+*#%&@$?!01
  glyph-duration: 30ms     # デフォルト 40ms
```
- `fade`: 古いテキストがフェードアウトし、新しいものがフェードインします。
- `none` (デフォルト): 新しいテキストが即座に表示されます。

`ThemeText` は、同じウィジェットが別のテキストを受け取るたびに変わります。新しい言語、更新された値、クエリを入力するにつれて変わる検索の結果などです。その `highlights` (テキストの範囲、検索が見つけた単語) は、変化が落ち着くと `highlightStyle` で表示されます。視差効果を減らす設定では即座に変わります。言語そのものに対して処理を行うには、ナビゲーションの `LanguageChangedEvent` を `@EventListener` で受け取ってください。

## コンテンツの変化

その場所に別のコンテンツを表示する画面の一部、例えば同じ画面の別のページが開いたときのドキュメントのページの記事は、次のコンテンツが読まれるまで表示中のものを保ちます。一フレームの間何もない状態に縮むことはありません。`motion.content-change` は、新しいコンテンツが古いものを置き換える方法を示します。

```yaml
spring:
  flutter:
    theme:
      motion:
        content-change: { type: fade-up, duration: 220ms, curve: ease-out }
```

- `fade`: 古いコンテンツがフェードアウトし、新しいものがフェードインします。
- `fade-up`: 同じで、新しいコンテンツが少し上がってきます。
- `morph`: 新しいコンテンツが上から一行ずつ自分をタイプしていきます。各行の文字は `text-change: morph` と同じようにグリフを経て定まります。古いコンテンツは即座に消えます。ページは最初のフレームから本来の高さを持ちます: まだ順番が来ていない行は、見えないまま自分の場所を保ちます。
- `none` (デフォルト): 新しいコンテンツが即座に表示されます。

`morph` では、`stagger` は各行が前の行よりどれだけ遅れて始まるか (デフォルトは 30ms)、`delay` はページが最初の行の前に、何もない状態でどれだけ待つか (デフォルトはなし) です。`text-change` の期間を与えると、ページの上の `ThemeText` (パンくず) が先にモーフし、ページが後に続きます。

```yaml
motion:
  text-change: { type: morph, duration: 650ms }
  content-change: { type: morph, duration: 1.2s, stagger: 40ms, delay: 650ms }
```

行の開始は最大でも `duration` の 85 パーセントの間に収まるので、長いページも `duration` で終わります。`MarkdownView` と `RouteContentView` はモーフします。それ以外の `ContentChange` は新しいコンテンツを即座に表示します。

同じ画面で別のページが開くと (`RouteContentView`)、ブラウザーがページを開くように、画面も先頭に戻ります: `motion.scroll-to-top` (デフォルトは 400ms の ease-out-cubic。`none` はジャンプし、視差効果を減らす設定でもジャンプします)。

```yaml
motion:
  scroll-to-top: { duration: 500ms, curve: ease-in-out }
```

新しいコンテンツが高さを決め、古いものは消える間その高さに切り取られます。`RouteContentView` と `MarkdownView.resource` はこの方法で変わります。それ以外のコンテンツは `ContentChange(id: ..., child: ...)` で包みます。新しい `id` が変化です。視差効果を減らす設定では、コンテンツは即座に変わります。

独自の種類は、アプリケーションの起動前に登録します (テーマは起動時に読まれ、誰も登録していない種類は、存在する名前を示して起動を止めます)。

```dart
void main() {
  ContentTransitions.register(
    'scale',
    (child, animation) => ScaleTransition(scale: animation, child: child),
  );
  runApp(SpringApplicationWidget(application: createApplication));
}
```

## マウスホイール

Flutter は、スクロール領域をホイールの刻み全体だけ一度に動かします。Web ではページが一刻みごとに 100 ピクセルほどジャンプし、カクつきのように見えます。`motion.wheel-scroll` は、コントローラーを設定せずに、アプリのすべてのスクロール領域についてホイールの各刻みを滑らかにします。

```yaml
motion:
  wheel-scroll: { duration: 250ms, speed: 0.8 }
```

- `duration`: 一つの刻みが到達するまでの時間。続けて来た刻みは加算されて動き続けます。
- `speed`: 刻みの割合。1 未満は遅く、1 より上は速くなります。
- `none` (デフォルト): Flutter 自身の動作。
- `inertia`: [慣性](#慣性) を参照。

タッチのスクロールはその物理挙動を保ちます。プラットフォームがホイールの刻みとして報告するトラックパッド (Web) も滑らかになります。その刻みは小さいため、ほぼ以前どおりに動きます。処理は `WheelScrollSmoother` が行い、`SpringApp` がアクティブなテーマからそれを設定します。

## 慣性

`motion.wheel-scroll.inertia` は、ポインターの種類ごとに、スクロールに重さを与えます。どれもデフォルトではオフ (0) です。

```yaml
motion:
  wheel-scroll: { duration: 260ms, speed: 0.75, inertia: { mouse: 0.2 } }
```

| キー | 働き |
|---|---|
| `mouse` | 続けて来る素早いホイールの刻みが、それぞれより遠くへ進み (0.2: 一つごとに 5 分の 1 ずつ増え、最大で 6 つ続くまで)、より長く滑ります。そのため、速く回したホイールはページを横切り、一刻みだけなら一刻み分だけ動きます |
| `trackpad` | 指が止まると、ページは最後の刻みの割合を毎フレーム保ちながら滑り続けます (0.9)。システムが自分では滑らせないトラックパッド向けです。Windows や Linux の多くがそうです。macOS は滑らせるので、そこでは 0 のままにしてください |
| `touch` | 指で弾くと、ページがより遠くへ飛びます (0.5: 1.5 倍の距離) |

慣性にかかわらず、指が動いている間にトラックパッドが刻みを送らなかったフレームには、前のフレームの刻みが与えられ、次の刻みはその分だけ短くなります。ブラウザーは毎フレーム刻みを送りますが、時々送らないことがあり、その結果ページが 1 フレーム止まり、次のフレームで 2 倍の距離をジャンプしていました。

## 長さ

`motion.durations.<name>` は、独自のアニメーションのための、好きな名前を持つ長さです。

長さは、数値、省略可能な空白、そして単位です: `ms`、`s`、`m`、`h`、`d` (大文字小文字を問わない)。小数も使えます (`1.5s`、`0.5d`)。単なる数値はミリ秒です。負の数値や別の単位はエラーです。これは、テーマのすべての時間の唯一の構文です: モーション、アニメーション、スタイル、トークン、`transition`、`refresh`、`timeout`。

`short`、`medium`、`long` は、書かなくても存在します: 100 ms、250 ms、450 ms。宣言していない別の名前を読む (`context.theme.motion` は書いた名前だけを持ちます) と、最も近い名前を列挙するエラーになります。

```dart
AnimatedContainer(
  duration: context.theme.motion.fast,                 // Duration
  curve: context.theme.motion.curves.emphasized,       // Curve
  height: expanded ? 200 : 80,
)
```

## カーブ

カーブは、下の表の名前、または三次曲線のための四つの数値 (CSS の `cubic-bezier` と同じ) です。四つの数値は、YAML のリストか、引用符で囲んだ一つのテキストとして書きます。

```yaml
spring:
  flutter:
    theme:
      motion:
        curves:
          standard: '0.2, 0, 0, 1'
          bounce: bounce-out
          snap: [0.4, 0, 0.2, 1]
```

名前はケバブケースで書きます。`easeIn` と `ease_in` も使えます。

| カーブ | 感触 |
|---|---|
| `linear` | 一定の速度 |
| `ease` | ゆっくり始まり、速くなり、ゆっくり終わる (CSS の `ease`) |
| `ease-in` | ゆっくり始まる |
| `ease-out` | ゆっくり終わる |
| `ease-in-out` | ゆっくり始まり、ゆっくり終わる |
| `fast-out-slow-in` | 素早い始まりと、長く穏やかな終わり (Material の古典的なカーブ) |
| `decelerate` | 速い始まりが滑らかに減速する |
| `standard` | Material 3 の標準のイージング |
| `standard-accelerate` | 去っていくもののための Material 3 の標準のイージング |
| `standard-decelerate` | 到着するもののための Material 3 の標準のイージング |
| `emphasized` | 強いイージング: `0.2, 0, 0, 1` |
| `emphasized-accelerate` | 去っていくもののための強調されたもの |
| `emphasized-decelerate` | 到着するもののための強調されたもの |
| `ease-in-sine`、`ease-out-sine`、`ease-in-out-sine` | ごく穏やかなイージング |
| `ease-in-cubic`、`ease-out-cubic`、`ease-in-out-cubic` | より強いイージング |
| `ease-in-back`、`ease-out-back`、`ease-in-out-back` | 最初に少し後ろに下がる、または終わりを行き過ぎる |
| `bounce-in`、`bounce-out`、`bounce-in-out` | ボールのように弾む |
| `elastic-in`、`elastic-out`、`elastic-in-out` | ゴムバンドのように跳ねる |

それ以外はこれらの名前を列挙するエラーです。`motion.curves` で宣言していないカーブは、`SpringTheme.of(context).curve(name)` で読むと Material の標準のイージングです。生成される `context.theme.motion.curves.<name>` は、宣言した名前についてだけ存在します。

## アニメーション

`animations.<name>` は名前付きのアニメーションです。一回の実行の時間、そのカーブ、終わりに起きることです。

| `repeat` | 終わりに起きること |
|---|---|
| `none` | 一度再生し、終わりにとどまる |
| `loop` | 最初から再び始める。永久に |
| `reverse` | 往復して再生する。永久に |

`ThemeAnimation` が一つを再生します。コントローラーを所有し、指定どおりに繰り返し、テーマが変わると新しい長さやカーブを受け取り、ビルダーにカーブに沿った 0 から 1 の進行を渡します。

```dart
ThemeAnimation(
  context.theme.animations.borderSpin,
  builder: (context, t) =>
      Transform.rotate(angle: t.value * 2 * pi, child: ring),
)
```

アニメーションは [背景](background.md) の画像を動かすこともできます (`background.animation: border-spin`)。すべてのアニメーションには `duration` が必要です。それがないものは起動を止めます。

## 視差効果を減らす設定

デバイスが動きを減らすよう求めている場合 (`MediaQuery.disableAnimations`):

- `context.theme.motion` を通じて読むすべての長さは `Duration.zero` になります。
- `repeat: none` の `ThemeAnimation` は終わりにジャンプします (`t` は 1)。`loop` と `reverse` は 0 で静止します。
- 長さがゼロのアニメーションも同じです。
- `ThemeStates` は値を即座に変えます。
- [背景](background.md) は静止し、フェードなしで変わります。

トークンから読んだ長さ (`SpringTheme.of(context).tokenDuration(...)`) はそのままの長さで、減らされません。型付きの `context.theme.motion` のゲッターを使うか、自分で `MediaQuery.disableAnimationsOf(context)` をチェックしてください。

## 関連項目

- [プロパティ](properties.md)
- [スタイルと状態](styles-and-states.md): `transition: 120ms ease-out`
- [背景](background.md): `animation`、`effect`、`transition`
- [Cupertino](../../spring-boot-starter-flutter-cupertino/theme-properties.md): iOS のページのトランジション
