Go tcell 窗口缩小后旧字符残留怎么办

我在 tcell 做终端面板时遇到过一个很像“字符没有被覆盖”的现象：窗口变窄后，边框或标题看起来还留着缩小前的内容，窗口再放大时旧字符又出现在不该出现的位置。先给结论：收到 EventResize 后要以新尺寸重算布局；如果显示状态和 tcell 内部的单元格状态可能已经不同步，就在 resize 分支调用 Screen.Sync()，随后完整重绘并 Show()。不要只给几个原坐标重新写一遍。

官方地址：https://github.com/gdamore/tcell

先确认残留确实发生在窗口缩放之后

不要先把问题归结为某一处 SetContent。tcell 官方教程说明，应用在初始化时以及终端尺寸变化时都会收到 EventResize，事件里可以通过 Size() 取得新宽高。若应用还拿旧的宽高计算右边界，缩小后就可能继续把标题、边框或列表绘制到已经变化的布局区域。

我通常先把 resize 分支写得很明确，只保留新尺寸，并让后续渲染函数重新取值：

case *tcell.EventResize:
    width, height := ev.Size()
    // 记录本轮的新尺寸，后续布局不能继续使用旧窗口宽高。
    model.width, model.height = width, height
    // 让渲染函数按新边界重算面板、标题和文本截断位置。
    model.layoutDirty = true

这里的 model 是应用自己的状态，不是 tcell 的内置类型。关键是把尺寸变化当成一次布局输入，而不是普通按键那样只改一个字符。

为什么窗口缩小后局部重绘会留下旧字符

tcell 的 CellBuffer.Resize 在改变缓冲区尺寸时会复制原来与新区域重叠的内容，并让这些单元格进入待重绘状态。这个设计方便应用继续使用逻辑内容，但也意味着“尺寸变了”并不自动等于“你的业务画面已经按新布局重建”。如果渲染函数只更新标题和几块变化区域，旧的边框、空白区或缓存文本就可能继续参与显示。

因此，排查时要分两层看：

• 应用层：是否用 ev.Size() 更新布局，是否清掉了不再存在的列表项和边框区域。
• 显示层：物理终端是否与 tcell 的逻辑单元格一致，是否需要全量同步。

resize 分支应该怎样调用 Sync

官方教程在收到 EventResize 时直接调用 s.Sync()；官方接口说明也把 resize 事件列为 Sync() 的典型使用场景。对一个自己维护渲染循环的程序，我会把它和“重新布局、重新绘制”放在同一个分支里：

func handleEvent(s tcell.Screen, ev tcell.Event, model *Model) bool {
    switch ev := ev.(type) {
    case *tcell.EventResize:
        w, h := ev.Size()
        // 先保存新尺寸，避免 render 仍按旧边界写入。
        model.width, model.height = w, h
        // resize 可能让物理终端与逻辑缓冲区失步，先请求整屏同步。
        s.Sync()
        // 完整重画当前模型，而不是只补写发生变化的几个字符。
        render(s, model)
        // 让本轮逻辑内容真正出现在终端上。
        s.Show()
    case *tcell.EventKey:
        if ev.Key() == tcell.KeyEscape || ev.Key() == tcell.KeyCtrlC {
            return false
        }
    }
    return true
}

这段代码的重点不是把 Sync 当成每帧刷新函数，而是只在 resize 或确实怀疑终端失步时使用。普通按键更新仍然可以由 SetContent、PutStr 和 Show 完成。

Clear 和 Sync 不要混为一谈

Clear() 在 tcell 接口中等价于使用默认样式把屏幕填充为空格，作用是修改逻辑屏幕内容；这个变化要等 Show() 或 Sync() 才会可见。Sync() 则会把所有可见单元格重新写到物理显示，成本更高，也可能比普通增量显示更闪烁。

如果你的绘制函数本来就会覆盖当前屏幕的每个可见单元格，可以只在 resize 事件后调用 Sync 再重绘。如果布局里有明确的旧区域，也可以先清空逻辑内容再绘制：

func render(s tcell.Screen, model *Model) {
    // 清掉本轮屏幕上的逻辑内容，避免旧列表项和边框继续参与绘制。
    s.Clear()
    drawFrame(s, model.width, model.height)
    drawContent(s, model)
}

但不要把 Clear() 当成对物理终端的强制修复；如果终端本身已经和逻辑缓冲区失步，仍应在 resize 分支使用 Sync()。同样，也不要每一帧无条件 Clear 加 Sync，否则会放大闪烁和刷新成本。

还有两个容易被忽略的边界

第一，宽字符和 emoji 可能占用两个屏幕单元格。tcell 的接口文档提醒，宽字符写在最后一列时会被替换为单宽空格；所以缩小后要重新按新宽度截断文本，不能把旧的列坐标直接复用。

第二，若你只绘制变化行，就必须自行管理“上一帧存在、本帧不存在”的区域。例如列表从 20 行缩小到 8 行，不能只画前 8 行，还要清理剩余区域，或者改为 resize 时整屏重绘。这个问题属于渲染策略，不是 tcell 自动知道的业务布局。

一份可执行的排查顺序

结论

Go tcell 窗口缩小后的旧字符残留，优先按“尺寸输入、业务布局、逻辑缓冲区、物理终端”四层排查。收到 EventResize 后更新尺寸并完整重绘；如果可能存在显示失步，就调用一次 Sync()。Clear() 只解决逻辑内容填充，不能替代 resize 场景下的整屏同步。

常见问题

收到 EventResize 后只调用 Show 可以吗？

如果应用已经完整覆盖当前可见区域，并且逻辑缓冲区与物理终端一致，通常可以；一旦出现旧字符残留或终端失步，应使用 Sync() 并重新渲染。

每次窗口变化都必须先 Clear 吗？

不一定。完整 render 已经覆盖所有可见单元格时可以不额外 Clear；如果采用局部绘制，就要清理上一帧不再存在的区域。

为什么不用每帧 Sync 彻底解决？

Sync() 会重写所有可见单元格，开销和视觉扰动都高于普通增量显示。把它限定在 resize 或确有失步证据的场景更合适。