Sidebar
示例代码Go · 可复制
这是上方组件库展示案例的完整源码。examples/components/sidebar.go
在脚手架项目中复用组件构造和 Render 写法;示例的 registerSection 与共享辅助函数由组件库提供。
package main
import (
"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("sidebar", "navigation", func() core.Widget {
nav := kit.Sidebar().
Section(demoText("Workspace", "工作台"), kit.SidebarItem{ID: "inbox", Label: demoText("Inbox", "收件箱"), Icon: kit.IconInbox, Badge: 12},
kit.SidebarItem{ID: "orders", Label: demoText("Orders", "订单"), Icon: kit.IconReceipt, Children: []kit.SidebarItem{
{ID: "pending", Label: demoText("Pending orders", "待处理订单"), Icon: kit.IconClock, Badge: 6},
{ID: "completed", Label: demoText("Completed orders", "已完成订单"), Icon: kit.IconCheck},
{ID: "archived", Label: demoText("Archive order", "归档订单"), Icon: kit.IconArchive, Disabled: true},
}},
kit.SidebarItem{ID: "calendar", Label: demoText("Schedule", "日程"), Icon: kit.IconCalendar}).
Section(demoText("Team", "团队"), kit.SidebarItem{ID: "members", Label: demoText("Members", "成员"), Icon: kit.IconUser},
kit.SidebarItem{ID: "saved", Label: demoText("Starred", "已收藏"), Icon: kit.IconStarOutline}).
Section("", kit.SidebarItem{ID: "settings", Label: demoText("Preferences", "偏好设置"), Icon: kit.IconSettings})
status, right := "", false
nav.SetSuffix("inbox", kit.Button(demoText("Refresh", "刷新"), func() { status = demoText("Inbox refreshed", "已刷新收件箱") }).Variant(kit.ButtonGhost).Size(24))
nav.SetContextMenu("inbox", kit.Menu().
Item(demoText("Mark all read", "标记全部已读"), "", func() {
nav.SetBadge("inbox", 0)
status = demoText("All inbox messages read", "收件箱已全部读完")
}).
Separator().Item(demoText("Open inbox", "打开收件箱"), "", func() { nav.SetValue("inbox") }))
nav.SetValue("inbox")
nav.SetExpanded("orders", true)
nav.Header(el.ViewFunc(func(cx *el.Context) el.Element {
row := el.Div().Row().Items(el.Center).Gap(10).Py(8).Child(kit.Avatar("Keel").Size(28).Render(cx))
if !nav.Collapsed() {
row.Child(el.Text(demoText("Keel workspace", "Keel 工作台")).TextSize(15).Bold())
}
return row
}))
nav.Footer(el.ViewFunc(func(cx *el.Context) el.Element {
row := el.Div().Row().Items(el.Center).Gap(10).Py(8).Child(kit.Avatar("Yike").Size(28).Render(cx))
if !nav.Collapsed() {
row.Child(el.Div().Gap(2).Child(el.Text("Yike").TextSize(13), el.Text(demoText("Personal workspace", "个人工作区")).TextSize(11).TextColor(theme.Muted)))
}
return row
}))
initialized, wasNarrow := false, false
return el.Root(el.ViewFunc(func(cx *el.Context) el.Element {
width, height := cx.ViewportSize()
narrow := width < 600
if !initialized || narrow != wasNarrow {
nav.SetCollapsed(narrow)
initialized, wasNarrow = true, narrow
}
nav.Height(height)
titles := map[string]string{"pending": demoText("Pending orders", "待处理订单"), "completed": demoText("Completed orders", "已完成订单"), "archived": demoText("Archive order", "归档订单"), "inbox": demoText("Inbox", "收件箱"), "orders": demoText("Orders", "订单"), "calendar": demoText("Schedule", "日程"), "members": demoText("Team members", "团队成员"), "saved": demoText("Starred", "已收藏"), "settings": demoText("Preferences", "偏好设置")}
body := el.Div().Grow().W(el.Dp(0)).ScrollY().Bg(theme.Surface).P(28).Gap(12).Items(el.Stretch)
body.Child(el.Text(demoText("Workspace / ", "工作台 / ")+titles[nav.Value()]).TextSize(12).TextColor(theme.Muted),
el.Text(titles[nav.Value()]).TextSize(24).Bold(),
el.Text(demoText("View team activity and tasks in one place.", "集中查看团队动态与待办事项。")).TextSize(13).TextColor(theme.Muted),
el.Div().H(el.Dp(1)).My(12).Bg(theme.Border))
if nav.Value() == "inbox" {
for _, item := range []struct{ title, detail string }{
{demoText("Order awaiting confirmation", "订单待确认"), demoText("East China customer · Just now", "华东客户 · 刚刚")}, {demoText("This week's deliveries", "本周交付安排"), demoText("Project team · 20 minutes ago", "项目组 · 20 分钟前")}, {demoText("Design review updated", "设计评审已更新"), demoText("Product team · 1 hour ago", "产品团队 · 1 小时前")},
} {
body.Child(el.Div().Py(12).Gap(6).Child(el.Text(item.title).TextSize(14), el.Text(item.detail).TextSize(12).TextColor(theme.Muted)))
}
} else {
body.Child(kit.Empty(demoText("No pending items", "暂无待处理事项")).Render(cx))
}
body.Child(kit.Button(demoText("Toggle sidebar position", "切换侧栏位置"), func() { right = !right }).Render(cx), el.Text(status))
root := el.Div().Row().Items(el.Stretch)
if right {
nav.Side(el.Right)
return root.Child(body, nav.Render(cx))
}
nav.Side(el.Left)
return root.Child(nav.Render(cx), body)
}))
})
}
应用的导航侧栏:分组、选中项、角标,可以收起成只显示图标。
nav := kit.Sidebar().
Section("工作台", kit.SidebarItem{ID: "inbox", Label: "收件箱", Icon: kit.IconInbox, Badge: 12}).
Section("", kit.SidebarItem{ID: "settings", Label: "设置", Icon: kit.IconSettings}).
OnChange(navigate)
- 鼠标点击只显示选中背景;Tab、方向键导航显示焦点框。滚动条占用右侧独立留白,不覆盖行背景、角标或点击区域。
- 36dp 导航行、16dp 图标、14sp 文案;选中项使用中性底色和强调图标,计数为低对比数字,底部展开状态显示折叠文案。
- 有标题的分组显示标题;没有标题的分组之间用分隔线隔开。
- 每个可用项都能用 Tab 聚焦,↑ ↓ / Home / End / PageUp / PageDown 移动并滚动到目标,回车或空格激活。
Disabled或SetItemDisabled(id, bool)禁用单项;SetDisabled禁用整个侧栏及插槽操作。 SidebarItem.Children定义嵌套导航。分支整行点击展开/收起,不触发导航回调;→ 展开,← 收起或移到父项。SetExpanded/Expanded管理展开状态,SetValue会展开目标祖先并滚动到选中项。Header(el.View)/Footer(el.View)位于导航滚动区之外,适合工作区切换和账户信息。插槽可在 Render 中读取Collapsed(),自行切换图标版内容。Height(dp)显式设置侧栏高度,导航内容溢出时只滚动中间区域;默认按内容定高,上限为窗口高度。嵌入应用外壳时可传cx.ViewportSize()返回的高度。- 底部按钮可以收起侧栏,收起后宽 56dp:只显示图标,名称改由 Tooltip 显示,角标变成圆点。
Icon可以不设(IconNone):展开时只显示文字,收起时显示名称首字。SidebarItem.IconView接受仅用于显示的自定义图标,在同一个 16dp 插槽内覆盖Icon;收起后仍显示,颜色由应用控制。分支展开箭头紧跟名称,位于角标和独立尾部内容之前。Filter(query)只显示名称包含 query 的项(不区分大小写),以及通向它们的父项,父项会临时展开;没有匹配项的分组连同标题一起隐藏。传空字符串恢复全部。选中项被过滤掉时仍保持选中。组件库应用go run ./examples/components用它做搜索。Side(el.Right)将分隔线放到左边,并调整折叠箭头与收起状态的提示方向;默认el.Left。应用仍需把侧栏放在主内容右边,组件不改变父布局顺序。BorderWidth(dp)调整分隔线,0 隐藏。SidebarItem.Tag在名称后、展开箭头前放置仅展示的内容,通常是Tag。名称截断时它保持尺寸;选中行加粗时它保持常规字重;折叠时隐藏。SectionAction(title, view, items...)在分组标题末尾放置内容(如添加按钮);这样的分组为空时仍显示标题(筛选时隐藏)。SectionTitleWeight(font.Weight)设置分组标题字重,默认常规;SectionTitleColor(color)设置分组标题颜色,默认theme.Muted(在 Render 中设置,如theme.Text,即可跟随主题切换)。Resizable(min, max)把分隔线变成separator:拖动,或聚焦后用方向键(每次 16dp,Home / End 到达上下限)在 min 与 max dp 之间调整展开宽度。调整后的宽度与Width一样是显式宽度,会关闭AutoWidth。OnResize(fn)通知新宽度,CurrentWidth()读取当前宽度。收起后的图标栏不可调整。Collapsible(false)隐藏内置折叠按钮;程序仍可调用SetCollapsed。SidebarItem.Suffix/SetSuffix(id, view)添加独立尾部内容,可以放按钮或开关;点击尾部不选择或展开导航项。收起时隐藏尾部内容,展开时最大宽度为侧栏配置宽度的一半,高度应适配 36dp 行。Badge 仍可同时显示。SidebarItem.ContextMenu/SetContextMenu(id, menu)为条目添加右键菜单,支持 Menu 的子菜单、快捷键提示、链接及自定义内容。一个 Menu 实例只属于一个条目,其 Trigger 不使用;菜单外观与位置仍由 Menu 配置。隐藏、禁用或替换条目菜单会关闭旧菜单。右键不改变选中项。Value()/SetValue(id)、SetBadge(id, n)、Collapsed()/SetCollapsed、Width(dp)(默认 220)。
SidebarItem.SuffixOnHover 让尾部内容在整行悬停、行内有键盘焦点或上下文菜单打开时显示。隐藏时保留布局占位,且不能触发操作。
选项结构会递归复制;IconView、Suffix 和 ContextMenu 保留传入实例。整个 Sidebar 的 ID 必须非空且唯一;新增 Section 包含空值或重复 ID 时整组不加入。父项禁用不隐式禁用子项。
Sidebar 跳过滚动视口外的行绘制,但每帧仍会构建和布局展开的条目,尚不是完整的虚拟列表。菜单清理通过已列出的 ID 集合一次遍历整份数据,行内 hover 和焦点查询复用 el 的本轮渲染索引。回归测试覆盖 1×/2× 下的 1000 行列表、屏外绘制、键盘定位与选择,以及收起父项后的菜单关闭。运行 go test ./ui/kit -run '^$' -bench BenchmarkSidebarScroll -benchmem,可测量带逐项菜单和 hover 按钮的平铺列表及已收起的项目树。
Agent:容器角色 navigation;叶项是 link,分支是带展开布尔值的 button,selected 表示当前页;收起按钮名为"收起侧栏""展开侧栏";开启 Resizable 后,分隔线是名为"调整大小"的 separator,值为当前宽度。
验证:go run ./examples/components -section sidebar,加 -theme dark 检查深色。
大字体会自动增加导航行和分组标题高度。默认侧栏宽度也随字体缩放增加,最多 420dp,并为正文预留 240dp;无法容纳原始宽度时显示图标栏,窗口变宽后恢复。Width(dp) 保持显式宽度;Width(dp).AutoWidth(true) 可重新启用自适应。自动宽度调整在字体缩放大于 1 时生效。被截断的标签在悬停或聚焦时显示完整提示,Escape 可关闭。自定义页头、页脚仍需应用自行适配。
SectionTitleSize(sp) 设置分类标题字号,零恢复 theme.TextSm,非法值忽略。标题行高及滚动定位会随字号调整。