ios-animation-implementation

iOS アニメーションの実装

Apple のフレームワークを直接使ってアニメーションコードを記述します。サードパーティ製のアニメーションライブラリは依存関係のリスクを増やし、新しい OS リリースへの対応が遅れることも少なくありません。Apple の API はレンダリングパイプライン向けに十分に最適化されており、iOS の各バージョンで無償の改善を受けられます。

カスタムアニメーションを書く前に

必要な動きをシステムがすでに処理していないか確認します。Apple の HIG には、「多くのシステムコンポーネントにはモーションが自動的に含まれているため、アプリ全体で親しみやすく一貫した体験を提供できます」とあります。システムコンポーネントはアクセシビリティ設定や入力方法にも自動的に対応します。Liquid Glass（iOS 26）は、直接タッチにはより強く反応し、トラックパッドには控えめなエフェクトを適用します。カスタムアニメーションで同じ適応性を手軽に実現することはできないため、システムが提供するモーションがある場合はそちらを優先します。

次の場合はカスタムアニメーションを使わないでください：

• 標準のナビゲーション遷移で対応できる場合（push、pop、sheet、fullScreenCover）
• SF Symbol の .symbolEffect で必要なフィードバックが得られる場合
• .contentTransition(.numericText) でデータの変更に対応できる場合
• withAnimation のシステム標準のスプリングで十分な場合

次の場合はカスタムアニメーションを記述してください：

• 必要な空間的関係をシステムが提供していない場合（ヒーロー遷移、カスタムジェスチャ）
• 複数のプロパティを連携させた振り付けが必要な場合
• アニメーションがアプリの個性を形作る象徴的な演出である場合
• ジェスチャ駆動のインタラクションにカスタムの進行状況マッピングが必要な場合

API の選択

目的に合った API を選びます。まずは SwiftUI アニメーション（最も簡単で宣言的）から始め、インタラクティブな制御が必要な場合は UIKit に移り、レイヤーレベルの精度が必要な場合にのみ Core Animation を使います。

必要な機能	API	理由
状態に応じたプロパティの変更	withAnimation / .animation(_:value:)	宣言的で、補間が自動
複数ステップの順次アニメーション	PhaseAnimator	フェーズごとのタイミングを設定できる離散フェーズ
プロパティごとのタイムライン制御	KeyframeAnimator	プロパティごとに独立したキーフレームトラック
ビュー間のヒーロー遷移	matchedGeometryEffect + Namespace	ビューのアイデンティティをまたいだジオメトリの一致
ズームを使ったナビゲーションの push/pop	.navigationTransition(.zoom)	iOS 18 以降に組み込まれたズーム遷移
カスタムのビュー挿入・削除	Transition プロトコルへの準拠	TransitionPhase に基づくモディファイア
ビュー内のコンテンツ切り替え	.contentTransition()	数値テキスト、補間、不透明度
スクロール位置に基づくエフェクト	.scrollTransition	フェーズ駆動のスクロール連動アニメーション
SF Symbol のアニメーション	.symbolEffect()	バウンス、パルス、ウィグル、ブリーズ、回転
インタラクティブ／中断可能なアニメーション（UIKit）	UIViewPropertyAnimator	一時停止、再開、反転、スクラブ
レイヤーごとのプロパティアニメーション	CABasicAnimation / CASpringAnimation	シャドウ、ボーダー、cornerRadius のアニメーション
複雑な振り付け（レイヤー）	CAKeyframeAnimation + CAAnimationGroup	複数プロパティのレイヤーアニメーション
物理シミュレーション	UIDynamicAnimator	重力、衝突、スナップ、アタッチメント
アニメーションに連動した触覚フィードバック	.sensoryFeedback モディファイア	値の変更に連動
アニメーション付き背景グラデーション	MeshGradient	配置した色をアニメーションさせる 2D グリッド

カテゴリ別の実装

詳しいパターンやコード例は、リファレンスファイルに記載されています。作業内容に合ったファイルを読み込みます。

タスク	リファレンス
SwiftUI の宣言的アニメーション（withAnimation、スプリング、フェーズ、キーフレーム）	references/swiftui-animations.md
ビュー遷移（ナビゲーション、モーダル、カスタム Transition プロトコル）	references/transitions.md
ジェスチャ駆動のインタラクティブアニメーション	references/gesture-animations.md
Core Animation と UIKit のアニメーションパターン	references/core-animation.md

リファレンスを読み込むタイミング

• withAnimation、スプリングパラメーター、PhaseAnimator、または KeyframeAnimator を記述する場合 → swiftui-animations.md
• ナビゲーショントランジション、モーダル表示、matchedGeometryEffect、またはカスタム Transition を構築する場合 → transitions.md
• ドラッグで閉じる操作、スワイプアクション、ピンチ／回転、またはスクロール連動エフェクトを実装する場合 → gesture-animations.md
• CABasicAnimation、UIViewPropertyAnimator、レイヤーアニメーション、または SwiftUI と UIKit のブリッジに取り組む場合 → core-animation.md

スプリングパラメーターのクイックリファレンス

