源码篇第6章 调度台与工位——pi-tui ​

本章导读: 源码路线第 ⑤ 站(产品层)。从核心层切到基础层的
pi-tui包,读tui-main-screen.ts、stdin-buffer.ts和utils.ts。这一站离开模型和循环,去看终端这块“画布”为什么不能随便涂:差分渲染、显示列、不完整的控制序列,各自管着什么。
小A在自己的终端小工具里写了几行渲染代码,发现输出一会儿乱跳,一会儿闪烁,光标停在奇怪的位置。他盯着屏幕:“终端不是一块画布吗?我随便画不就行了?”
“问题就在这:终端不是一张可以随意覆写的画布。”老Z说,“宽度按显示列计算,输入可能带着不完整的控制序列,旧终端未必支持新协议。想让你自己的界面稳定,得先看 pi-tui 怎么面对这些约束。”
本章沿 pi-tui 的渲染与输入路径阅读这些约束。源码证据均来自上游 pi 标签 v1.0.0(提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32,包版本 1.0.0,2026-10-01);不覆盖全部内置组件、主题和图像协议。
组件不直接碰 stdin ​
“先从公共接口进。”老Z打开 packages/tui/src/index.ts,里面导出组件、TUI/Component 接口、TuiMainScreen、TuiAltScreen 与 ProcessTerminal。核心契约在 packages/tui/src/tui.ts 的 Component:组件以 render(width) 返回终端行,并可选实现 handleInput;TuiBase 负责焦点、覆盖层、输入监听和调度渲染。
比喻:调度台与工位
组件是工位,
TuiBase是调度台:工位只说自己要画成什么样(返回行数组),什么时刻刷新由调度台决定。
正常路径是下面这条简化调用链:
ProcessTerminal.start(onInput, onResize)
→ TuiBase.start() / requestRender()
→ TuiMainScreen.doRender() 或 TuiAltScreen.doRender()
→ 组件树的 render(width)
→ terminal.write(...ANSI 输出...)这是源码结构的概括,省略了覆盖层和调试分支。TuiBase.start() 把两条回调注册进 ProcessTerminal.start():data 走 handleTerminalInput,resize 走 requestRender()。链上有个容易看错的环节:resize 回调本身不重绘,只调 requestRender(),全量还是差分,要等稍后的 doRender() 才见分晓。requestRender() 有两条路,对应两种调用强度:
requestRender(force=false) requestRender(force=true)
→ 已请求过?return(合并进本次) → resetRenderState()(清空旧帧账本)
→ renderRequested = true → 清掉未执行的渲染定时器
→ process.nextTick(scheduleRender) → process.nextTick(doRender)
scheduleRender():
计算 delay = max(0, 16ms - 距上次渲染时间)
→ setTimeout(delay) 到点:
renderRequested = false
doRender() ← 全量还是差分在这里才见分晓
若 doRender 期间又来了请求 → 再 scheduleRender()“两条路的差别我猜在 force:它跳过合并,直接刷?”
“只对了一半,force 还会清旧账本。”老Z说,“它先 resetRenderState(),把 previousLines 那些旧帧参照一起清掉,常用于主题变化或尺寸相关事件后的强制全量重建。普通请求才是只置位 renderRequested,靠 MIN_RENDER_INTERVAL_MS = 16 的最小间隔合并,16ms 窗口内来了十个请求也只算一次渲染。还有,force 也先走 process.nextTick,不是同步刷屏。”
“那输入呢?聚焦组件怎么拿到数据?”
“handleTerminalInput 先让注册的监听器过一遍,监听器可返回 { consume: true } 截断、或 { data } 改写当前输入,再交给已聚焦组件,并顺带 requestRender()。”老Z说,“两个细节:一是 key release 序列会被过滤,除非聚焦组件声明了 wantsKeyRelease;二是被聚焦组件若是覆盖层,还会先确认它仍可见,不可见就改派焦点。所以组件不直接管理 stdin 和全局光标,它们共享这一层生命周期。”
“我在组件里想打印个日志调试怎么办?”
“你可以写 stdout,但一旦绕过渲染器,旧帧和光标账本就不再可信,屏幕上会出现你控制不了的残留。”老Z说。
“这账本具体指什么?”
“TuiMainScreen 维护着 previousLines、cursorRow、hardwareCursorRow、maxLinesRendered、previousViewportTop 这一串状态,下一次差分更新全靠它们推算光标该往上还是往下挪。”老Z说,“你直接 console.log 一行,终端光标会动,这些字段却一动不动。下一帧差分按旧账本计算 lineDiff,光标就被挪到一个错误的行,接着就是闪烁和错位。”
“所以调试只能走渲染层。”
“对。”老Z说,“PI_TUI_DEBUG_REDRAW=1 把 fullRender 的原因追加到日志目录下的 pi-tui-debug.log,前提是宿主构造 TUI 时给了 logDirectory,没给就不记;PI_TUI_DEBUG=1 把每次差分渲染的上下文 dump 到 /tmp/tui。这两个都是渲染层内部的观测点,不破坏账本。”
主屏以旧帧为参照 ​
小A:“为什么不干脆每次清屏重画?”
“全量重画实现直观,但输出量更大,滚动历史和视觉连续性都会变差。”老Z说,“TuiMainScreen 的答案是以旧帧为参照:相同行不重写,变化行才通过光标移动、擦除和写入更新。”
// packages/tui/src/tui-main-screen.ts,TuiMainScreen.doRender()(v1.0.0,结构化伪码,非逐行源码)
let newLines = this.render(width);
if (this.previousLines.length === 0 || widthChanged || heightChanged) {
fullRender(/* 是否清屏取决于分支 */);
} else {
// 找出 previousLines 与 newLines 的变化区间,移动光标、擦除并写入变化行
}
this.previousLines = newLines;“关键不在‘比较字符串’本身,而在比较前维护宽度与 ANSI 状态、比较后更新 previousLines。”老Z指着伪码说,“resize 回调只是调 requestRender();尺寸变化要不要全量重绘,是 doRender() 比较当前和先前的宽高之后决定的,别把这个判断算到回调参数头上。”
“为什么宽度变化一定要全量重画,高度变化也是吗?”
“宽高处理不一样。”老Z说,“widthChanged 一律走 fullRender(true),因为换行宽度变了,每一行可能折成不同的样子,差分算不出来。heightChanged 默认也全量,但有一个特例:isTermuxSession() 返回真时跳过全量。Termux 在软键盘弹出/收起时反复改高度,每次都全量重画会把整个历史重放一遍,体验崩溃。”
“内容缩短了怎么办?”
“旧行残留和尾部行清理也在这个函数里处理。”老Z说,“getClearOnShrink() 为真且 newLines.length < maxLinesRendered 且没有覆盖层时,触发 fullRender(true) 清掉空行。maxLinesRendered 是个高水位,只增不减直到清屏,所以缩短会被识别。”
“‘超过宽度就抛错’那条边界,卡的是什么?”
“卡的是组件契约的破坏。”老Z说,“差分更新分支里,非图像行的 visibleWidth(line) > width 会写 pi-tui-crash.log(没有日志目录时写到系统临时目录)、调 stop()、再 throw。原因是差分更新靠 hardwareCursorRow 和 computeLineDiff 推算光标位移,一旦某行实际占了两行,后面所有行号就全错了,与其继续输出错位内容,不如尽早停。这条检查只在差分更新分支有:fullRender() 路径不查,它本身就是全量重建。”
“差分是对所有终端的承诺吗?”
“它是已确认的实现事实,不保证所有终端都不会有视觉闪动。”老Z补充,“该文件还成对发送 \x1b[?2026h/\x1b[?2026l,把一批更新包在一次同步区间中。v1.0.0 不再把整帧拼成一个字符串一次写出,而是经 BoundedTerminalWriter 按 1 MiB 分块写,切块时不拆开 UTF-16 代理对;注释说明这是为了全量重绘时不生成超过 V8 上限的大字符串。代码里同时保留了终端环境与图像行的特殊处理,终端输出并不总是普通文本行。”
把 doRender() 的分支摊开看,能更清楚地看出哪些判断归谁:
doRender() 分支顺序(v1.0.0,TuiMainScreen):
| 条件 | 动作 | 理由 |
| --- | --- | --- |
| 首次渲染(previousLines 为空) | fullRender(false),不清屏 | 假设进入时屏幕是干净的 |
| widthChanged | fullRender(true) | 换行宽度变了,每行折法都可能变 |
| heightChanged 且非 Termux | fullRender(true) | 视口要对齐;Termux 键盘弹收除外 |
| clearOnShrink 且内容缩短且无覆盖层 | fullRender(true) | 高水位回落时清掉旧行残留 |
| firstChanged >= newLines.length | 只清多余行,不重写 | 全部变化都是删除 |
| firstChanged < prevViewportTop | fullRender(true) | 差分只能碰当前视口内的行 |
| 其余 | 差分:清行、写变化行 | 最小化输出与闪烁 |“为什么 firstChanged < prevViewportTop 也要全量?”小A问。
“因为差分更新假设它‘从某行开始写、光标能一路跟着算’。”老Z说,“要改的行一旦在视口上方,往上的光标位移就会把上一屏的内容卷回来,与其猜,不如重建。它和‘超宽抛错’是同一类判断:差分是有前提的捷径,前提不成立就退回全量或停止,不带着坏前提硬算。”
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。