Keel v0.5.1 中文 GitHub

List

Live example: a real Keel application compiled to WebAssembly. Interact with it here. The initial download is about 10 MB.Open full screen
Example sourceGo · Copyable

This is the complete source for the gallery example above.examples/components/list.go

Reuse the component construction and Render methods in a scaffolded project. The example’s registerSection and shared helpers are provided by the component gallery.

package main

import (
	"strconv"

	"github.com/dyike/keel/ui/core"
	"github.com/dyike/keel/ui/el"
	"github.com/dyike/keel/ui/kit"
	"github.com/dyike/keel/ui/theme"
)

func init() {
	registerSection("list", "data", func() core.Widget {
		var items []string
		for i := range 300 {
			items = append(items, demoText("Contact ", "联系人 ")+strconv.Itoa(i+1))
		}
		msg := demoText("Ctrl/Cmd selects multiple items; Shift selects a range. Drag to reorder. Gray items are disabled.", "Ctrl/Cmd 多选,Shift 连选;拖动条目重排,灰色条目不可操作")
		var l *kit.ListView
		l = kit.List(items...).Searchable(true).MultiSelect().Reorderable(func(from, to int) {
			msg = demoText("Moved to position ", "已移动到第 ") + strconv.Itoa(to+1) + demoText(" items", " 项")
		}).Height(240).OnActivate(func(i int) { msg = demoText("Open ", "打开 ") + l.Items()[i] })
		entries := l.Entries()
		for i := range entries {
			entries[i].Disabled = i%10 == 4
			entries[i].Group = demoText("Group ", "分组 ") + strconv.Itoa(i/50+1)
			entries[i].Icon = kit.IconUser
			entries[i].Keywords = []string{"contact"}
		}
		l.SetEntries(entries...)
		l.RowHeight(36).RenderItem(func(cx *el.Context, item kit.ListItemContext) el.Element {
			return el.Div().Row().Grow().Items(el.Center).Gap(8).Child(kit.Icon(item.Item.Icon).Render(cx), el.Text(item.Item.Label).MaxLines(1).Grow(), kit.Button(demoText("Details", "详情"), func() { msg = demoText("Details: ", "详情:") + item.Item.Label }).Size(24).Variant(kit.ButtonGhost).Render(cx))
		})
		l.OnSelectionChange(func(values []int) {
			msg = demoText("Selected ", "选中 ") + strconv.Itoa(len(values)) + demoText(" items", " 项")
		})
		inserted := 0
		return el.Embed(el.ViewFunc(func(cx *el.Context) el.Element {
			return el.Div().P(24).Gap(8).W(el.Dp(320)).MaxW(el.Full).Child(kit.Button(demoText("Prepend item", "在开头插入条目"), func() {
				inserted++
				entry := kit.ListItem{ID: "inserted-" + strconv.Itoa(inserted), Label: demoText("New contact ", "新联系人 ") + strconv.Itoa(inserted)}
				l.SetEntries(append([]kit.ListItem{entry}, l.Entries()...)...)
			}).Render(cx), l.Render(cx), el.Text(msg).TextColor(theme.Muted))
		}))
	})
}

The default single-select virtual list supports multi-selection, single-item disabling, stable ID, and drag-and-drop rearrangement.

contacts := kit.List(names...).Height(240).OnChange(show).OnActivate(open)
  • Click or ↑ ↓ Home End PageUp PageDown to select, double-click or press Enter to activate.
  • The focus is on the entire list, not on a certain row: the row will be recycled with scrolling, and the focus cannot stay on a certain row.
  • Value() returns the serial number of the selected item (-1 if none), SetValue does not trigger the callback; SetItems replaces the content, and clears it when the original selection does not exist; Items(), SetDisabled.
  • Height(dp) or Fill() sets the height. Plain() removes the border and background and is used in panels and sidebars that already have borders; the outline is still displayed when focused.

Agent: container role listbox, each item is option, selected means selected.

Verify: go run ./examples/components -section list, add -theme dark to check the dark theme.

Constructs and SetItems copies the option slice, Items() returns a copy. Update data via SetItems; modifying the slice passed in or returned does not affect the list. The selection is still represented by the index. After replacement, the index will be cleared when it goes out of bounds, and the user callback will not be triggered.

SetEntries(...ListItem) receives {ID, Label, Disabled}, copies the data and keeps the selection by ID; empty ID, duplicate ID panics before modification. Entries() returns a copy. SetItems still uses index identity, use SetEntries when you need to maintain selections across insertions, deletions, and rearrangements. SetItemDisabled(index, on) disables a single item. The mouse, arrow keys, range selection and select all will skip it, and pressing Enter will not activate it. Program selection allows disabled items to be retained.

