Dock
示例代码Go · 可复制
这是上方组件库展示案例的完整源码。examples/components/dock.go
在脚手架项目中复用组件构造和 Render 写法;示例的 registerSection 与共享辅助函数由组件库提供。
package main
import (
"encoding/json"
"github.com/dyike/keel/ui/core"
"github.com/dyike/keel/ui/el"
"github.com/dyike/keel/ui/kit"
"github.com/dyike/keel/ui/theme"
"github.com/dyike/keel/ui/window"
)
func init() {
registerSection("dock", "navigation", func() core.Widget {
txt := func(s string) el.View {
return el.ViewFunc(func(*el.Context) el.Element { return el.Div().ScrollY().P(12).Child(el.Text(s).TextSize(13)) })
}
code := func(s string) el.View {
return el.ViewFunc(func(*el.Context) el.Element {
return el.Div().Grow().ScrollY().P(16).Bg(theme.Surface).Child(el.Text(s).Mono().TextSize(13))
})
}
saved := demoText("Move, close, split, or resize panels to see the saved layout JSON here", "移动、关闭、拆分或调整面板后,这里显示保存的布局 JSON")
files := kit.Tree(&kit.TreeNode{ID: "ui", Label: "ui", Children: []*kit.TreeNode{{ID: "kit", Label: "kit"}, {ID: "el", Label: "el"}}}).Fill().Plain()
searchFactory := func(state kit.DockPanelState) (kit.DockPanel, error) {
input := kit.Input("").Placeholder(demoText("Search in file", "在文件中搜索"))
var query string
if len(state.State) > 0 {
if err := json.Unmarshal(state.State, &query); err != nil {
return kit.DockPanel{}, err
}
}
input.SetValue(query)
return kit.DockPanel{ID: state.ID, Kind: "search", Title: state.Title, View: input,
SaveState: func() (json.RawMessage, error) { return json.Marshal(input.Value()) }}, nil
}
search, _ := searchFactory(kit.DockPanelState{ID: "search", Title: demoText("Search", "搜索")})
var snapshot []byte
status := demoText("Enter a search query, then save, change, and restore it", "先输入搜索词,再保存、修改和恢复")
var d *kit.DockView
// The center view shows while no document is open.
d = kit.Dock(el.ViewFunc(func(*el.Context) el.Element {
return el.Div().Grow().P(24).Gap(8).Bg(theme.Surface).Child(el.Text(demoText("No open documents", "没有打开的文档")).Bold(),
el.Text(demoText("Drag a panel here, or choose “Move to center” in its menu to open it as a document", "把面板拖到这里,或用面板菜单的“移到中间”打开为文档")).TextSize(12).TextColor(theme.Muted))
})).
Panel(kit.DockPanel{ID: "files", Title: demoText("Files", "文件"), Icon: kit.IconFolder, View: files, NoClose: true,
Toolbar: kit.Button("", func() { status = demoText("File list refreshed", "已刷新文件列表") }).Name(demoText("Refresh files", "刷新文件")).Icon(kit.IconRetry).Variant(kit.ButtonGhost).Size(24),
Menu: func(m *kit.MenuView) {
m.Item(demoText("Collapse all", "全部折叠"), "", func() { status = demoText("All directories collapsed", "已折叠全部目录") })
}}, kit.DockLeft).
Panel(search, kit.DockLeft).
Panel(kit.DockPanel{ID: "main.go", Title: "main.go", View: code("package main\n\nfunc main() {\n run()\n}")}, kit.DockCenter).
Panel(kit.DockPanel{ID: "app.go", Title: "app.go", View: code("package main\n\nfunc run() {}")}, kit.DockCenter).
Panel(kit.DockPanel{ID: "outline", Title: demoText("Outline", "大纲"), View: txt("func main()\nfunc run()")}, kit.DockRight).
Panel(kit.DockPanel{ID: "terminal", Title: demoText("Terminal", "终端"), NoPadding: true, View: txt("$ go test ./...\nok"),
Tab: func(selected bool) el.View {
return el.ViewFunc(func(*el.Context) el.Element {
return el.Div().Row().Items(el.Center).Gap(6).Child(el.Div().Size(el.Dp(6)).Rounded(3).Bg(theme.Success), el.Text(demoText("Terminal", "终端")))
})
}}, kit.DockBottom).
Panel(kit.DockPanel{ID: "layout", Title: demoText("Layout", "布局"), View: el.ViewFunc(func(*el.Context) el.Element {
return el.Div().ScrollY().P(12).Child(el.Text(saved).TextSize(12).TextColor(theme.Muted))
})}, kit.DockBottom).
OnLayoutChange(func(l kit.DockLayout) {
b, _ := json.Marshal(l)
saved = string(b)
}).
// "Open in new window", or a tab dragged out of the dock, opens the
// panel in a window; closing that window puts it back.
OnDetach(func(p kit.DockPanel, reattach func()) {
window.Open(window.Options{Title: p.Title, Width: 520, Height: 400, Content: el.Root(p.View), OnClose: reattach})
})
if err := d.RegisterPanel("search", searchFactory); err != nil {
panic(err)
}
d.Split("search", "files", kit.DockPlacementBottom)
d.Split("app.go", "main.go", kit.DockPlacementRight)
// Side panels narrow enough that the documents stay the widest region
// in the gallery's 680dp window.
l := d.Layout()
l.LeftSize, l.RightSize, l.BottomSize = 180, 160, 140
d.SetLayout(l)
customSkin := &kit.DockSkin{
Header: func(e *el.DivEl) { e.Bg(theme.Bg).Py(theme.SpaceSm) },
Body: func(e *el.DivEl) { e.P(theme.SpaceLg) },
Tab: func(e *el.DivEl, selected bool) {
if selected {
e.Bg(theme.Primary).TextColor(theme.PrimaryText)
}
},
Separator: func(e *el.DivEl) { e.Bg(theme.Primary) },
}
styled := false
save := kit.Button(demoText("Save workspace", "保存工作区"), func() {
state, err := d.Snapshot()
if err != nil {
status = err.Error()
return
}
data, err := json.Marshal(state)
if err != nil {
status = err.Error()
return
}
snapshot = data
status = demoText("Layout and search query saved", "已保存布局和搜索词")
})
restore := kit.Button(demoText("Restore workspace", "恢复工作区"), func() {
if len(snapshot) == 0 {
status = demoText("Save the workspace first", "请先保存工作区")
return
}
var state kit.DockState
if err := json.Unmarshal(snapshot, &state); err != nil {
status = err.Error()
return
}
if err := d.Restore(state); err != nil {
status = err.Error()
return
}
status = demoText("Layout restored and search panel rebuilt", "已恢复布局并重建搜索面板")
})
style := kit.Button(demoText("Toggle Dock appearance", "切换 Dock 外观"), func() {
styled = !styled
if styled {
d.Skin(customSkin)
} else {
d.Skin(nil)
}
})
toggles := []el.View{d.RegionButton(kit.DockLeft), d.RegionButton(kit.DockBottom), d.RegionButton(kit.DockRight)}
return el.Root(el.ViewFunc(func(cx *el.Context) el.Element {
width, _ := cx.ViewportSize()
compact := width < 720*max(float32(1), cx.TextScale())
d.Compact(compact)
return el.Div().Grow().Items(el.Stretch).Child(
el.Div().Row().Wrap().NoShrink().Items(el.Center).Gap(theme.SpaceSm).P(theme.SpaceSm).Child(save.Render(cx), restore.Render(cx), style.Render(cx),
el.Div().Row().Hidden(compact).Gap(theme.SpaceSm).Child(toggles[0].Render(cx), toggles[1].Render(cx), toggles[2].Render(cx))),
el.Text(status).NoShrink().TextSize(theme.TextSm).TextColor(theme.Muted), d.Render(cx))
}))
})
}
像 IDE 一样,把工具面板停靠在中间内容的左、右、下三侧。
d := kit.Dock(editor).
Panel(kit.DockPanel{ID: "files", Title: "文件", View: fileTree}, kit.DockLeft).
Panel(kit.DockPanel{ID: "term", Title: "终端", View: terminal}, kit.DockBottom).
OnLayoutChange(func(l kit.DockLayout) { save(l) })
if !d.SetLayout(loaded) { /* 不支持的版本或非法布局,保留原布局 */ }
- 每个停靠区可以放多个面板,用标签切换;长标签栏可横向滚动;停靠区和中间内容之间可以拖动调整大小。
- 面板标题栏右侧的菜单可以把面板移到另一侧,或者关闭它;
SetVisible(id, true)会在原来的停靠区重新打开。 - 最大化:菜单里的"最大化"或双击标签,让这个面板铺满整个 Dock,中间内容和其他面板暂时隐藏;再点"还原"、双击标签或按 Esc 恢复。
Zoom(id)/Zoom("")/Zoomed()在程序里控制,最大化状态保存在DockLayout.Zoomed。移走或关闭最大化的面板会自动还原。 - 面板会拿到停靠区的全部高度。Tree、Table、List 这类组件可以用
Fill()撑满,并自带滚动;较长的普通内容要自己包一层ScrollY。 DockLayout记录每个停靠区里有哪些面板及其顺序、当前标签、各区尺寸、已关闭的面板。它可以直接编码成 JSON 保存。版本为 2,旧的无版本布局和版本 1 迁移为单标签组;不认识的版本、重复跨区 ID、NaN/无穷尺寸会被原子拒绝,SetLayout返回 false 且保留原布局。SetLayout会忽略不认识的面板 ID,布局里没提到的面板保持原位。SetDisabled禁用面板与布局操作。分隔条可用方向键按 10dp 调整,Home / End 到边界;取消拖动恢复原尺寸,普通点击分隔条不触发布局回调。- 用户移动、关闭、切换面板或拖动调整大小之后,调用
OnLayoutChange。 - 窗口太窄时,左右两区会按比例缩小,给中间内容至少留出 120dp。
Agent:每个停靠区是以当前面板标题命名的 region,标签栏是 tablist,菜单按钮名为"更多 面板标题",菜单项是"停靠到左侧""停靠到右侧""停靠到底部""关闭"。
验证:go run ./examples/components -section dock,加 -theme dark 检查深色。
重复注册面板 ID 会更新标题和 View,保留所在区域;空 ID、非法区域不会加入。布局快照及恢复输入都做副本隔离,未知面板的 Visible 为 false。
嵌套分割:d.Split("search", "files", kit.DockPlacementBottom) 把搜索放到文件组下方;还支持 Left / Right / Top。标题菜单提供“向右拆分”和“向下拆分”,把当前标签从同组其他标签中拆出。分隔条可拖动,或用方向键每次调整 5%,Home / End 到 5% / 95%。取消拖动或禁用会恢复拖动前比例。Move 移到指定区域的首个标签组,并选中移入的标签;空组自动合并。关闭的组保留在布局中,重新打开时回到原位。
LeftTree / RightTree / BottomTree 由 DockNode 表达嵌套:叶子用 Panels / Active,分割用 First / Second / Axis / Ratio。树存在时,其面板顺序优先于旧的平面列表;旧列表仍随布局更新。恢复会深拷贝树,拒绝循环、超过 32 层、重复面板、缺失分支或越界比例,未知面板会剔除并合并空分支。布局快照可以直接 JSON 往返。程序调用 Split / Move / SetLayout 不触发布局回调。
拖动标签时,标题栏显示插入位置;放到另一组的中间会合并,放到正文四边会拆分。编辑器的左、右、下边缘可恢复空停靠区;对应区域已有面板时合并到其中一组。半透明色块表示落点,松开才改布局并回调一次,焦点跟随移入的标签。Esc、指针取消、放到外部或禁用都撤销预览。布局内的坐标使用 dp,拖放命中按实际可见裁剪范围判断。
中心区文档
Panel(p, kit.DockCenter) 把面板放进中心区,当作文档。中心区和侧边区一样由标签组组成:
- 文档可以拆分(
Split、标题菜单、拖到组的边缘)、拖动合并、最大化,布局通过CenterTree、Center、CenterActive一起保存。 - 有文档时,文档取代
Dock(center)传入的中心视图;文档全部关闭或移走后,中心视图重新出现,适合放“没有打开的文档”这类空状态。 - 侧边面板的菜单多了“移到中间”,中心文档的菜单可以停靠到左、右、下。用过
DockCenter的 Dock,中心区为空时,把标签拖到中间就会打开为文档。 - 中心区有文档时,只有紧贴边缘的 24dp 窄条用来恢复已经空掉的侧边区,其余位置的边缘用来拆分文档组。
跨窗口
d.OnDetach(func(p kit.DockPanel, reattach func()) {
window.Open(window.Options{Title: p.Title, Content: el.Root(p.View), OnClose: reattach})
})
- 设置
OnDetach后,面板菜单多出“在新窗口打开”。把标签拖出 Dock 范围松开,也会分离出去。 - 分离的面板从 Dock 里移走,
Visible为 false,Detached()列出它们,并调用一次OnLayoutChange。 - 新窗口关闭时调用
reattach,面板回到原来的停靠区和标签组。要在界面回调里调用(OnClose本来就是),其他 goroutine 用core.Update。 - kit 不自己开窗口,窗口大小、标题栏等由应用决定。
- 恢复布局不会重新打开窗口:
SetLayout把分离的面板放回 Dock。 - 不设置
OnDetach时,拖出 Dock 和以前一样是取消。
容器应有明确的宽高,通常直接用 el.Root(d)。嵌入普通页面时给外层指定宽高;Dock 内部按可用空间分配区域。
根视口中的首帧和每次缩放都先按当前视口分配停靠区,给中心保留 120dp;视口小于该值时,停靠区可缩到零,中心使用剩余空间。嵌入更小的容器时,首次绘制测得实际尺寸后会请求重绘并校正。此处“保留中心”不代表所有面板在手机宽度下都适合阅读。
面板状态与工厂
只保存位置继续用 Layout/SetLayout。要在新 Dock 中重建面板,使用 Snapshot/Restore,并按类型注册工厂:
factory := func(s kit.DockPanelState) (kit.DockPanel, error) {
input := kit.Input("搜索")
var query string
if len(s.State) > 0 {
if err := json.Unmarshal(s.State, &query); err != nil {
return kit.DockPanel{}, err
}
}
input.SetValue(query)
return kit.DockPanel{View: input, SaveState: func() (json.RawMessage, error) {
return json.Marshal(input.Value())
}}, nil // Restore 填入原来的 ID、Kind 和 Title
}
if err := d.RegisterPanel("search", factory); err != nil { /* 处理错误 */ }
state, err := d.Snapshot()
// json.Marshal(state) 保存;读回后 json.Unmarshal 到 kit.DockState。
if err == nil { err = anotherDock.Restore(state) } // anotherDock 也须注册 search
首次添加面板时设置 DockPanel.Kind: "search" 和 SaveState;工厂接收实例 ID、类型、标题和 JSON 数据,可以恢复同类型的多个实例。返回值的非空 ID/Kind 必须与快照匹配,View 不得为 nil;标题为空时继承快照,否则采用工厂标题。应用负责数据版本迁移,工厂也应返回新的 SaveState,才能继续保存编辑后的值。
DockState 版本为 1,内部 DockLayout 仍是版本 2。快照按 ID 排序,复制布局和 JSON,包括隐藏、分离的面板。注册表属于单个 Dock,空类型、nil 工厂和重复类型返回错误。没有 Kind 的既有静态面板可按 ID 原样复用,但不能携带 SaveState 或数据;要跨新实例恢复,所有面板都应有已注册的 Kind。
恢复先检查整份清单、JSON 和布局,再调用工厂。未知类型、重复 ID、布局引用缺失的面板、清单中没有布局位置的面板、非法树或工厂错误都会返回错误,保留当前 Dock。恢复成功后,面板集合以快照为准,当前多出来的面板被移除;中心空视图、外观、禁用状态、注册表和回调保留。工厂应只构造视图,外部副作用和已创建资源由应用管理,Dock 无法替应用回滚。
这些操作在 UI 线程调用,不触发 OnLayoutChange。面板数据编辑不会触发布局回调,应用应在保存工作区或关闭窗口时显式调用 Snapshot。分离面板恢复到 Dock 内,不自动开关应用窗口;旧窗口关闭回调不会影响恢复后的新实例。
独立外观
d.Skin(&kit.DockSkin{
Header: func(e *el.DivEl) { e.Bg(theme.Bg) },
Body: func(e *el.DivEl) { e.P(theme.SpaceLg) },
Tab: func(e *el.DivEl, selected bool) {
if selected { e.Bg(theme.Primary).TextColor(theme.PrimaryText) }
},
Separator: func(e *el.DivEl) { e.Bg(theme.Primary) },
})
Panel 配置标签组外框,Header/Body/Tab/Separator 分别配置标题栏、正文、标签与内外分隔条。回调每帧应用在新元素上,可改颜色、边框、字号和面板留白;保留元素身份、子内容和事件处理,分隔条保持 4dp 几何。配置对象可以共享并在 UI 线程更新,Skin(nil) 恢复默认外观,不改布局或面板内容。皮肤不进入布局 JSON,也不修改全局主题。它只管样式;面板自己的标签、工具栏和菜单见下一节。
组件库示例的“保存工作区 / 恢复工作区”可以验证搜索词随布局恢复,“切换 Dock 外观”用于检查皮肤。原生窗口、浅深色视觉和多窗口生命周期仍需真机验收。
面板的标签、工具栏和菜单
DockPanel 的可选字段让每个面板决定自己在 Dock 里的样子和行为:
d.Panel(kit.DockPanel{
ID: "files", Title: "文件", View: files,
Icon: kit.IconFolder, // 标签上的图标
Toolbar: kit.Button("", refresh).Name("刷新").Icon(kit.IconRetry).Variant(kit.ButtonGhost).Size(24),
Menu: func(m *kit.MenuView) { m.Item("全部折叠", "", collapseAll) },
NoClose: true, // 菜单里没有“关闭”
}, kit.DockLeft)
Icon显示在标题前;Tab(selected)完全替换标签内容(例如带状态点),Title仍是标签的无障碍名字。Toolbar在面板是当前标签时显示在标题栏右侧、菜单按钮之前。Menu往面板菜单里加项,排在 Dock 自带的移动、拆分、最大化、关闭之前。NoClose去掉“关闭”;NoZoom去掉“最大化”,双击标签和Zoom(id)也不再最大化它。NoPadding去掉正文留白,适合终端、画布这类贴边绘制的面板。
收起侧栏
toolbar.Child(d.RegionButton(kit.DockLeft).Render(cx), d.RegionButton(kit.DockBottom).Render(cx))
RegionButton(side) 返回一个切换按钮,侧栏展开时为选中状态,可放进标题栏或工具栏;按钮建一次后复用。SetRegionOpen(side, open) / RegionOpen(side) / ToggleRegion(side) 是对应的程序接口,ToggleRegion 会触发 OnLayoutChange。收起只是隐藏整块区域,面板的标签、拆分和尺寸都保留,再展开原样回来;收起状态存在布局的 LeftClosed/RightClosed/BottomClosed 里。中心区不能收起。收起最大化面板所在的侧栏会先退出最大化。
Compact(true) 将所有已打开的面板呈现为可横向滚动的标签栏,一次显示一个全宽面板。断点由宿主决定(Gallery 使用随字体缩放调整的 720dp)。区域折叠是桌面布局偏好,紧凑模式仍可访问其中已打开的面板;已关闭和已分离的面板不显示。保留面板内容、自定义标签、工具栏、自定义菜单动作、外观与禁止关闭设置。拆分、移动、调整尺寸和分离操作在桌面模式使用。
紧凑模式的当前面板独立于持久化布局:切换标签或调用 Compact(false) 不会覆盖桌面的分栏树、尺寸、活动标签和缩放,也不会触发 OnLayoutChange。关闭面板仍正常改变保存布局并通知;当前面板关闭后会选择另一个已打开面板,没有面板时显示中心占位内容。与普通 Dock 标签一样,输入状态应保存在面板视图中。