Runtime Diagnostics Panel

import { RenderRuntimeDiagnosticsPanel, type RuntimeDiagnosticsState } from 'ds-ui'

Runtime Diagnostics Panel 是运行时诊断面板，用于查看 paint/layout request、热点聚合、调用栈、dirty target 和诊断快照。它是排查“为什么一直重绘”“为什么一直 layout”的主要工具。

在完整应用中，推荐通过 DevTools 开发工具 的 Runtime tab 打开该能力。单独使用 RenderRuntimeDiagnosticsPanel 更适合 demo、测试或自定义诊断容器。

和 运行时诊断指南 的区别：

• 指南讲排查流程和操作顺序。
• 本页讲面板字段、指标含义、过滤方式和典型案例。

核心数据结构

RenderRuntimeDiagnosticsPanel 接收 RuntimeDiagnosticsState：

const state: RuntimeDiagnosticsState = {  paintRequestDebugEnabled: true,  paintRequests: [],} const panel = new RenderRuntimeDiagnosticsPanel({ state })

实际应用中，paintRequests 应由运行时 host 收集。面板只负责展示、过滤、聚合和查看详情。

构造参数

面板区域

Requests 视图

Requests 视图保留时间顺序，适合观察“刚才那一次操作触发了什么”。

重点字段：

Hotspots 视图

Hotspots 按 target、kind、source、reason 聚合，适合观察长时间采样中的最高频来源。

重点字段：

排查时优先看 count 最高且业务上不应持续变化的 hotspot。

过滤器

常用组合：

• 空闲持续重排：kind = layout，按 count 看 hotspots。
• hover 卡顿：query 输入组件名或 hover。
• 弹窗问题：source = overlay。
• 窗口问题：source = window。

debugState

面板自身提供 debugState()，适合测试和诊断：

典型案例

空闲时持续 layout

现象：

kind: layout
target: RenderReviewSidebar
stack: RenderReviewSidebar.setItems -> RenderMedicalRecordEditor.performLayout

判断：

performLayout() 中同步调用子组件 setter，且 setter 即使数据不变也会 markNeedsLayout()。

修复：

• 对传入 items 做签名比较。
• 数据没变时不调用 setter。
• 避免 layout 阶段创建新数组再写入子组件。

空闲时持续 paint

现象：

kind: frame
target: RenderTabs
stack: underline animation reset -> RenderTabs._syncUnderline

判断：

动画控制器可能在没有 tab 切换时反复 reset，导致持续 paint。

修复：

• 只在 active tab 或目标 underline 变化时启动动画。
• 相同值不 reset 动画。
• 动画结束后停止通知。

输入光标导致大文档重绘

现象：

kind: frame
target: RenderMedicalRecordEditor
reason: caret

判断：

光标闪烁不应让整个大文档持续重绘。需要检查 dirty 范围是否被放大。

修复：

• 光标绘制走局部 dirty rect。
• 光标闪烁不触发布局。
• 可视页绘制不要因为光标而扫描全量页。

overlay 请求过多

现象：

source: overlay
target: PopupHost

判断：

popup、tooltip、dropdown 或 modal 可能在滚动/hover 中反复刷新位置或重建内容。

修复：

• 只有 anchor rect 变化时刷新 popup 位置。
• hover tooltip 加延迟和相等判断。
• 弹窗内容数据没变时不重建树。

快照导出

导出快照适合现场问题复现：

1. 开启 paint request debug。
2. 执行最小复现动作。
3. 导出 Runtime Diagnostics Snapshot。
4. 提交给开发分析。

快照应脱敏：

• 不包含患者隐私。
• 不包含账号 token。
• 不包含完整病历正文。
• 不包含超大业务数组。

性能注意事项

• 开启 stack 采集会增加额外开销，只在排查时打开。
• 请求历史应有上限，不要无限保存。
• 面板本身也会布局和绘制，复杂问题复现后应关闭它再验证真实性能。
• 详情 ObjectInspector 展开大对象时应分批，避免诊断工具造成新的卡顿。

和其他工具的分工

相关文档

• 运行时诊断
• DevTools 开发工具
• ObjectInspector 对象查看器
• Paint 性能
• Layout 性能
• Diagnostics API 参考