Go Bubble Tea 怎么响应窗口尺寸变化重新布局

我第一次给 Bubble Tea 的列表界面加“可调整窗口”时，最容易犯的错是把宽度判断散落在按键处理和渲染字符串里。窗口一变，标题、正文和底部提示各算一套宽度，最后不是换行错位，就是缩小窗口后残留旧布局。更稳的做法是：让 WindowSizeMsg 进入 Update，把宽高保存到模型，View 每次只根据模型重新计算布局。

官方地址：https://github.com/charmbracelet/bubbletea

我为什么把窗口尺寸当成 Update 的消息

Bubble Tea 的核心分工很清楚：model 保存状态，Update 接收消息并返回新状态，View 根据状态生成界面。官方文档把 WindowSizeMsg 定义为包含 Width 和 Height 的消息，并说明它会在程序启动时先送达，之后在终端尺寸改变时送达。

这意味着重新布局不是一个需要额外 goroutine 的“监听器”。它只是一次普通的消息更新：收到新尺寸，更新模型，随后由 Bubble Tea 重新调用 View。我觉得这条边界很重要，因为它让所有布局输入都有同一个来源，窗口变化不会绕过状态层。

旧写法的问题：View 里到处猜当前宽度

如果每个组件都自己读取终端，或者在字符串拼接时临时减去边距，布局规则会变成隐形的全局状态。比如列表按整个窗口宽度换行，底部帮助栏却按固定 80 列截断；窗口从宽变窄时，某个子区域还可能继续使用上一次的列数。

我现在会先在模型里明确记录尺寸，再把“内容区宽度”“列表列数”“帮助栏是否换行”当作同一轮渲染的派生值。不要把派生值反写成多个互相独立的状态，否则下一次 WindowSizeMsg 到来时，很难判断应该更新哪一份。

新规则：在 WindowSizeMsg 分支中更新模型

下面这个模型只保留当前窗口的原始宽高。示例使用 Bubble Tea v2 的导入路径；项目如果仍在使用旧版依赖，应以自身模块声明和对应官方文档为准。

package main

import (
    "strings"

    tea "charm.land/bubbletea/v2"
    "github.com/charmbracelet/lipgloss"
)

type model struct {
    width  int
    height int
    items  []string
}

func (m model) Init() tea.Cmd {
    // 不需要启动额外命令，初始窗口尺寸会由 Bubble Tea 送入 Update。
    return nil
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        // 只保存原始尺寸，具体列宽和换行留给 View 的布局函数计算。
        m.width = msg.Width
        m.height = msg.Height
    }

    // 返回更新后的值，否则本次尺寸消息不会进入下一次渲染。
    return m, nil
}

func (m model) View() tea.View {
    contentWidth := maxInt(m.width-4, 12)
    rows := make([]string, 0, len(m.items))
    for _, item := range m.items {
        // 每一项使用同一个内容区宽度，避免组件各算各的边距。
        rows = append(rows, lipgloss.NewStyle().Width(contentWidth).Render(item))
    }

    body := strings.Join(rows, "\n")
    return tea.NewView(body)
}

func maxInt(a, b int) int {
    // 初始尺寸可能还没有到达，给布局一个可渲染的最小宽度。
    if a > b {
        return a
    }
    return b
}

这里的关键不是把每一行文字“刷新”一遍，而是让刷新所需的输入收敛到 model.width 和 model.height。Update 返回的是新的 model；如果只修改了局部变量却返回旧值，界面当然不会按新尺寸布局。

代码对比：View 只做一次布局计算

实际项目通常不止一个列表，还会有左侧导航、主内容区和底部提示。我的经验是先计算区域边界，再把边界传给子渲染函数，而不是让每个函数再次读取 m.width。这样窗口放大时可以增加主内容宽度，窗口缩小时也能统一降级。

type layout struct {
    sidebar int
    main    int
    footer  int
}

func (m model) currentLayout() layout {
    // 预留边距后再分配区域，避免边框和内容挤在同一列。
    usable := maxInt(m.width-6, 30)
    sidebar := 20
    if usable 

这段代码展示的是布局关系，不是一个完整可运行程序：currentLayout 只从 model 的尺寸派生区域宽度，View 再把同一结果交给侧栏、主区和页脚。正式项目还要根据所用的 Lip Gloss 版本调整样式组合方式，但“尺寸进 Update，布局在 View 集中派生”的职责不变。

兼容注意：初始零值、窄窗口和 Windows

第一，初始化阶段不要假定宽高已经可用。官方说明虽然会在程序启动时发送一次尺寸消息，但模型的默认零值仍然可能先参与某段初始化逻辑，因此宽度计算最好有明确的最小值。

第二，窄窗口不是异常到可以忽略的情况。可以把侧栏改成更短的标签、隐藏非必要区域，或者让主内容只保留一列。不要简单地把负数宽度传给样式函数；先完成边界收敛，界面才不会在缩放时抖动。

第三，WindowSizeMsg 的动态变化依赖平台能力。官方文档特别指出，Windows 不支持 SIGWINCH，因此不能把“所有平台都能实时收到 resize”写成保证。Windows 上应提供可接受的静态布局或手动刷新策略，并把这条限制写进产品说明。

我的采用建议

如果只是一个固定宽度的短命令行工具，直接让 View 输出固定布局就够了；一旦界面有分栏、换行、表格或可折叠区域，就值得把尺寸作为 model 状态管理。我的落地顺序是：先接住 WindowSizeMsg，再集中写一个布局函数，最后才为窄窗口增加降级方案。

这样做的代价是多了几个尺寸边界和布局单元测试，但换来的是消息、状态和渲染职责清楚。对需要在 Linux、macOS 和 Windows 间分发的 Bubble Tea 程序，平台限制也能在同一层被看见，而不会变成用户报告“缩放不生效”后才临时修补。

常见问题

需要手动调用 tea.WindowSize() 吗？

通常不需要。官方文档说明程序启动和窗口尺寸变化时会自动发送 WindowSizeMsg；只有确实要主动查询当前尺寸时，才考虑使用对应命令。

为什么收到 WindowSizeMsg 后界面仍然不变？

先检查 Update 是否把消息里的宽高写入 model，并返回了更新后的 model；再检查 View 是否真的使用了这些字段，而不是仍在使用固定常量。

参考资料：Bubble Tea 官方仓库与 Go 包文档。本文示例中的结构图是原创静态说明图，不代表实际终端运行结果。