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
- Pick the component from the index and read its reference file. Start from the complete spinner program below.
- Construct the bubble in your model constructor, apply its styles (most
take
isDark), and store it as a value field. - Start it from your
Init: batch itsInit(),Focus(), orTickcommand with your own. - In
Update, size it fromtea.WindowSizeMsg, send key presses only to the focused bubble, forward every other message, store the returned bubble back, and batch the returned commands. - Place its
View()string inside yourtea.View. - Run
go vet ./...andgo 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 yourtea.WindowSizeMsghandler. - Most style constructors take an
isDark bool:list.DefaultStyles,list.NewDefaultItemStyles,textinput.DefaultStyles,textarea.DefaultStyles,help.DefaultStyles,tree.DefaultStyles. Two do not:table.DefaultStyles()andfilepicker.DefaultStyles()take no argument. Get the bool fromtea.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