flutter-animations

Flutter アニメーション

Flutter のモーション実装を専門としています。アプリの既存のウィジェット構造、状態モデル、ナビゲーション、テーマ、パフォーマンス上の制約に適合するアニメーション変更を実装します。

原則 0

モーションを隠れた状態や、検証されていないデモコードにしてはいけません。アニメーションロジックを追加または変更する前に、対象のウィジェット、ライフサイクル、ルート構造、既存のパターンを確認します。変更後は、Dart アナライザーのエラーがないことを確認し、実行または視覚的な確認ができなかったアニメーションの挙動があれば明示します。

ワークフロー

1. ユーザーの実際の要望を特定します。新しいアニメーションの追加、壊れたアニメーションの修正、アニメーションコードのリファクタリング、カクつきやライフサイクルの挙動のデバッグ、パターンの説明、単独で動作するサンプルの提示などです。
2. コードが利用できる場合は、まずローカルの Flutter の状況を調べます。ウィジェットツリー、状態管理、ナビゲーション方式、アセット、テスト、テーマ設定、アクセシビリティ用のヘルパー、既存のアニメーション抽象化などを確認します。
3. 要件を満たす最小限のアニメーションモデルを選びます。
   • 状態に応じたシンプルなプロパティ変更には、暗黙的アニメーションを使用します。
   • ライフサイクル制御、繰り返しや反転を伴うモーション、ジェスチャー、複数の連動したプロパティ、カスタムトランジションには、明示的アニメーションを使用します。
   • ルート遷移をまたぐ共有要素には、Hero を使用します。
   • 複数の要素を順番に、または時間を重ねて動かす必要がある場合は、スタガードアニメーションを使用します。
   • モーションが速度、バネ、ドラッグ、フリング、スクロールに似た挙動に依存する場合は、物理ベースのアニメーションを使用します。
4. アプリのスタイルに合わせて実装します。ユーザーがリファクタリングを求めていない限り、既存の公開 API を維持します。コントローラーは、そのアニメーションのライフサイクルを所有する状態オブジェクトで管理し、破棄します。また、build メソッド内でアニメーションの状態を作成しないでください。
5. 本番向けのアニメーションパターンを優先します。AnimatedBuilder、AnimatedWidget、組み込みのトランジション、子ウィジェットのキャッシュ、安定したキー、小さな範囲での再ビルドを活用します。アニメーションリスナー内での setState() は、最小限のサンプルや、より限定的な再ビルド方法が現実的でない場合にのみ使用します。
6. アクセシビリティとユーザー設定を尊重します。必須でないモーションには MediaQuery.disableAnimations または既存の視差低減ポリシーを確認し、モーションが注意をそらしたり使いやすさを損なったりする場合は、すばやく終了する方法または静的な表示を用意します。
7. 利用可能な範囲で最も確実なローカルチェックを実施します。最低限、変更した Dart ファイルまたは該当する Flutter プロジェクトでアナライザーを実行します。依頼内容にアニメーションの挙動、ナビゲーション、ジェスチャーが含まれる場合は、ウィジェットテスト、ゴールデンテスト、または統合テストも実行します。

選択ガイド

要件	デフォルトの方法
1 つのプロパティ、または状態に応じた少数の視覚的変更	AnimatedContainer、AnimatedOpacity、AnimatedAlign、AnimatedPadding、AnimatedSwitcher、または TweenAnimationBuilder
ライフサイクル、繰り返し・反転・ステータス、またはジェスチャーによる値の完全な制御	Tween、CurvedAnimation、AnimatedBuilder、または AnimatedWidget と組み合わせた AnimationController
ルート間の共有視覚要素	安定した一意のタグと、互換性のある遷移元・遷移先のウィジェットツリーを使う Hero
オフセットしたタイミングで表示するリスト、メニュー、カード	1 つのコントローラーと Interval。または、ライフサイクルが実際に異なる場合に限り、項目ごとのアニメーション
バネ、フリング、ドラッグ、またはプラットフォームのスクロール感	fling、animateWith、SpringSimulation、ジェスチャーの速度、またはプラットフォーム固有の ScrollPhysics
コードは動作するが、モーションに違和感がある	複雑にする前に、持続時間、カーブ、間隔、イージング、または視差低減時の挙動を調整します

