跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

charmed-bubbles

Use the Bubbles v2 component library (charm.land/bubbles/v2, charmbracelet bubbles) inside a Bubble Tea v2 TUI: list, table, viewport, textinput, textarea, spinner, progress bar, filepicker, tree, paginator, timer, stopwatch, help, and key bindings. Use when adding a ready made widget or TUI component (text input, spinners, scrolling view, file picker) to a terminal app, wiring its focus, size, styles, and messages, or migrating v1 bubbles code. Not for the program loop itself (charmed-bubbletea), raw styling (charmed-lipgloss), or whole forms (charmed-huh).

tpscloud · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add tpscloud/charmedimsure --skill charmed-bubbles

技能说明


name: charmed-bubbles description: "Use the Bubbles v2 component library (charm.land/bubbles/v2, charmbracelet bubbles) inside a Bubble Tea v2 TUI: list, table, viewport, textinput, textarea, spinner, progress bar, filepicker, tree, paginator, timer, stopwatch, help, and key bindings. Use when adding a ready made widget or TUI component (text input, spinners, scrolling view, file picker) to a terminal app, wiring its focus, size, styles, and messages, or migrating v1 bubbles code. Not for the program loop itself (charmed-bubbletea), raw styling (charmed-lipgloss), or whole forms (charmed-huh)." license: "MIT"

Bubbles v2

Add ready-made TUI components to a Bubble Tea v2 program: lists, tables, text inputs, viewports, spinners, progress bars, file pickers, trees, and timers, each wired through the same Init, Update, and View contract.

Import each component from its own package ("charm.land/bubbles/v2/list", .../table, .../viewport, and so on), pinned to v2.2.1. Go blocks headed // examples/... are trimmed from complete programs that build against the pinned modules.

If the project's go.mod still requires github.com/charmbracelet/bubbles (pre-v2), the v2 APIs here do not apply. Use go doc against the project's version and keep its import paths unless the user asks to migrate.

Workflow

  1. Pick the component from the index and read its reference file. Start from the complete spinner program below.
  2. Construct the bubble in your model constructor, apply its styles (most take isDark), and store it as a value field.
  3. Start it from your Init: batch its Init(), Focus(), or Tick command with your own.
  4. In Update, size it from tea.WindowSizeMsg, send key presses only to the focused bubble, forward every other message, store the returned bubble back, and batch the returned commands.
  5. Place its View() string inside your tea.View.
  6. Run go vet ./... and go build ./..., then run the program in a terminal. If a bubble is frozen, empty, or ignores keys, check Mistakes that cost time, fix, and rerun.

The contract most bubbles follow

An interactive bubble is a struct with Update(tea.Msg) (Model, tea.Cmd) and View() string. Note both differences from your top level model: Update returns the bubble's own concrete type (no type assertion needed), and View returns a plain string that you place inside your tea.View. Not every package fits this shape: help.Model.View(k KeyMap) takes the key map to render, key is a plain data package with no model, and cursor is driven by the inputs that embed it. Do not build an interface over "all bubbles" that assumes a zero argument View.

A complete program with one bubble (examples/charmed-bubbles/spinner/main.go); list, table, viewport, and the others slot into the same places:

// examples/charmed-bubbles/spinner/main.go
package main

import (
    "fmt"
    "os"

    "charm.land/bubbles/v2/spinner"
    tea "charm.land/bubbletea/v2"
)

type model struct {
    spinner spinner.Model
}

func (m model) Init() tea.Cmd {
    return m.spinner.Tick // a method value is a tea.Cmd
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    if msg, ok := msg.(tea.KeyPressMsg); ok && (msg.String() == "q" || msg.String() == "ctrl+c") {
        return m, tea.Quit
    }
    var cmd tea.Cmd
    m.spinner, cmd = m.spinner.Update(msg) // store it back; bubbles are values
    return m, cmd
}

func (m model) View() tea.View {
    return tea.NewView(m.spinner.View() + " working, q to quit\n")
}

func main() {
    m := model{spinner: spinner.New(spinner.WithSpinner(spinner.Dot))}
    if _, err := tea.NewProgram(m).Run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

Some bubbles have an Init() tea.Cmd that must run (filepicker reads its directory, timer starts ticking); others start on a method that returns a Cmd (textinput.Focus(), spinner.Tick). Batch these from your own Init.

Rules of thumb:

  • Forward every message to every bubble unless you have a reason not to. Spinners, timers, and progress bars deliver their own tick and frame messages through Update; if you gate on key presses only, they stall.
  • Gate key presses by focus. Two text inputs both receiving keys will both type.
  • Sizes are methods in v2: SetWidth, SetHeight, SetSize, Width(), Height(). Call them from your tea.WindowSizeMsg handler.
  • Most style constructors take an isDark bool: list.DefaultStyles, list.NewDefaultItemStyles, textinput.DefaultStyles, textarea.DefaultStyles, help.DefaultStyles, tree.DefaultStyles. Two do not: table.DefaultStyles() and filepicker.DefaultStyles() take no argument. Get the bool from tea.BackgroundColorMsg (see charmed-bubbletea).
  • Key maps are functions now: textinput.DefaultKeyMap(), not a package variable.

key and help

key.Binding pairs the keys that trigger an action with the help text shown for it. key.Matches(msg, binding) works on a tea.KeyPressMsg. A type with ShortHelp() []key.Binding and FullHelp() [][]key.Binding satisfies help.KeyMap, and help.Model.View(keymap) renders it in one line (or all groups when ShowAll is true).

// examples/charmed-bubbletea/compose/main.go
var keys = keyMap{
    Submit: key.NewBinding(key.WithKeys("enter"), key.WithHelp("enter", "submit")),
    Quit:   key.NewBinding(key.WithKeys("ctrl+c", "esc"), key.WithHelp("esc", "quit")),
}

case tea.KeyPressMsg:
    switch {
    case key.Matches(msg, keys.Quit):
        return m, tea.Quit
    }

m.help.View(keys)   // "enter submit • esc quit"

Disable a binding with SetEnabled(false) and

阅读完整来源 ↗