README
¶
常见问题
以下是关于 list bubble（列表气泡）的一些最常见问题。
添加自定义项
要创建自定义项，您需要完成几个步骤。首先，它们需要实现 list.Item 和 list.DefaultItem 接口。
// Item 是出现在列表中的一个项。
type Item interface {
// FilterValue 是我们在过滤列表时针对此项进行过滤所使用的值。
FilterValue() string
}
// DefaultItem 描述了一个设计用于与 DefaultDelegate（默认委托）配合使用的项。
type DefaultItem interface {
Item
Title() string // 返回项的标题
Description() string // 返回项的描述
}
您可以在我们的 Kancli 项目中看到一个可运行的示例，该项目专门为 Bubble Tea 中的列表和组合视图教程而构建。
自定义样式
列表项的渲染（和行为）是通过 ItemDelegate 接口完成的。起初可能会有点令人困惑，但它允许列表变得非常灵活和强大。
如果您只是想更改默认样式，可以这样做：
import "github.com/purpose168/bubbles-cn/list"
// 创建一个新的默认委托
d := list.NewDefaultDelegate()
// 更改颜色
c := lipgloss.Color("#6f03fc") // 设置紫色
d.Styles.SelectedTitle = d.Styles.SelectedTitle.Foreground(c).BorderLeftForeground(c) // 设置选中标题的前景色和左边框颜色
d.Styles.SelectedDesc = d.Styles.SelectedTitle.Copy() // 在此处复用标题样式
// 使用我们的委托初始化列表模型
width, height := 80, 40 // 设置宽度和高度
l := list.New(listItems, d, width, height) // 创建列表
// 您也可以动态更改委托
l.SetDelegate(d) // 设置新的委托
这段代码将替换 list-default 示例中的这一行。
要完全控制列表项的渲染方式，您也可以定义自己的 ItemDelegate（示例）。
Documentation
¶
Overview ¶
Package list 提供了一个功能丰富的 Bubble Tea 组件，用于浏览通用项目列表。 它具有可选的过滤、分页、帮助、状态消息和用于指示活动的 spinner 等功能。
Index ¶
- Variables
- type DefaultDelegate
- func (d DefaultDelegate) FullHelp() [][]key.Binding
- func (d DefaultDelegate) Height() int
- func (d DefaultDelegate) Render(w io.Writer, m Model, index int, item Item)
- func (d *DefaultDelegate) SetHeight(i int)
- func (d *DefaultDelegate) SetSpacing(i int)
- func (d DefaultDelegate) ShortHelp() []key.Binding
- func (d DefaultDelegate) Spacing() int
- func (d DefaultDelegate) Update(msg tea.Msg, m *Model) tea.Cmd
- type DefaultItem
- type DefaultItemStyles
- type FilterFunc
- type FilterMatchesMsg
- type FilterState
- type Item
- type ItemDelegate
- type KeyMap
- type Model
- func (m Model) Cursor() int
- func (m *Model) CursorDown()
- func (m *Model) CursorUp()
- func (m *Model) DisableQuitKeybindings()
- func (m Model) FilterState() FilterState
- func (m Model) FilterValue() string
- func (m Model) FilteringEnabled() bool
- func (m Model) FullHelp() [][]key.Binding
- func (m Model) GlobalIndex() int
- func (m *Model) GoToEnd()
- func (m *Model) GoToStart()
- func (m Model) Height() int
- func (m Model) Index() int
- func (m *Model) InsertItem(index int, item Item) tea.Cmd
- func (m Model) IsFiltered() bool
- func (m Model) Items() []Item
- func (m Model) MatchesForItem(index int) []int
- func (m *Model) NewStatusMessage(s string) tea.Cmd
- func (m *Model) NextPage()
- func (m *Model) PrevPage()
- func (m *Model) RemoveItem(index int)
- func (m *Model) ResetFilter()
- func (m *Model) ResetSelected()
- func (m *Model) Select(index int)
- func (m Model) SelectedItem() Item
- func (m *Model) SetDelegate(d ItemDelegate)
- func (m *Model) SetFilterState(state FilterState)
- func (m *Model) SetFilterText(filter string)
- func (m *Model) SetFilteringEnabled(v bool)
- func (m *Model) SetHeight(v int)
- func (m *Model) SetItem(index int, item Item) tea.Cmd
- func (m *Model) SetItems(i []Item) tea.Cmd
- func (m *Model) SetShowFilter(v bool)
- func (m *Model) SetShowHelp(v bool)
- func (m *Model) SetShowPagination(v bool)
- func (m *Model) SetShowStatusBar(v bool)
- func (m *Model) SetShowTitle(v bool)
- func (m *Model) SetSize(width, height int)
- func (m *Model) SetSpinner(spinner spinner.Spinner)
- func (m *Model) SetStatusBarItemName(singular, plural string)
- func (m *Model) SetWidth(v int)
- func (m Model) SettingFilter() bool
- func (m Model) ShortHelp() []key.Binding
- func (m Model) ShowFilter() bool
- func (m Model) ShowHelp() bool
- func (m *Model) ShowPagination() bool
- func (m Model) ShowStatusBar() bool
- func (m Model) ShowTitle() bool
- func (m *Model) StartSpinner() tea.Cmd
- func (m Model) StatusBarItemName() (string, string)
- func (m *Model) StopSpinner()
- func (m *Model) ToggleSpinner() tea.Cmd
- func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
- func (m Model) View() string
- func (m Model) VisibleItems() []Item
- func (m Model) Width() int
- type Rank
- type Styles
Constants ¶
This section is empty.
Variables ¶
var NewModel = New
NewModel returns a new model with sensible defaults.
Deprecated: use New instead.
Functions ¶
This section is empty.
Types ¶
type DefaultDelegate ¶
type DefaultDelegate struct {
ShowDescription bool
Styles DefaultItemStyles
UpdateFunc func(tea.Msg, *Model) tea.Cmd
ShortHelpFunc func() []key.Binding
FullHelpFunc func() [][]key.Binding
// contains filtered or unexported fields
}
DefaultDelegate 是一个设计用于列表中的标准委托。 它由 DefaultItemStyles 设置样式，可以根据需要自定义。
通过将 Description 设置为 false 可以隐藏描述行， 这会将列表渲染为单行项目。项目之间的间距可以通过 SetSpacing 方法设置。
设置 UpdateFunc 是可选的。如果设置了，它将在 ItemDelegate 被调用时被调用， 而 ItemDelegate 是在列表的 Update 函数被调用时被调用的。
设置 ShortHelpFunc 和 FullHelpFunc 是可选的。它们可以设置为在列表的默认简短和完整帮助菜单中包含项目。
func NewDefaultDelegate ¶
func NewDefaultDelegate() DefaultDelegate
NewDefaultDelegate 创建一个带有默认样式的新委托。
func (DefaultDelegate) FullHelp ¶
func (d DefaultDelegate) FullHelp() [][]key.Binding
FullHelp 返回委托的完整帮助。
func (DefaultDelegate) Height ¶
func (d DefaultDelegate) Height() int
Height 返回委托的首选高度。 这仅在 ShowDescription 为 true 时有效，否则高度始终为 1。
func (*DefaultDelegate) SetSpacing ¶
func (d *DefaultDelegate) SetSpacing(i int)
SetSpacing 设置委托的间距。
func (DefaultDelegate) ShortHelp ¶
func (d DefaultDelegate) ShortHelp() []key.Binding
ShortHelp 返回委托的简短帮助。
type DefaultItem ¶
DefaultItem 描述了一个设计用于与 DefaultDelegate 一起工作的项目。
type DefaultItemStyles ¶
type DefaultItemStyles struct {
// 正常状态。
NormalTitle lipgloss.Style
NormalDesc lipgloss.Style
// 选中项状态。
SelectedTitle lipgloss.Style
SelectedDesc lipgloss.Style
// 暗淡状态，用于过滤器输入最初激活时。
DimmedTitle lipgloss.Style
DimmedDesc lipgloss.Style
// 匹配当前过滤器的字符（如果有）。
FilterMatch lipgloss.Style
}
DefaultItemStyles 定义了默认列表项的样式。 有关这些样式何时生效，请参见 DefaultItemView。
func NewDefaultItemStyles ¶
func NewDefaultItemStyles() (s DefaultItemStyles)
NewDefaultItemStyles 返回默认项目的样式定义。 有关这些样式何时生效，请参见 DefaultItemView。
type FilterFunc ¶
FilterFunc 接受一个术语和一个要搜索的字符串列表（由 Item#FilterValue 定义）。 它应返回一个排序后的排名列表。
type FilterMatchesMsg ¶
type FilterMatchesMsg []filteredItem
FilterMatchesMsg 包含过滤期间匹配项的数据。该消息应路由到 Update 进行处理。
type FilterState ¶
type FilterState int
FilterState 描述模型上的当前过滤状态。
const ( Unfiltered FilterState = iota // 未设置过滤器 Filtering // 用户正在积极设置过滤器 FilterApplied // 应用了过滤器且用户未编辑过滤器 )
可能的过滤状态。
type Item ¶
type Item interface {
// FilterValue 是我们在过滤列表时用于与此项目进行过滤的值。
FilterValue() string
}
Item 是列表中显示的项目。
type ItemDelegate ¶
type ItemDelegate interface {
// Render 渲染项目的视图。
Render(w io.Writer, m Model, index int, item Item)
// Height 是列表项的高度。
Height() int
// Spacing 是列表项之间的水平间隙大小（以单元格为单位）。
Spacing() int
// Update 是项目的更新循环。列表更新循环中的所有消息都将通过这里，
// 除非用户正在设置过滤器。使用此方法执行适合此委托的项目级更新。
Update(msg tea.Msg, m *Model) tea.Cmd
}
ItemDelegate 封装了所有列表项的通用功能。将此逻辑与项目本身分离的好处是， 您可以更改项目的功能而无需更改实际项目本身。
注意，如果委托还实现了 help.KeyMap 接口，与委托相关的帮助项将被添加到帮助视图中。
type KeyMap ¶
type KeyMap struct {
// 浏览列表时使用的按键绑定。
CursorUp key.Binding // 光标向上
CursorDown key.Binding // 光标向下
NextPage key.Binding // 下一页
PrevPage key.Binding // 上一页
GoToStart key.Binding // 前往开始
GoToEnd key.Binding // 前往结束
Filter key.Binding // 过滤器
ClearFilter key.Binding // 清除过滤器
// 设置过滤器时使用的按键绑定。
CancelWhileFiltering key.Binding // 取消过滤
AcceptWhileFiltering key.Binding // 接受过滤
// 帮助切换按键绑定。
ShowFullHelp key.Binding // 显示完整帮助
CloseFullHelp key.Binding // 关闭完整帮助
// 退出按键绑定。在过滤时不会被捕获。
Quit key.Binding // 退出
// 强制退出按键绑定。在过滤时也会被捕获。
ForceQuit key.Binding // 强制退出
}
KeyMap 定义了按键绑定。它满足 help.KeyMap 接口，用于渲染菜单。
type Model ¶
type Model struct {
Title string
Styles Styles
InfiniteScrolling bool
// 用于导航列表的按键映射。
KeyMap KeyMap
// Filter 用于过滤列表。
Filter FilterFunc
// 简短和完整帮助视图的附加按键映射。这允许您在不重新实现帮助组件的情况下
// 向帮助菜单添加附加按键映射。当然，如果您需要更多灵活性，
// 也可以禁用列表的帮助组件并实现一个新的。
AdditionalShortHelpKeys func() []key.Binding
AdditionalFullHelpKeys func() []key.Binding
Paginator paginator.Model
Help help.Model
FilterInput textinput.Model
// 状态消息应保持可见的时间。默认情况下为 1 秒。
StatusMessageLifetime time.Duration
// contains filtered or unexported fields
}
Model 包含此组件的状态。
func New ¶
func New(items []Item, delegate ItemDelegate, width, height int) Model
New 返回一个具有合理默认值的新模型。
func (*Model) DisableQuitKeybindings ¶
func (m *Model) DisableQuitKeybindings()
DisableQuitKeybindings 是一个辅助函数，用于禁用用于退出的按键绑定， 以防您想在应用程序的其他地方处理此操作。
func (Model) GlobalIndex ¶
GlobalIndex 返回当前选定项目的索引，因为它存储在 未过滤的项目列表中。此值可以与 SetItem() 一起使用。
func (Model) Index ¶
Index 返回当前选定项目的索引，因为它存储在 过滤的项目列表中。 将此值与 SetItem() 一起使用可能不正确，请考虑使用 GlobalIndex() 代替。
func (*Model) InsertItem ¶
InsertItem 在给定索引处插入一个项目。如果索引超出上界， 项目将被追加。这返回一个命令。
func (Model) MatchesForItem ¶
MatchesForItem 返回由当前过滤器匹配的符文位置（如果有）。 使用此方法来设置由活动过滤器匹配的符文的样式。
请参阅 DefaultItemView 以获取使用示例。
func (*Model) NewStatusMessage ¶
NewStatusMessage 设置一个新的状态消息，该消息将显示有限的时间。 注意这也返回一个命令。
func (*Model) RemoveItem ¶
RemoveItem 移除给定索引处的项目。如果索引超出范围， 这将是空操作。O(n) 复杂度，在 TUI 的情况下可能不会成为问题。
func (*Model) SetFilterState ¶
func (m *Model) SetFilterState(state FilterState)
SetFilterState 允许手动设置过滤状态。
func (*Model) SetFilterText ¶
SetFilterText 显式设置过滤文本而不依赖用户输入。 它还将 filterState 设置为合理的默认值 FilterApplied，但这 可以通过 SetFilterState 更改。
func (*Model) SetFilteringEnabled ¶
SetFilteringEnabled 启用或禁用过滤。注意这与 ShowFilter 不同， ShowFilter 仅仅隐藏或显示输入视图。
func (*Model) SetShowFilter ¶
SetShowFilter 显示或隐藏过滤栏。注意这不会禁用过滤， 它只是隐藏内置的过滤视图。这允许您使用 FilterInput 以不同的方式 渲染过滤 UI，而无需从头重新实现过滤。
要完全禁用过滤，请使用 EnableFiltering。
func (*Model) SetShowPagination ¶
SetShowPagination 隐藏或显示分页器。注意分页仍然会活动， 只是不会显示。
func (*Model) SetShowStatusBar ¶
SetShowStatusBar 显示或隐藏显示列表元数据的视图，例如项目计数。
func (*Model) SetSpinner ¶
SetSpinner 允许设置 spinner 样式。
func (*Model) SetStatusBarItemName ¶
SetStatusBarItemName 定义项目标识符的替换。默认为 item/items。
func (Model) SettingFilter ¶
SettingFilter 返回用户当前是否正在编辑过滤值。 这纯粹是以下内容的便捷方法：
m.FilterState() == Filtering
包含在这里是因为在实现此组件时这是一个常见的检查项。
func (Model) ShowFilter ¶
ShowFilter 返回过滤器是否设置为渲染。注意这与 FilteringEnabled 是分开的， 因此过滤可以被隐藏但仍然可以调用。这允许您以不同的方式渲染过滤， 而无需从头重新实现它。
func (*Model) StartSpinner ¶
StartSpinner 启动 spinner。注意这也返回一个命令。
func (Model) StatusBarItemName ¶
StatusBarItemName 返回单数和复数状态栏项目名称。
func (*Model) ToggleSpinner ¶
ToggleSpinner 切换 spinner。注意这也返回一个命令。
type Rank ¶
Rank 定义给定项目的排名。
func DefaultFilter ¶
DefaultFilter 使用 sahilm/fuzzy 来过滤列表。这是默认设置。
func UnsortedFilter ¶
UnsortedFilter 使用 sahilm/fuzzy 来过滤列表。它不对结果进行排序。
type Styles ¶
type Styles struct {
// TitleBar 标题栏样式
TitleBar lipgloss.Style
// Title 标题样式
Title lipgloss.Style
// Spinner 加载动画样式
Spinner lipgloss.Style
// FilterPrompt 过滤提示符样式
FilterPrompt lipgloss.Style
// FilterCursor 过滤光标样式
FilterCursor lipgloss.Style
// DefaultFilterCharacterMatch 过滤器中匹配字符的默认样式。可由委托覆盖。
DefaultFilterCharacterMatch lipgloss.Style
// StatusBar 状态栏样式
StatusBar lipgloss.Style
// StatusEmpty 空状态样式
StatusEmpty lipgloss.Style
// StatusBarActiveFilter 激活过滤器时的状态栏样式
StatusBarActiveFilter lipgloss.Style
// StatusBarFilterCount 过滤器计数样式
StatusBarFilterCount lipgloss.Style
// NoItems 无项目时的样式
NoItems lipgloss.Style
// PaginationStyle 分页样式
PaginationStyle lipgloss.Style
// HelpStyle 帮助样式
HelpStyle lipgloss.Style
// Styled characters 样式化字符
// ActivePaginationDot 激活的分页点样式
ActivePaginationDot lipgloss.Style
// InactivePaginationDot 未激活的分页点样式
InactivePaginationDot lipgloss.Style
// ArabicPagination 阿拉伯数字分页样式
ArabicPagination lipgloss.Style
// DividerDot 分隔点样式
DividerDot lipgloss.Style
}
Styles 包含此列表组件的样式定义。默认情况下，这些值由 DefaultStyles 生成。
Source Files