bubble-tea

name: bubble-tea description: > 学习和复用 Charmbracelet Bubble Tea / Bubbles / Lip Gloss 的组件写法。 disable-model-invocation: true license: MIT

Bubble Tea 组件索引

本技能用于让 LLM 在编写或调整 Bubble Tea / Bubbles / Lip Gloss 代码前，先吸收本文件中的组件模型、生命周期接入点和常见坑；实现时按任务读取 snippets/ 中的 Go 片段作为可复用知识材料，而不是把片段机械复制成固定框架。

通用接入规则

• 先分发消息：退出、确认、窗口尺寸等应用级消息优先处理；但输入框、textarea 或 list 正在输入/过滤时，先让组件消费普通按键，避免全局快捷键抢输入。
• 子组件更新后必须写回：Bubbles 多为值类型，component.Update(msg) 返回的新组件值要写回 model，得到的 tea.Cmd 也要继续返回或合并。
• 副作用只放在 tea.Cmd：阻塞 I/O、轮询、等待、channel 监听都放进 tea.Cmd；Cmd 只返回 tea.Msg 让 Update 改状态，不要在 Cmd 里直接改 model；在 Cmd 中打开的资源也在 Cmd 内关闭。
• 正确返回命令：Init / Update 返回的是命令值本身，不要提前调用；需要参数时写返回 tea.Cmd 的工厂函数。spinner/progress/timer 等组件返回的后续 cmd 也不要丢。
• View 只渲染状态：不要在 View 里改 model、启动工作或读取外部资源。
• 布局和命令编排：在 WindowSizeMsg 中同步 viewport、list、progress 等依赖终端尺寸的组件；并发命令用 tea.Batch，必须按顺序执行时用 tea.Sequence。

根生命周期骨架

type model struct {
    // 组件状态：input textinput.Model、items list.Model、viewport viewport.Model
    // 业务状态：selectedPath string、loading bool、err error
}

func newModel() model {
    return model{
        // 创建组件；组件创建函数见 snippets
    }
}

func (m model) Init() tea.Cmd {
    // blink、tick、timer init、首次加载、终端能力请求等启动命令
    return nil
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyPressMsg:
        switch msg.String() {
        case "q", "esc", "ctrl+c":
            return m, tea.Quit
        }
    case tea.WindowSizeMsg:
        // 同步依赖终端尺寸的组件宽高
    }

    // 转发给子组件，并把新组件值写回 m
    // var cmd tea.Cmd
    // m.input, cmd = m.input.Update(msg)
    // return m, cmd

    return m, nil
}

func (m model) View() tea.View {
    v := tea.NewView("")
    // v.AltScreen = true
    // v.MouseMode = tea.MouseModeCellMotion
    // v.Cursor = ...
    return v
}

组件与模式表

Reference Links

• Bubble Tea 官方 examples：https://github.com/charmbracelet/bubbletea/tree/main/examples