rendering-layout-performance

TUI 渲染、布局、性能与备用屏幕生命周期

当 TUI 绘制错误、闪烁、浪费 CPU、无法妥善处理调整大小、破坏滚屏内容，或需要稳健的渲染架构时，请使用此技能。

渲染原则

1. 根据状态渲染。 视图应是当前状态和终端尺寸的纯投影。
2. 批量写入。 构建一帧画面，比较差异或将更新加入队列，然后一次性刷新。避免大量小型写入。
3. 尽量减少终端控制操作。 反复重置样式、移动光标和清屏开销很大，在远程连接上也很显眼。
4. 限制高频来源。 合并日志、指标、鼠标移动、连续的调整大小事件和进度更新。
5. 明确帧的所有权。 全屏渲染器在活动期间拥有屏幕；后台输出应写到其他位置。

布局规则

• 每帧或每次调整大小事件发生时，都根据 width 和 height 计算布局。
• 设置最低可用尺寸，并在低于该阈值时显示清晰的小屏幕提示。
• 优先使用约束、弹性布局、网格、分屏或框架布局原语，而不是随意指定坐标。
• 将焦点、选中项、视口偏移和光标位置保存在 UI 状态中。
• 测试窄屏、宽屏、高屏、极小屏和尺寸不规则的终端。

备用屏幕生命周期

对于全屏应用，如果用户退出后应返回原始滚屏内容，请使用备用屏幕。对于简单输出，如果命令结果应保持可见，则不要使用备用屏幕。

清理时必须恢复：

• 备用屏幕。
• 原始（raw）/半原始（cbreak）模式。
• 鼠标跟踪。
• 带括号的粘贴模式。
• 焦点和扩展键盘模式。
• 光标可见性和样式。
• 若有修改，则恢复终端标题或调色板。

性能检查清单

• UI 循环不会因网络、磁盘、子进程或 API 调用而阻塞。
• 长时间运行的操作通过消息、通道或任务发布进度。
• 将渲染速率限制在人类感知所需的水平，尤其是仪表板。
• 在执行耗时的重新计算前，合并调整大小事件。
• 对大型数据集中的表格和列表进行虚拟化或分页。
• TUI 占用屏幕时，日志记录不会写入 stdout/stderr。
• 如果支持远程终端，应将远程终端和 SSH 延迟纳入测试。

故障模式

症状	可能原因	修复方法
闪烁	清空整个屏幕或反复刷新	比较差异并批量写入，避免全屏清除
空闲时 CPU 占用高	无条件的重绘循环	根据事件渲染，或使用受限频率的定时器
崩溃后 Shell 损坏	未在 panic/exception 时执行清理	使用统一的终端保护机制，并通过 finally/defer/drop 执行清理
布局重叠	使用绝对坐标或尺寸过期	调整大小后重新计算约束
日志出现在 UI 中	备用屏幕处于活动状态时仍向 stdout/stderr 写入日志	使用文件接收器、应用内日志面板或缓冲日志

参考文件

• references/render-loop-patterns.md - 帧缓冲区、脏区域、限流和事件循环。
• references/alternate-screen-lifecycle.md - 设置/拆除检查清单和崩溃恢复。