UIKit アニメーションデバッグ は何をしますか?
概要
CAAnimation の問題は、特定の条件下で、完了ハンドラが呼び出されない、タイミングがおかしい、カクつくといった形で現れます。核となる原則 CAAnimation の問題の90%は、Core Animation のバグではなく、CATransaction のタイミング、レイヤーの状態、またはフレームレートの仮定に起因します。
警告サイン — CAAnimation の問題を疑うべきケース
以下のいずれかに該当する場合は、デバイスの動作ではなくアニメーションロジックに問題があると疑ってください:
- シミュレータでは完了ハンドラが呼ばれるが、実機では呼ばれない
- アニメーションの持続時間(0.5秒)が実際の見た目の持続時間(1.2秒)と一致しない
- スプリングアニメーションが iPhone 15 Pro では正しく見えるが、古いデバイスではカクつく
- ジェスチャーとアニメーションを同時に行うとカクつく(個別では問題ない)
- 完了ハンドラで
[weak self]を使っているが、その理由がわからない - ❌ 禁止 実際の動作に合わせるために duration や値をハードコーディングすること
- これは異なるハードウェアのユーザーにデバイス固有のバグを出荷することになります
- これを「一時的な修正」や「十分良い」と正当化しないでください
重要な区別 シミュレータはタイミング問題を隠蔽することがよくあります(60Hz固定、スロットリングなし)。実機ではこれらの問題が露呈します(可変フレームレート、CPUスロットリング、バックグラウンドプレッシャー)。必須: 出荷前に必ず実機(サポート対象の最古モデル)でテストしてください。
必須の初動診断
コードを変更する前に、常にこれらを最初に実行してください:
// 1. 完了ハンドラが呼ばれているか確認
animation.completion = { [weak self] finished in
print("🔥 完了ハンドラ呼び出し: finished=\(finished)")
guard let self = self else {
print("🔥 self が nil でした")
return
}
// 元のコード
}
// 2. 実際の持続時間と宣言された持続時間を確認
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5 // 宣言
layer.add(anim, forKey: "test")
DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
print("経過時間: \(Date().timeIntervalSince(startTime))") // 実際
}
// 3. アクティブなアニメーションを確認
if let keys = layer.animationKeys() {
print("アクティブなアニメーション: \(keys)")
for key in keys {
if let anim = layer.animation(forKey: key) {
print("\(key): duration=\(anim.duration), removed=\(anim.isRemovedOnCompletion)")
}
}
}
// 4. レイヤーの状態を確認
print("レイヤーの速度: \(layer.speed)") // != 1.0 はタイミングが変更されている
print("レイヤーのtimeOffset: \(layer.timeOffset)") // != 0 はアニメーションがオフセットされている
これが示すこと
- 完了ハンドラの print が表示される → ハンドラは呼ばれている。問題はコールバックコードにある。
- 完了ハンドラの print が表示されない → ハンドラが呼ばれていない。CATransaction/レイヤーの状態を確認。
- 経過時間 == 宣言時間 → 持続時間は正しい。見た目のカクつきはフレームレートの問題。
- 経過時間 != 宣言時間 → CATransaction のラッピングが持続時間を変更している。
- layer.speed != 1.0 → 何かがアニメーションを遅くしている。
- アクティブなアニメーションのリストが長い → 複数のアニメーションが競合している。
必須の解釈
コードを変更する前に、以下の1つの診断が根本原因であることを特定する必要があります:
- 完了ハンドラが呼ばれるが、経過時間が宣言時間と異なる場合 → パターン2(CATransaction)を適用
- 完了ハンドラが呼ばれず、isRemovedOnCompletion が true の場合 → パターン3を適用
- 完了ハンドラが呼ばれるが見た目がカクつく場合 → 必ず最初に Instruments でプロファイルする
- 「おそらくフレームレートの問題でしょう」と推測してはいけません。データで証明してください。
- プロファイル > Core Animation インストゥルメントでフレームドロップを確実に確認できます。
- Instruments をスキップするなら、それは推測です。
診断結果が矛盾または不明瞭な場合
- 止まってください。まだパターンに進まないでください。
- 原因を絞り込むために print 文を追加してください。
- 自問してください: 「診断結果は X と Y を示しているが、Z が一致しない。何を見落としているのか?」
- 不明な場合は Instruments > Core Animation でプロファイルしてください。
決定木
CAAnimation の問題?
├─ 完了ハンドラが呼ばれない?
│ ├─ シミュレータのみ?
│ │ └─ シミュレータのタイミングは異なる(60Hz)。実機でテスト。
│ ├─ 実機のみ?
│ │ ├─ 確認: isRemovedOnCompletion と fillMode
│ │ ├─ 確認: CATransaction のラッピング
│ │ └─ 確認: アニメーション中にアプリがバックグラウンドに移行するか
│ └─ シミュレータと実機の両方?
│ ├─ 確認: 完了ハンドラがアニメーション追加前に設定されているか
│ └─ 確認: [weak self] が実際にキャプチャされているか(完了前に nil になっていないか)
│
├─ 持続時間のミスマッチ (宣言 != 見た目)?
│ ├─ layer.speed != 1.0?
│ │ └─ 何かがアニメーションの持続時間を変更している。見つけて修正。
│ ├─ アニメーションが CATransaction でラップされている?
│ │ └─ CATransaction.setAnimationDuration() が animation.duration を上書きする
│ └─ 見た目の持続時間が宣言より長い?
│ └─ シミュレータ(60Hz) vs デバイス(120Hz)。実際のハードウェアに合わせて再計算。
│
├─ スプリング物理演算が実機でおかしい?
│ ├─ 値が1つのデバイス用にハードコーディングされている?
│ │ └─ モデルではなくデバイスのパフォーマンスクラスを使用
│ ├─ damping/stiffness の値が mass/stiffness と入れ替わっている?
│ │ └─ CASpringAnimation のパラメータの意味を確認
│ └─ シミュレータでは動作するが実機では動作しない?
│ └─ シミュレータは60Hz。デバイスは120Hzの場合がある。再計算。
│
└─ ジェスチャー + アニメーションのカクつき?
├─ アニメーションが競合している (同じ keyPath)?
│ └─ 新しいアニメーションを追加する前に古いアニメーションを削除
├─ アニメーション実行中にジェスチャーがレイヤーを更新している?
│ └─ 同期更新に CADisplayLink を使用
└─ ジェスチャーがメインスレッドをブロックしている?
└─ Instruments > Core Animation でプロファイル
一般的なパターン
パターン選択ルール(必須)
パターンは1つずつ、この順序で適用すること
-
常にパターン1から始める(完了ハンドラの基本)
- 完了ハンドラが絶対に呼ばれない場合 → パターン1
- print 文(33行目)を使用して、完了ハンドラが add() の前に設定されていることを確認する
- 完了ハンドラが呼ばれているが、タイミングがおかしい場合のみパターン2に進む
-
次にパターン2(CATransaction の持続時間ミスマッチ)
- 完了ハンドラが呼ばれるが、経過時間が宣言時間と異なる場合のみ
- 必須の初動診断のログ(40-47行目)を確認する
-
次にパターン3(isRemovedOnCompletion)
- アニメーションは完了するが、視覚的な状態が元に戻る場合のみ
-
パターン4-7 特定の症状に基づいて適用(91行目以降の決定木を参照)
禁止事項
- ❌ 複数のパターンを同時に適用すること(「パターン2とパターン4を一緒に試そう」)
- ❌ 「すでにそうでないとわかっている」という理由でパターン1をスキップすること
- ❌ それぞれのパターンが必要な理由を理解せずにパターンを組み合わせること
- ❌ パターンをランダムに試して、どれかがうまくいくことを期待すること
パターン1: 完了ハンドラの基本
❌ 間違い(アニメーション追加後にハンドラを設定)
layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in // ❌ 遅すぎる!
print("完了")
}
✅ 正しい(追加前にハンドラを設定)
animation.completion = { [weak self] finished in
print("🔥 アニメーション完了: \(finished)")
guard let self = self else { return }
self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")
理由 完了ハンドラは、アニメーションがレイヤーに追加される前に設定する必要があります。追加後に設定しても何も起こりません。
パターン2: CATransaction と animation.duration
❌ 間違い(CATransaction がアニメーションの持続時間を上書き)
CATransaction.begin()
CATransaction.setAnimationDuration(2.0) // ❌ すべてのアニメーションを上書き!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5 // これは無視される
layer.add(anim, forKey: nil)
CATransaction.commit() // アニメーションは0.5秒ではなく2.0秒かかる
✅ 正しい(トランザクションではなくアニメーションに持続時間を設定)
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// CATransaction のラッピングなし
理由 CATransaction.setAnimationDuration() は、トランザクションブロック内のすべてのアニメーションに影響します。すべてのアニメーションを均一に変更したい場合にのみ使用してください。
パターン3: isRemovedOnCompletion と fillMode
❌ 間違い(完了後にアニメーションが消える)
let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// 0.5秒後、アニメーションが削除され、レイヤーが元の状態に戻る
✅ 正しい(アニメーションの状態を維持)
anim.isRemovedOnCompletion = false
anim.fillMode = .forwards // アニメーション後の最終状態を維持
layer.add(anim, forKey: nil)
// 0.5秒後、アニメーションの状態が保持される
理由 デフォルトでは、アニメーションは削除され、レイヤーは元の状態に戻ります。永続的な状態変更には、isRemovedOnCompletion = false と fillMode = .forwards を設定します。
パターン4: 完了ハンドラでの弱参照 self(必須)
❌ 禁止(強参照 self は循環参照を引き起こす)
anim.completion = { finished in
self.property = "value" // ❌ 循環参照が確実
}
✅ 必須(常に弱参照 self を使用)
anim.completion = { [weak self] finished in
guard let self = self else { return }
self.property = "value" // 安全にアクセス
}
これが必須であり、オプションではない理由
- CAAnimation はアニメーションが完了するまで完了ハンドラを保持し続ける
- 完了ハンドラは self を強参照でキャプチャする(明示的に弱参照にしない限り)
- 循環参照が発生: self → アニメーション → 完了ハンドラ → self
- アニメーションが短時間(0.3秒)でもメモリリークが発生する
禁止される正当化
- ❌ 「アニメーションが短いので循環参照のリスクはない」
- ❌ 「手動でアニメーションを削除するので問題ない」
- ❌ 「このコードパスは一度しか実行されない」
完了ハンドラでは常に [weak self] を使用してください。例外はありません。
パターン5: 複数のアニメーション(同じ keyPath)
❌ 間違い(アニメーションが競合)
// アニメーション1を追加
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")
// 後でアニメーション2を追加
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide") // ❌ 同じキー。anim1 を置き換える!
✅ 正しい(追加前に古いアニメーションを削除)
layer.removeAnimation(forKey: "slide") // 最初に古いものを削除
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")
または一意のキーを使用:
let anim1 = CABasicAnimation(keyPath: "position.x")
layer.add(anim1, forKey: "slide_1")
let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2") // 異なるキー
理由 同じキーでアニメーションを追加すると、以前のアニメーションが置き換えられます。古いアニメーションを削除するか、一意のキーを使用してください。
パターン6: ジェスチャーとアニメーションの同期のための CADisplayLink
❌ 間違い(ジェスチャーが直接更新し、アニメーションが異なるレートで更新)
func handlePan(_ gesture: UIPanGestureRecognizer) {
let translation = gesture.translation(in: view)
view.layer.position.x = translation.x // ❌ 同期の問題
}
// 別途:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil) // 非同期によるカクつき
✅ 正しい(同期に CADisplayLink を使用)
var displayLink: CADisplayLink?
func startSyncedAnimation() {
displayLink = CADisplayLink(
target: self,
selector: #selector(updateAnimation)
)
displayLink?.add(to: .main, forMode: .common)
}
@objc func updateAnimation() {
// 同じフレームでジェスチャーとアニメーションの両方を更新
let gesture = currentGesture
let position = calculatePosition(from: gesture)
layer.position = position // 同期された更新
}
理由 ジェスチャー認識機能と CAAnimation は異なるフレームレートで実行される可能性があります。CADisplayLink は両方を画面のリフレッシュレートに同期します。
パターン7: スプリングアニメーションのデバイス差
❌ 間違い(1つのデバイス用にハードコーディング)
let springAnim = CASpringAnimation()
springAnim.damping = 0.7 // iPhone 15 Pro 用にハードコーディング
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil) // iPhone 12 でカクつく
✅ 正しい(デバイスのパフォーマンスに適応)
let springAnim = CASpringAnimation()
// デバイスのパフォーマンスクラスを使用(モデルではなく)
if ProcessInfo.processInfo.processorCount >= 6 {
// 最新のAシリーズ(A14+)
springAnim.damping = 0.7
springAnim.stiffness = 100
} else {
// 古いAシリーズ
springAnim.damping = 0.85
springAnim.stiffness = 80
}
layer.add(springAnim, forKey: nil)
理由 スプリング物理演算は60Hzと120Hzで異なるフィーリングになります。モデルではなくデバイスクラス(コア数、GPU)を使用してください。
クイックリファレンステーブル
| 問題 | 確認項目 | 修正方法 |
|---|---|---|
| 完了ハンドラが呼ばれない | add() の前にハンドラが設定されているか | completion = を add() の前に移動 |
| 持続時間のミスマッチ | CATransaction でラップされているか | CATransaction を削除するか、アニメーションをトランザクションから外す |
| 古いデバイスでのカクつき | 値がハードコーディングされているか | ProcessInfo でデバイスクラスを判定 |
| アニメーションが消える | isRemovedOnCompletion が true か | false に設定し、fillMode = .forwards を使用 |
| ジェスチャー + アニメーションのカクつき | 更新が同期されているか | CADisplayLink を使用 |
| 複数のアニメーションの競合 | 同じキーか? | 一意のキーを使用するか、先に removeAnimation() を実行 |
| ハンドラでの weak self | 完了ハンドラが正しくキャプチャされているか | 完了ハンドラでは常に [weak self] を使用 |
30分経っても行き詰まった場合
30分以上経過してもアニメーションがまだ壊れている場合:
止まってください。以下のいずれかの可能性があります:
- 必須の手順をスキップした(最も一般的)
- 診断出力を誤って解釈した
- 症状に合わないパターンを適用した
- Instruments によるプロファイリングが必要な5%のエッジケースに該当する
「スキルが機能しなかった」と主張する前の必須チェックリスト
- 必須の初動診断の4つの診断ブロックすべてを実行した(28-63行目)
- 診断の正確な出力(ログ、print 文)を貼り付けた
- 「これが示すこと」(66-72行目)から1つの根本原因を特定した
- 決定木(91行目以降)から最初に一致するパターンを適用した
- シミュレータだけでなく、実際のデバイスでパターンをテストした
- アプリケーションのバックグラウンド移行が完了ハンドラに影響するかどうかを確認した
エスカレーション手順(上記のすべてを実行しても問題が解決しない場合)
-
Instruments > Core Animation ですべての診断を再度実行する
- フレームレート、GPU 使用率、CPU 使用率を確認する
- 正確な診断データを収集する
-
収集したデータを構造化して提示する:
問題: [完了ハンドラが呼ばれない / 持続時間のミスマッチ / カクつき / その他]
デバイス: [モデル, iOS バージョン]
診断結果:
- 完了ハンドラの print: [表示される / 表示されない]
- 経過時間 vs 宣言: [数値]
- レイヤー速度: [layer.speed の値]
- アクティブなアニメーション: [キーのリスト]
- isRemovedOnCompletion: [true/false]
Instruments データ:
- フレームレート: [数値]
- GPU 使用率: [数値]
- CPU 使用率: [数値]
- その他の観察結果: [自由記述]
試したパターン: [パターン番号とその結果]
- 上記の情報を提供する新しいプロンプトを送信する
禁止
- ❌ 「うまくいかなかった」とだけ言って新しいプロンプトを開始する(診断データなし)
- ❌ 実行した診断や試したパターンを記載せずに「もう一度試す」
- ❌ 問題を理解せずに値をランダムに変更する