MultiSelect() Enables Ctrl/Cmd plus selection, Shift range selection, and Ctrl/Cmd+A selection all. SelectedValues() returns a copy of the index in display order, SetSelectedValues is assigned programmatically, OnSelectionChange receives a copy of the selection; Value() is the active item, and SetValue is replaced with a single selection. Programmatic assignment does not trigger user callbacks.

Reorderable(func(from, to int)) enables drag rearrangement. The internal order will be modified and notified after releasing the button. Cancel dragging without modifying the order. Move(from, to) provides program rearrangement without triggering callbacks. Both methods retain the selection by ID, and the callback index refers to the position before and after the move respectively; the current drag is oriented to the target within the viewport and does not automatically scroll to distant items.

Group, search and customize content

ListItem can set Group, Keywords and Icon. Adjacent items with the same Group form a group. The group title occupies one line but cannot be selected; the group header is not displayed when there are no search results in the group. RenderGroupHeader(func(cx, group) el.Element) replaces the header content and RenderGroupFooter inserts a line at the end of each non-empty group. All virtual rows (including group headers/footers) use the same row height. RowHeight(dp) can be set to 20–512dp, and the default is 32dp.

Searchable(true) displays the search box, which is not displayed by default; SetQuery / Query controls the query. The search is case-insensitive and matches Label and Keywords, but not group titles. Keywords are copied during SetEntries, and the keywords returned by Entries are also copies. OnSearch receives query changes and is notified when the program calls SetQuery. The application can obtain remote data accordingly; local filtering is always in effect.

Searches are not renumbered: Value, select/activate callbacks, and Index in custom row contexts are all source data indexes for SetEntries. Hidden selections are retained. Keyboard navigation, range selection, and select all only work on visible available items. The hidden current item cannot be activated by Enter. Drag to position the target according to the visible layout including the group header/footer, and then update the source order; the items retain the original Group, and changes in adjacent relationships may cause groups with the same name to appear in segments.

list.Searchable(true).RenderItem(func(cx *el.Context, row kit.ListItemContext) el.Element {
    return el.Div().Row().Grow().Child(
        el.Text(row.Item.Label).Grow(),
        kit.Button("Details", func() { open(row.Item.ID) }).Size(24).Render(cx),
    )
})

ListItemContext with entry copy, source Index, Selected and Disabled status. RenderItem returns nil to use the default icon/label. Sub-buttons with custom content handle events independently, without selecting/activating list rows; the rest of the row's background still supports original selection and dragging. Stateful instances of custom views should be saved by the application with a stable ID, and the content height should fit into the uniform row height.

Load more

OnLoadMore(fn) works with SetHasMore(true) to request the next page within two lines from the bottom. The component is set to loading first and then fn is called. The same data will not be automatically requested repeatedly. The results are delivered through SetEntries in the UI thread or core.Update, then SetLoading(false); the last page is set by SetHasMore(false). Appending data will not automatically pull the viewport back to the old selection.

If failed, use SetLoadError(message) to stop the automatic request and display the retry button; click it and then call the loading function. When disabled, no requests are initiated and issued network tasks are canceled by the application. Expiration verification of remote search or loaded results is also managed by the application, and the query/request identifier should be checked before delivery; the component does not provide an asynchronous token API. SetQuery and SetEntries reset the current round of request flags, and the filtered content can continue to load if it is less than one screen.

Status content

files := kit.List().Searchable(true).
    InitialContent(kit.Label("Enter a file name to search")).
    EmptyContent(kit.Label("This folder is empty")).
    NoMatchesContent(kit.Label("No matching files")).
    LoadingContent(kit.Skeleton()).
    ErrorContent(func(msg string, retry func()) el.View { /* Provide custom error and retry UI */ })
  • EmptyContent: Displayed when the list has no data and no search terms.
  • NoMatchesContent: Displayed when there is a search term but no results.
  • InitialContent: When the searchable list has not yet entered a search term, it will be displayed instead of the entire list, and the results will be displayed after input.
  • LoadingContent, ErrorContent: replace the circle when loading more and the text when an error occurs and add "retry"; retry reinitiates loading.
  • Pass nil to restore default. The status content is displayed below the list, in the same position as the default text.

Example go run ./examples/components -section list demonstrates search, grouping, icons, and inline operations. The automatic test covers the original selection/drag regression, as well as search source index, group footer, range skip hidden items, sub-button isolation, load deduplication/failure retry/disable; real device vision and drag acceptance are not done.