VariableList
示例代码Go · 可复制
这是上方组件库展示案例的完整源码。examples/components/variable_list.go
在脚手架项目中复用组件构造和 Render 写法;示例的 registerSection 与共享辅助函数由组件库提供。
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) // 自动换行,自然高度
}).Height(400)
VariableList 的第二个参数是尚未测量行的估计高度(dp)。每帧只构建可视区及上下各一屏附近的行,布局后缓存实际高度,用前缀和索引查询行位置;普通滚动不扫描全部数据。
- key 必须非空且唯一。
SetKeys(ids)复制新的顺序,保留仍存在的 key 的尺寸缓存;重复或空 key 会在修改前 panic。 - 头部插入或上方行高度变化时,保持首个可见 key 的屏幕位置;该行被删除则选择原索引附近的行。窗口宽度或缩放变化自动清空尺寸缓存并重新测量。
- 可见行的高度变化自动检测;修改屏幕外的数据或字体后调用
Invalidate(keys...),不传 key 则使全部尺寸缓存失效。 ScrollTo(cx, i)按当前列表的零基索引定位;ScrollToKey(cx, key)按稳定 key 定位,适用于插入、删除或重排后的消息跳转,不存在的 key 不改变当前定位请求。两者只滚动到目标行可见,初次显示和测量改变行高后继续校正。ScrollToAlign(cx, i, align)/ScrollToKeyAlign(cx, key, align)把目标行放到顶部、居中或底部(kit.ScrollStart/ScrollCenter/ScrollEnd),未测量的行先按估算高度定位,测量后自动校正。Height、Fill、Count、ID和SetDisabled与等高列表用法一致。- 稳定 key 保持构建范围内的元素身份;长期离开构建范围的输入值等业务状态仍应保存在应用模型中。
- 未访问行使用估计高度,因此滚动条长度会随测量调整。表格等行高已知场景继续使用等高列表。
验证:go run ./examples/components -section variable_list。点击“定位消息 50000”,再连续执行“头部插入 10 条”并重新定位,应始终看到“消息 50000”。同时检查展开行内容和窄窗口换行。
Horizontal(true) 启用横向变宽虚拟列表;构造时 estimate 参数作为未测量宽度。Width(dp) 设置视口宽度(横向默认 320dp),Height(dp) 设置高度;横向 Fill() 在 Row 父布局中填满主轴。项目渲染器可以返回不同自然宽度或显式宽度。
切换轴保留首个可见稳定 key,把项目内偏移归零,并清空旧轴测量;不会把行高当成列宽。待处理的 ScrollTo/ScrollToKey 保留,布局后继续修正。ScrollToEnd(cx) 定位末项。横向插入、删除、重排和尺寸改变同样保持阅读锚点;水平模式下交叉轴高度和缩放变化使缓存失效。可见项目每帧重新测量,修改离屏内容仍调用 Invalidate。
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)
同一列表只沿一个轴虚拟化。Keel 使用可见项目实测与未访问项目估算,上游通过调用方提供全部尺寸;滚动条长度可能随测量调整,定位采用最小露出策略。