第4章  帧时间线解读：Frame柱状图、绿色/黄色/红色含义、卡顿帧标记

4.1  帧时间线概述

帧时间线（Frame Timeline）是 Android Studio Profiler 中最核心的视觉组件之一。它将每一帧的渲染耗时以柱状图形式沿时间轴排列，让开发者可以一眼识别出哪些帧超过了 16.67ms（60fps）或 8.33ms（120fps）的预算边界，从而快速定位卡顿来源。

帧时间线通常出现在 CPU Profiler 或 GPU Profiler 的 Frame Lifecycle 视图中。每一根竖条代表一个完整帧：从 VSYNC 信号触发、CPU 提交渲染命令、GPU 合成到屏幕刷新完成。柱状图的高度等于该帧的总耗时。

4.2  Frame 柱状图颜色编码体系

Profiler 使用 绿 / 黄 / 红 三色编码来标识帧的“健康状态”。颜色阈值与当前显示设备的刷新率挂钩，默认以 60fps（16.67ms） 为基准线。下表为完整的颜色判定规则：

4.3  卡顿帧标记与 Jank 标签

Profiler 不仅通过颜色警示，还会在红色柱状图上方显示 ❌ Jank 标记。当连续多帧超过预算时，时间轴顶部会出现红色三角警告簇。此外，Frame Lifecycle 面板会列出每一帧的详细阶段耗时：

Frame #1247  总耗时: 42.3ms  状态: JANK
├─ Input       1.2ms
├─ Animation   3.8ms
├─ Measure     8.9ms
├─ Layout      12.4ms
├─ Draw       15.6ms
└─ GPU Wait    0.4ms

上例中 Measure + Layout 合计 21.3ms，占帧预算的 128%，是卡顿的核心原因。通过点击红色柱状图可以跳转到该帧的 Call Stack 火焰图，精确定位是哪个 View 的 onMeasure() 耗时超标。

4.4  帧时间线解读流程图

下面的 SVG 流程图梳理了从“帧提交”到“Jank 标记”的完整判定链路，帮助你建立系统的诊断思维：

4.5  实战：通过柱状图定位卡顿根因

在 Profiler 中操作时遵循以下步骤可以最大化帧时间线的诊断价值：

1. 框选卡顿区间：在帧时间线上按住鼠标左键拖动，选中一段红色柱状图密集的时间范围。
2. 查看 Frame Lifecycle：在下方面板找到 Frame Lifecycle 标签，按耗时降序排列各阶段。
3. 跳转热点帧：双击耗时最高的红色帧，Profiler 自动打开该帧的 Call Stack 火焰图。
4. 定位方法：在火焰图中寻找最宽的“平顶”函数，通常是 ConstraintLayout.onMeasure()、RecyclerView.onBindViewHolder() 或 BitmapFactory.decodeStream() 等。
5. 添加跟踪点：在火焰图中右键点击可疑方法，选择 Add Trace Point 可以持续监控该方法的帧耗时。

4.6  颜色阈值自定义与高级配置

如果默认的 16.67ms 阈值不符合你的性能目标（例如对 120Hz 屏幕或低端设备），可以通过 profiler 配置 调整颜色边界：

// 在 app/build.gradle.kts 中配置 Profiler 阈值 (AGP 8.0+)
android {
    profiler {
        frameThresholdMs = 12   // 将绿色阈值改为 12ms (≈83fps)
        jankThresholdMs  = 24   // 将红色阈值改为 24ms (≈41fps)
    }
}

配置后，Profiler 会使用新的阈值重新渲染帧时间线的颜色，同时 Jank 标记 也会以 jankThresholdMs 为准。该配置仅影响 Profiler 的显示，不影响实际帧率数据采集。

4.7  常见错误与排查清单

4.8  本章小结

• 帧时间线柱状图使用 绿 / 黄 / 红 三色标识帧的健康状态，阈值基于设备刷新率自动设定。
• 红色帧 > 33.33ms 会自动被标记为 Jank，并关联火焰图入口，是卡顿分析的首要目标。
• 通过 Frame Lifecycle 面板可以逐阶段拆解帧耗时（Input / Animation / Measure / Layout / Draw / GPU Wait）。
• 在 build.gradle.kts 中可以自定义 frameThresholdMs 和 jankThresholdMs 以匹配项目性能基线。
• 实战中框选连续红色帧区间 + 双击跳转火焰图是最高效的卡顿定位路径。