UIKitアニメーションデバッグ
概要
CAAnimationの問題は、完了ハンドラの欠落、タイミングの誤差、特定条件下でのカクつきとして現れます。基本原則: CAAnimationの問題の90%は、CATransactionのタイミング、レイヤーの状態、またはフレームレートの誤った前提に起因し、Core Animationのバグではありません。
警告サイン — CAAnimationの問題を疑う
以下のいずれかが見られた場合、デバイスの動作ではなくアニメーションロジックを疑ってください:
- 完了ハンドラがシミュレータでは発火するが、デバイスでは発火しない
- アニメーション時間(0.5秒)が実際の見た目の時間(1.2秒)と一致しない
- スプリングアニメーションがiPhone 15 Proでは正しく見えるが、古いデバイスではカクつく
- ジェスチャーとアニメーションを同時に行うとスタッターが発生する(個別では問題ない)
- 完了ハンドラ内で
[weak self]を使っているが、その理由がわからない - ❌ 禁止: 「実際に起こること」に合わせて時間や値をハードコーディングすること
- これにより、異なるハードウェアを使用するユーザーにデバイス固有のバグを出荷することになります
- これを「一時的な修正」や「十分に良い」と合理化してはいけません
重要な区別: シミュレータはタイミング問題を隠蔽することがよくあります(60Hz固定、スロットリングなし)。実機ではそれらが露呈します(可変フレームレート、CPUスロットリング、バックグラウンドプレッシャー)。必須: 出荷前に、サポート対象中最も古いモデルの実機でテストしてください。
必須の最初のステップ
常にこれらを最初に実行してください(コードを変更する前):
// 1. 完了が発火しているか確認
animation.completion = { [weak self] finished in
print("🔥 COMPLETION FIRED: finished=\(finished)")
guard let self = self else {
print("🔥 SELF WAS 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: \(layer.speed)") // != 1.0 はタイミングが変更されていることを示す
print("Layer timeOffset: \(layer.timeOffset)") // != 0 はアニメーションがオフセットされていることを示す
これからわかること
- 完了プリントが表示される → ハンドラは発火している。問題はコールバックコードにある
- 完了プリントが表示されない → ハンドラが発火していない。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)とデバイスのフレームレート(120Hz)の違い。実機用に再計算してください。
│
├─ スプリング物理がデバイスでおかしい?
│ ├─ 値が1つのデバイス用にハードコーディングされているか?
│ │ └─ モデルではなく、デバイスのパフォーマンスクラスを使用してください
│ ├─ damping/stiffness の値が mass/stiffness と入れ替わっていないか?
│ │ └─ CASpringAnimationパラメータの意味を確認
│ └─ シミュレータでは動作するがデバイスでは動作しないか?
│ └─ シミュレータは60Hzを使用。デバイスは120Hzを使用する可能性がある。再計算してください。
│
└─ ジェスチャー + アニメーションのカクつき?
├─ アニメーションが競合しているか(同じkeyPath)?
│ └─ 新しいアニメーションを追加する前に古いアニメーションを削除
├─ ジェスチャーがアニメーション実行中にレイヤーを更新しているか?
│ └─ CADisplayLinkを使用して同期更新を行う
└─ ジェスチャーがメインスレッドをブロックしているか?
└─ Instruments > Core Animationでプロファイリング
共通パターン
パターン選択ルール(必須)
1度に1つのパターンを、この順序で適用してください
-
常にパターン1から始める(完了ハンドラの基本)
- 完了が決して発火しない場合 → パターン1
- print文で完了が add() の前に設定されていることを確認(33行目)
- 完了は発火するがタイミングがおかしい場合のみ、パターン2に進む
-
次にパターン2(CATransactionの時間不一致)
- 完了は発火するが経過時間 != 宣言時間の場合のみ
- 必須の最初のステップ(40-47行目)のログを確認
-
次にパターン3(isRemovedOnCompletion)
- アニメーションは完了するが見た目の状態が元に戻る場合のみ
-
パターン4-7 特定の症状に基づいて適用(上の決定木91+行目を参照)
禁止事項
- ❌ 複数のパターンを同時に適用すること(「パターン2とパターン4を一緒に試してみよう」)
- ❌ 「もうそうじゃないとわかっている」という理由でパターン1をスキップすること
- ❌ なぜ各パターンが必要なのか理解せずに組み合わせること
- ❌ パターンをランダムに試してどれかがうまくいくことを期待すること
パターン1: 完了ハンドラの基本
❌ 間違い(アニメーション追加後にハンドラ設定)
layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in // ❌ 遅すぎる!
print("Done")
}
✅ 正しい(ハンドラを追加前に設定)
animation.completion = { [weak self] finished in
print("🔥 Animation finished: \(finished)")
guard let self = self else { return }
self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")
理由: 完了ハンドラは、アニメーションがレイヤーに追加される前に設定されなければなりません。後から設定しても何も起こりません。
パターン2: CATransaction vs 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() // アニメーションには2.0秒かかる。0.5秒ではない
✅ 正しい(アニメーションに時間を設定し、トランザクションには設定しない)
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: 完了ハンドラ内の弱い自己参照(必須)
❌ 禁止(強い自己参照は循環参照を引き起こす)
anim.completion = { finished in
self.property = "value" // ❌ 循環参照が確実に発生
}
✅ 必須(常に弱い自己参照を使用)
anim.completion = { [weak self] finished in
guard let self = self else { return }
self.property = "value" // 安全にアクセス可能
}
これが必須であり、オプションではない理由
- CAAnimationは、アニメーションが完了するまで完了ハンドラを生かし続ける
- 完了ハンドラは明示的に弱くしない限り、selfを強くキャプチャする
- 循環参照が発生する: self → アニメーション → 完了 → self
- アニメーションが短命であってもメモリリークは発生する(0.3秒だからといって防げるわけではない)
禁止される正当化
- ❌ 「アニメーションは短いので循環参照のリスクはない」
- ❌ 「手動でアニメーションを削除するので問題ない」
- ❌ 「このコードパスは1回しか実行されない」
完了ハンドラでは常に [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 か? | false に設定し、fillMode = .forwards を使用 |
| ジェスチャー + アニメーションのカクつき | 更新は同期されているか? | CADisplayLink を使用 |
| 複数のアニメーションが競合 | 同じキーか? | 一意のキーを使用するか、最初に removeAnimation() |
| ハンドラ内の弱い参照 | 完了が正しくキャプチャされているか? | 完了では常に [weak self] を使用 |
30分経っても行き詰まった場合
30分経ってもアニメーションがまだ壊れている場合:
停止してください。次のいずれかです:
- 必須の手順をスキップした(最も一般的)
- 診断出力を誤って解釈した
- 症状に合わないパターンを適用した
- Instrumentsによるプロファイリングが必要な5%のエッジケースに該当する
「スキルが機能しなかった」と主張する前の必須チェックリスト
- 必須の最初のステップ(28-63行目)の4つの診断ブロックすべてを実行した
- 診断結果の正確な出力(ログ、print文)を貼り付けた
- 「これからわかること」(66-72行目)から1つの根本原因を特定した
- 決定木(91+行目)から最初に一致するパターンを適用した
- シミュレータだけでなく、実機でパターンをテストした
- print文/ログで修正が機能したことを確認した
すべてのチェックボックスがオンになっているが、まだ壊れている場合
- Instruments > Core Animationでプロファイリングする必要があります
- 所要時間: 30-60分(エッジケースでは避けられない)
- ハードコーディング、asyncAfter、または「出荷して期待する」ことは禁止されています
- 回避策を追加する前にガイダンスを求めてください
想定時間コスト
- パターン1: 2-5分
- パターン2: 5-10分
- パターン3: 5-10分
- パターン4: 2-5分
- パターン5: 5-10分
- パターン6: 10-15分
- パターン7: 10-15分
- Instrumentsプロファイリング: 30-60分