Keel v0.5.1 English GitHub

Sidebar

在线示例:这是真实的 Keel 程序编译成 WebAssembly,可以直接操作。首次加载约 10 MB。全屏打开
示例代码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,非法值忽略。标题行高及滚动定位会随字号调整。