VariableList
Example sourceGo · Copyable
This is the complete source for the gallery example above.examples/components/variable_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 (
"fmt"
"strconv"
"strings"
"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("variable_list", "data", func() core.Widget {
keys := make([]string, 100000)
for i := range keys {
keys[i] = strconv.Itoa(i + 1)
}
older := 0
horizontal := false
expanded := map[string]bool{}
var list *kit.VariableListView
list = kit.VariableList(keys, 72, func(cx *el.Context, i int) el.Element {
k := keys[i]
number, _ := strconv.Atoi(k)
text := strings.Repeat(demoText("Mixed text wraps to fit the available width.", "中文 mixed text 会随宽度自动换行。"), 1+number%3)
if expanded[k] {
text += strings.Repeat(demoText(" Expanded content increases the row height.", " 展开后的内容继续增加当前行高度。"), 5)
}
row := el.Div().Py(12).Px(16).Gap(6).Bg(theme.Surface).Border(1, theme.Outline).Child(
el.Text(demoText("Message ", "消息 ")+k).Bold(), el.Text(text),
kit.Button(demoText("Expand / collapse", "展开 / 收起"), func() { expanded[k] = !expanded[k] }).Variant(kit.ButtonGhost).Render(cx))
if horizontal {
row.W(el.Dp(float32(180 + number%3*60)))
}
return row
}).Height(460)
return el.Root(el.ViewFunc(func(cx *el.Context) el.Element {
return el.Div().ScrollY().P(24).Gap(12).Child(
el.Text(demoText("Variable-height virtual list", "可变高度虚拟列表")).Bold().TextSize(24),
el.Text(fmt.Sprintf(demoText("%d items; resize the window, expand a row, or prepend items to check the reading position.", "%d 条;调整窗口宽度、展开某行或在头部插入,检查阅读位置。"), len(keys))).TextColor(theme.Muted),
el.Div().Row().Wrap().Gap(8).Child(
kit.Button(demoText("Toggle orientation", "切换横纵方向"), func() { horizontal = !horizontal; list.Horizontal(horizontal) }).Render(cx),
kit.Button(demoText("Go to #50000", "定位消息 50000"), func() { list.ScrollToKey(cx, "50000") }).Render(cx),
kit.Button(demoText("Prepend 10 items", "头部插入 10 条"), func() {
var add []string
for range 10 {
older++
add = append(add, fmt.Sprintf(demoText("History-%d", "历史-%d"), older))
}
keys = append(add, keys...)
list.SetKeys(keys)
}).Variant(kit.ButtonSecondary).Render(cx)),
list.Render(cx))
}))
})
}
list := kit.VariableList(messageIDs, 72, func(cx *el.Context, i int) el.Element {
return el.Text(messages[i].Body) // Automatic line wrapping, natural height
}).Height(400)
The second parameter of VariableList is the estimated height (dp) of the row that has not yet been measured. Each frame only builds rows near the visible area and one screen above and below. The actual height is cached after layout, and the row position is queried using prefixes and indexes; normal scrolling does not scan all data.
- key must be non-empty and unique.
SetKeys(ids)copies the new sequence, retaining the size cache of still existing keys; duplicate or empty keys will panic before modification. - When the header is inserted or the height of the upper row changes, the screen position of the first visible key is maintained; when the row is deleted, the row near the original index is selected. Window width or zoom changes automatically clear the size cache and remeasure.
- Height changes of visible rows are automatically detected;
Invalidate(keys...)is called after modifying off-screen data or fonts. If the key is not passed, all size caches will be invalidated. ScrollTo(cx, i)is positioned according to the zero-based index of the current list;ScrollToKey(cx, key)is positioned according to a stable key, which is suitable for message jump after insertion, deletion or rearrangement. Non-existing keys do not change the current positioning request. Both only scroll until the target row is visible, and continue to correct after initially displaying and measuring the row height.ScrollToAlign(cx, i, align)/ScrollToKeyAlign(cx, key, align)Put the target row at the top, center or bottom (kit.ScrollStart/ScrollCenter/ScrollEnd). The unmeasured rows are first positioned according to the estimated height and automatically corrected after measurement.Height,Fill,Count,ID, andSetDisabledare consistent with equal height list usage.- Stable keys maintain the identity of elements within the build scope; business state such as input values that have long left the build scope should still be preserved in the application model.
- Unvisited rows use an estimated height, so the scrollbar length adjusts to the measurement. In scenarios where table row heights are known, continue to use equal height lists.
Verification: go run ./examples/components -section variable_list. Click "Locate Message 50000", then continuously perform "Header Insert 10" and reposition, you should always see "Message 50000". Also checks for expanded line content and narrow window wrapping.
Horizontal(true) Enables horizontally widening virtual lists; constructed with the estimate parameter as the unmeasured width. Width(dp) sets the viewport width (horizontal default is 320dp), Height(dp) sets the height; horizontal Fill() fills the main axis in the Row parent layout. Item renderers can return different natural or explicit widths.
Switching the axis retains the first visible stable key, resets the offset within the project to zero, and clears the old axis measurements; row heights are not treated as column widths. The pending ScrollTo/ScrollToKey is retained and will be modified after layout. ScrollToEnd(cx) locates the last item. Horizontal insertion, deletion, reordering, and size changes also maintain the reading anchor; cross-axis height and scaling changes in horizontal mode invalidate cache. Visible items are re-measured every frame, and Invalidate is still called when modifying off-screen content.
strip := kit.VariableList(ids, 160, func(cx *el.Context, i int) el.Element {
return el.Div().W(el.Dp(widths[i])).Child(el.Text(labels[i]))
}).Horizontal(true).Width(640).Height(100)
The same list is virtualized along only one axis. Keel uses actual measurements of visible items and estimates of unvisited items, and provides all sizes upstream through the caller; the length of the scroll bar may be adjusted with the measurement, and the positioning adopts the minimum exposure strategy.