description: "Web GUI 的外壳布局：三栏 AppFrame（右栏作为贴边面板的轨道）、面板几何服务与主题呈现；供窗口外壳的使用者与维护者阅读。" kind: "package-reference"

@deepseek-ai/dsh-client-ui-layout

English | 中文

概述

本包提供 Web GUI 的三栏 AppFrame、左右栏宽度与 ctx.layout 呈现控制。右栏先让步以保护中栏空间，全屏由占用方呈现，框架保留宽屏底层轨道。主题呈现器负责配色、别名 token、正文字号与 document 元数据；布局状态在刷新后重置。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

本插件在 root slot 中组合侧边栏、主内容和右栏。侧边栏宽度为 264～420px，默认为 280px，收起后保留 56px 控制栏；窗口宽度低于 1024px 时自动收起，打开右侧面板也会收起手动展开的侧边栏。右侧面板首次打开时使用视口宽度的 45%，之后保留用户的像素宽度偏好，上限为 70%。为给中栏保留 400px，框架先将右侧面板缩减至 300px，再报告空间不足，使占用方将其关闭，最后才进一步压缩中栏。拖动没有过渡延迟；右侧手柄在关闭或全屏时不显示。

全局面板占据 root 作用域的 main keyed slot；conversation 是为会话界面保留的 key。ctx.layout.selectPanel(id) 选中已注册面板，null 则选中会话界面，但不改变当前会话。默认组合不注册任何全局面板。

Windows Electron 的 data-windows-titlebar 标记在所有列上方预留顶栏高度，并移除收起后的侧栏轨道。内容区仅左上角保留 16px 圆角，其余角和内部交界处保持直角。框架发布 --dsh-windows-content-radius 和 --dsh-windows-sidebar-width，供 ui-sidebar-right 的全屏圆角及侧栏避让使用。普通 Web 文档不会获得该标记；macOS 保留其独立布局。

可选 Session 的 shell.toolbar slot 占据三栏上方横跨整框的 toolbar 行——桌面桥统一 macOS 工具栏的席位。没有占用方时该行是零高度轨道，纯 Web 布局保持不变。已挂载的工具栏通过 ctx.layout.setToolbarHosts / releaseToolbarHosts 发布两个 portal 宿主；所有组件通过标准 useToolbarHosts hook 读取该注册（未挂载工具栏时为 null）。

主题呈现

呈现器消费解析后的主题快照，并投影到 document：html { color-scheme } 驱动原生 UA 控件，依据当前配色方案设置 body[data-ds-dark-theme]，把主题的别名 token 与 --dsh-content-font-size 设为 body 上的内联变量，并持有一个 <meta name="theme-color">，其内容随计算后的 body 背景色更新。对呈现器执行 dispose（资源释放）时，它会连同其他全局写入一起移除自己的元数据节点。

理解实现

selectPanel(id) 在改变选中态前检查实时 main 注册表；缺失的 key 会抛错并保留当前面板。beginNavigation() 为异步 UI 导航返回 abort signal。后续调用、有效面板选择（包括重复选择）或布局释放会中止该 signal，但不取消底层会话创建。消费方在提交导航或搬移草稿前检查 signal。

一次注册声明五个子 slot，并绑定 ctx.layout 的 selectPanel、toggleSidebar、openRightbar(track, fullscreen) 与 closeRightbar。同一个 root 存储把 panelInfo 选中态与 layoutInfo 测量、宽度偏好、呈现报告分开。usePanelInfo 订阅引用稳定的选中态对象，AppFrame 订阅引用稳定的布局对象。toolbar 宿主注册表位于布局控制器上：release 以引用相等做守卫，过期的 HMR disposer 不会清除新工具栏发布的宿主对；控制器释放时撤回注册，使会话标题头回到就地形态。useToolbarHosts 把该注册表适配到与 usePanelInfo 相同的 root 通道。rightbar owner 提供实际 width、viewportWidth，以及表示能否以普通模式呈现的 canShow；占用方在空间不足时执行确定性的收起，变宽不自行重新展开。全屏隐藏宽度手柄，但不自行释放占用方要求保留的轨道。AppFrame 保持各列容器挂载。右栏的 root 控制器仅在选中会话界面时，经 SessionProvider 渲染 rightbar.session；内容卸载时的报告释放轨道。独立的标题组件仅在会话界面可见时使用所选会话标题，以构建配置的产品标题或本地化 common.brand.localBuild 为回退值；语言变化会更新该回退值。主题呈现器是第二个 effect：从解析后的快照做纯 DOM 写入——初始状态经 getter 读取一次，此后仅事件驱动，不经过 React。它先应用调色板、字号与 token 变量，再把渲染出的背景测量为唯一的颜色依据。全屏呈现禁用网格和手柄过渡；占用方完全覆盖框架后才报告新的列布局。退出全屏时，框架先保持无过渡并安装目标布局：关闭移除右轨道，恢复保留右轨道。后续普通几何操作恢复正常过渡。

进一步探索

当布局面不够用时阅读以下页面。它们从框架进入它所渲染的栏与它所呈现的主题。

• ui-sidebar——占据 sidebar 栏及其座位。
• ui-conversation——占据 main 中的 conversation key。
• ui-sidebar-right——以每会话一个停靠面占据 rightbar 栏。
• ui-theme——呈现器消费其解析快照的主题 seam。
• Web 客户端架构——浏览器插件行如何加载并注册槽位。

模型体验

无。布局外壳管理浏览器查看状态；这里没有任何内容进入模型请求。

KV Cache 影响

无；该包既不组装也不发送提供方请求。

已知限制与延期工作

这些限制界定了当前布局行为。它们是当前包约束，不是通用窗口管理器对比或任务积压。

• 面板几何是瞬时状态——重新加载会恢复侧栏默认值并隐藏右侧面板；拖动设置的宽度是整个框架共用的一份偏好，而非每个会话各自的属性。
• 极窄窗口——右侧面板关闭后，中栏仍可能小于 400px；左侧 56px 控制栏仍会保留。
• 轨道与面板沿同一条曲线运动——框架的轨道过渡和占用方的滑入读取同一组时长与缓动变量；占用方若自用一套，挤压时面板边缘就会与会话界面的边缘脱开。
• 挤压重排期间无滚动锚定——布局变化可能移动读者的视口。

开发备注

无。

运行时不变式： 不发布伴生入口。外壳中 ctx.layout 背后的浏览状态存储不发出 Cordis 事件；clamp 与轨道的时序由本包各栏与服务规格直接断言。