forked from Mirrors/bubbletea
243 lines
7.3 KiB
Markdown
243 lines
7.3 KiB
Markdown
Bubble Tea Basics
|
||
=================
|
||
|
||
Bubble Tea is based on the functional design paradigms of [The Elm
|
||
Architecture][elm], which happens to work nicely with Go. It's a delightful way
|
||
to build applications.
|
||
|
||
This tutorial assumes you have a working knowledge of Go.
|
||
|
||
By the way, the non-annotated source code for this program is available
|
||
[on GitHub][tut-source].
|
||
|
||
[elm]: https://guide.elm-lang.org/architecture/
|
||
[tut-source]:https://github.com/charmbracelet/bubbletea/tree/master/tutorials/basics
|
||
|
||
## Enough! Let's get to it.
|
||
|
||
For this tutorial, we're making a shopping list.
|
||
|
||
To start we'll define our package and import some libraries. Our only external
|
||
import will be the Bubble Tea library, which we'll call `tea` for short.
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"fmt"
|
||
"os"
|
||
|
||
tea "github.com/charmbracelet/bubbletea"
|
||
)
|
||
```
|
||
|
||
Bubble Tea programs are comprised of a **model** that describes the application
|
||
state and three simple methods on that model:
|
||
|
||
* **Init**, a function that returns an initial command for the application to run.
|
||
* **Update**, a function that handles incoming events and updates the model accordingly.
|
||
* **View**, a function that renders the UI based on the data in the model.
|
||
|
||
## The Model
|
||
|
||
So let's start by defining our model which will store our application's state.
|
||
It can be any type, but a `struct` usually makes the most sense.
|
||
|
||
```go
|
||
type model struct {
|
||
choices []string // items on the to-do list
|
||
cursor int // which to-do list item our cursor is pointing at
|
||
selected map[int]struct{} // which to-do items are selected
|
||
}
|
||
```
|
||
|
||
## Initialization
|
||
|
||
Next, we’ll define our application’s initial state. In this case, we’re defining
|
||
a function to return our initial model, however, we could just as easily define
|
||
the initial model as a variable elsewhere, too.
|
||
|
||
```go
|
||
func initialModel() model {
|
||
return model{
|
||
// Our to-do list is a grocery list
|
||
choices: []string{"Buy carrots", "Buy celery", "Buy kohlrabi"},
|
||
|
||
// A map which indicates which choices are selected. We're using
|
||
// the map like a mathematical set. The keys refer to the indexes
|
||
// of the `choices` slice, above.
|
||
selected: make(map[int]struct{}),
|
||
}
|
||
}
|
||
```
|
||
|
||
Next, we define the `Init` method. `Init` can return a `Cmd` that could perform
|
||
some initial I/O. For now, we don't need to do any I/O, so for the command,
|
||
we'll just return `nil`, which translates to "no command."
|
||
|
||
```go
|
||
func (m model) Init() tea.Cmd {
|
||
// Just return `nil`, which means "no I/O right now, please."
|
||
return nil
|
||
}
|
||
```
|
||
|
||
## The Update Method
|
||
|
||
Next up is the update method. The update function is called when ”things
|
||
happen.” Its job is to look at what has happened and return an updated model in
|
||
response. It can also return a `Cmd` to make more things happen, but for now
|
||
don't worry about that part.
|
||
|
||
In our case, when a user presses the down arrow, `Update`’s job is to notice
|
||
that the down arrow was pressed and move the cursor accordingly (or not).
|
||
|
||
The “something happened” comes in the form of a `Msg`, which can be any type.
|
||
Messages are the result of some I/O that took place, such as a keypress, timer
|
||
tick, or a response from a server.
|
||
|
||
We usually figure out which type of `Msg` we received with a type switch, but
|
||
you could also use a type assertion.
|
||
|
||
For now, we'll just deal with `tea.KeyMsg` messages, which are automatically
|
||
sent to the update function when keys are pressed.
|
||
|
||
```go
|
||
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
|
||
switch msg := msg.(type) {
|
||
|
||
// Is it a key press?
|
||
case tea.KeyMsg:
|
||
|
||
// Cool, what was the actual key pressed?
|
||
switch msg.String() {
|
||
|
||
// These keys should exit the program.
|
||
case "ctrl+c", "q":
|
||
return m, tea.Quit
|
||
|
||
// The "up" and "k" keys move the cursor up
|
||
case "up", "k":
|
||
if m.cursor > 0 {
|
||
m.cursor--
|
||
}
|
||
|
||
// The "down" and "j" keys move the cursor down
|
||
case "down", "j":
|
||
if m.cursor < len(m.choices)-1 {
|
||
m.cursor++
|
||
}
|
||
|
||
// The "enter" key and the spacebar (a literal space) toggle
|
||
// the selected state for the item that the cursor is pointing at.
|
||
case "enter", " ":
|
||
_, ok := m.selected[m.cursor]
|
||
if ok {
|
||
delete(m.selected, m.cursor)
|
||
} else {
|
||
m.selected[m.cursor] = struct{}{}
|
||
}
|
||
}
|
||
}
|
||
|
||
// Return the updated model to the Bubble Tea runtime for processing.
|
||
// Note that we're not returning a command.
|
||
return m, nil
|
||
}
|
||
```
|
||
|
||
You may have noticed that <kbd>ctrl+c</kbd> and <kbd>q</kbd> above return
|
||
a `tea.Quit` command with the model. That’s a special command which instructs
|
||
the Bubble Tea runtime to quit, exiting the program.
|
||
|
||
## The View Method
|
||
|
||
At last, it’s time to render our UI. Of all the methods, the view is the
|
||
simplest. We look at the model in its current state and use it to return
|
||
a `string`. That string is our UI!
|
||
|
||
Because the view describes the entire UI of your application, you don’t have to
|
||
worry about redrawing logic and stuff like that. Bubble Tea takes care of it
|
||
for you.
|
||
|
||
```go
|
||
func (m model) View() string {
|
||
// The header
|
||
s := "What should we buy at the market?\n\n"
|
||
|
||
// Iterate over our choices
|
||
for i, choice := range m.choices {
|
||
|
||
// Is the cursor pointing at this choice?
|
||
cursor := " " // no cursor
|
||
if m.cursor == i {
|
||
cursor = ">" // cursor!
|
||
}
|
||
|
||
// Is this choice selected?
|
||
checked := " " // not selected
|
||
if _, ok := m.selected[i]; ok {
|
||
checked = "x" // selected!
|
||
}
|
||
|
||
// Render the row
|
||
s += fmt.Sprintf("%s [%s] %s\n", cursor, checked, choice)
|
||
}
|
||
|
||
// The footer
|
||
s += "\nPress q to quit.\n"
|
||
|
||
// Send the UI for rendering
|
||
return s
|
||
}
|
||
```
|
||
|
||
## All Together Now
|
||
|
||
The last step is to simply run our program. We pass our initial model to
|
||
`tea.NewProgram` and let it rip:
|
||
|
||
```go
|
||
func main() {
|
||
p := tea.NewProgram(initialModel())
|
||
if _, err := p.Run(); err != nil {
|
||
fmt.Printf("Alas, there's been an error: %v", err)
|
||
os.Exit(1)
|
||
}
|
||
}
|
||
```
|
||
|
||
## What’s Next?
|
||
|
||
This tutorial covers the basics of building an interactive terminal UI, but
|
||
in the real world you'll also need to perform I/O. To learn about that have a
|
||
look at the [Command Tutorial][cmd]. It's pretty simple.
|
||
|
||
There are also several [Bubble Tea examples][examples] available and, of course,
|
||
there are [Go Docs][docs].
|
||
|
||
[cmd]: http://github.com/charmbracelet/bubbletea/tree/master/tutorials/commands/
|
||
[examples]: http://github.com/charmbracelet/bubbletea/tree/master/examples
|
||
[docs]: https://pkg.go.dev/github.com/charmbracelet/bubbletea?tab=doc
|
||
|
||
## Additional Resources
|
||
|
||
* [Libraries we use with Bubble Tea](https://github.com/charmbracelet/bubbletea/#libraries-we-use-with-bubble-tea)
|
||
* [Bubble Tea in the Wild](https://github.com/charmbracelet/bubbletea/#bubble-tea-in-the-wild)
|
||
|
||
### Feedback
|
||
|
||
We'd love to hear your thoughts on this tutorial. Feel free to drop us a note!
|
||
|
||
* [Twitter](https://twitter.com/charmcli)
|
||
* [The Fediverse](https://mastodon.technology/@charm)
|
||
* [Slack](https://charm.sh/slack)
|
||
|
||
***
|
||
|
||
Part of [Charm](https://charm.sh).
|
||
|
||
<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>
|
||
|
||
Charm热爱开源 • Charm loves open source
|