最新の SwiftUI では、スプリングがデフォルトのアニメーションタイプです。UIKit／CA とのブリッジを除き、mass／stiffness／damping ではなく duration と bounce を使用してください。

プリセット	Duration	Bounce	用途
.smooth	0.5	0.0	デフォルトのトランジション、ほとんどの状態変化
.snappy	0.3	0.15	マイクロインタラクション、トグル、素早いフィードバック
.bouncy	0.5	0.3	遊び心のある演出、注意を引く場面
.interactiveSpring	0.15	0.0	ジェスチャーの追従、ドラッグへの追従
カスタム	変動	変動	.spring(duration: 0.4, bounce: 0.2)

アクセシビリティとマルチモーダルフィードバック

Apple の HIG では、「モーションを任意にできるようにする」こと、また「触覚や音声などの代替手段も使って視覚的なフィードバックを補い、情報を伝える」ことを掲げています。すべてのアニメーションで「視差効果を減らす」設定に対応し、重要な状態変化にはアニメーションだけでなく、複数のフィードバック手段を使用してください。

@Environment(\.accessibilityReduceMotion) private var reduceMotion

// Pattern 1: Conditional animation
withAnimation(reduceMotion ? .none : .spring()) {
    isExpanded.toggle()
}

// Pattern 2: Simplified alternative
.animation(reduceMotion ? .easeOut(duration: 0.15) : .spring(duration: 0.5, bounce: 0.3), value: isActive)

// Pattern 3: Skip entirely
if !reduceMotion {
    view.phaseAnimator(phases) { /* ... */ }
}

「視差効果を減らす」設定が有効な場合の代替方法（自然さの高い順）：

1. クロスフェード — モーションを不透明度のトランジションに置き換えます
2. 短縮 — 同じアニメーションを大幅に速くし（0.1～0.15 秒）、バウンスをなくします
3. 即時 — .animation(.none) を使うか、アニメーションブロック自体を完全に省略します

キャンセルと割り込みへの対応

Apple の HIG では、「特にアニメーションを複数回体験しなければならない場合、アニメーションが完了するまで何もできずに待たせてはいけません」としています。すべてのアニメーションで割り込みに対応してください。

• スプリングアニメーションは自動的に目標を変更します。これがデフォルトの動作であり、ほとんどの場合に適しています
• ジェスチャー駆動のアニメーションでは、常にユーザーが操作の主導権を持ちます。動作中でもキャンセルできるようにしてください
• シーケンスアニメーション（トリガー付きの KeyframeAnimator、PhaseAnimator）では、再生中も UI の操作性を保ってください
• 重大な理由（破壊的操作の確認など）がない限り、アニメーション中にユーザー操作を無効にしないでください

パフォーマンスチェックリスト

• 可能な場合はレンダーサーバー上でアニメーションを実行してください。Core Animation はメインスレッドの外で動作し、SwiftUI の drawingGroup() はレンダリングを Metal に移します
• ビューの ID 変更（.id() モディファイア）のアニメーションは避けてください。ビューが破棄され、再作成されます
• 親のジオメトリ変化によってアニメーション中に子のレイアウトに異常が起きる場合は、geometryGroup() を使用してください
• 影をアニメーションさせる場合は、明示的に shadowPath を指定してください。指定しないと、システムはフレームごとにパスを再計算します
• リストやスクロールビューでは、項目ごとのぼかし／影のアニメーションを避けてください。各セルでオフスクリーンレンダリングが発生します
• PhaseAnimator とループアニメーションは軽量に保ってください。これらは連続して実行されます
• 頻繁に行われる操作では、カスタムモーションよりシステム提供のアニメーションを優先してください。Apple の HIG では、「頻繁に発生する UI 操作にモーションを追加することは、一般的に避ける」よう推奨しています
• Instruments の「Animation Hitches」テンプレートを使って、フレーム落ちを見つけてください

ゲート（作業完了とする前に）

順番に実施し、各項目の合格を確認してからタスクを完了としてください。

1. API の適合性 — このタスクには API 選択表から仕組みを選びます。合格： どの「必要性」行と API を適用したかを、（「なんとなく」別レイヤーを選ぶのではなく）1 文で説明できます。
2. モーションの軽減 — カスタムのタイミングは「アクセシビリティとマルチモーダルフィードバック」に従う必要があります。合格： 複雑なモーションは accessibilityReduceMotion に応じて分岐するか、システムのデフォルトのみを使用するか、カスタムのタイミングを使用していません。
3. 割り込み可能性 — 「キャンセルと割り込み可能性」に適合しています。合格： タスクで明示的に必要とされ、理由を説明する短いコメントがある場合を除き、アニメーション全体に対して一律に allowsHitTesting(false) を適用していません。
4. 負荷の高いモーションまたは連続的なモーション — ループ、常時実行の PhaseAnimator、セルごとのぼかしやシャドウなど、「パフォーマンスチェックリスト」で問題となる項目に該当する場合。合格： Instruments（Animation Hitches）を実行し、記録またはトレースへのパスを残しているか、パターンを先に簡素化し、その変更箇所を示せます。