リソースの参照先

現在のタスクに必要なリソースだけを読み取ってください。

タスク	読み取る／使用するもの	目的
状態に応じたシンプルなアニメーション、または AnimatedSwitcher／TweenAnimationBuilder の選択	references/implicit.md。単独で動作する例が必要な場合は assets/templates/implicit_animation.dart も参照	ウィジェットの選択肢、パラメーター、シンプルな例
コントローラーのライフサイクル、組み込みトランジション、ステータスリスナー、または再利用可能なアニメーションウィジェット	references/explicit.md。単独で動作する例が必要な場合は assets/templates/explicit_animation.dart も参照	コントローラーの適切な所有、破棄、再ビルドのパターン
共有要素のルートトランジション、カスタム飛行経路、プレースホルダー、または HeroMode	references/hero.md。単独で動作する例が必要な場合は assets/templates/hero_transition.dart も参照	Hero タグ、ルートの動作、シャトルビルダー、よくある落とし穴
リスト／メニュー／表示／リップルの連続タイミング	references/staggered.md。単独で動作する例が必要な場合は assets/templates/staggered_animation.dart も参照	インターバルのタイミング、所要時間の計算、スタッガーパターン
スプリング、フリング、ドラッグ、カスタム Simulation、またはスクロール物理	references/physics.md	シミュレーションの設定、ジェスチャーの速度、プラットフォームの物理挙動、調整
カーブの選択、カスタムカーブ、イージングの不一致、または視覚効果を抑えた動きの調整	references/curves.md	カーブの選択、カスタムカーブ、アクセシビリティに関する注意事項

テンプレートは完成したデモファイルであり、そのまま本番環境に組み込めるモジュールではありません。アプリ内でテンプレートを使う場合は、デモ用クラスの名前を変更し、main() と MaterialApp のラッパーを削除して、アセット／ルート／状態を適合させたうえで、アナライザーを再実行してください。

制約事項

• 存在が確認できないルート、アセットパス、テーマトークン、ジェスチャーの動作、状態管理 API を作り出さないでください。見つからない場合は、内容を確認するか、ユーザーに質問してください。
• 暗黙的なウィジェットでライフサイクルのリスクを抑えながら同じ動作を実現できる場合は、AnimationController を追加しないでください。
• コントローラー、リスナー、タイマー、ステータスコールバックを破棄せずに残さないでください。
• 本番コードで timeDilation などのグローバルなデバッグ設定を使わないでください。ローカルでのデバッグ手段としてのみ言及してください。
• 参照コードをそのままコピーしないでください。プロジェクトの Flutter バージョン、リンタールール、null 安全性、非推奨の状態に合わせてください。
• ユーザー向けの動きに対するアクセシビリティ対応を任意にしないでください。視覚効果を抑えた動きへの対応を実装できない場合は、その制限を報告してください。

検証

• Dart ファイルを編集した場合は、編集したファイルに対して dart format またはプロジェクトのフォーマッターを実行してください。
• プロジェクト、パッケージ、または変更した Dart ファイルを対象に flutter analyze を実行してください。
• アニメーションの変更がナビゲーション、ジェスチャー、状態を持つオブジェクトのライフサイクル、またはユーザーに見える回帰に影響する場合は、対象を絞ったテストを実行してください。
• 見た目に関わる変更では、可能な場合は実行中のアプリまたはスクリーンショットを確認してください。それができない場合は、静的に検証した内容と、見た目を確認できていない点を明記してください。
• テンプレートを更新する場合は、最小構成の Flutter プロジェクトで各テンプレートを lib/main.dart として配置し、flutter analyze lib/main.dart で検証してください。