README.zh.md 6.1 KB
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 则选中会话界面，但不改变当前会话。默认组合不注册任何全局面板。
主题呈现
呈现器消费解析后的主题快照，并投影到 document：html { color-scheme } 驱动原生 UA 控件，依据当前配色方案设置 body[data-ds-dark-theme]，把主题的别名 token 与 --dsh-content-font-size 设为 body 上的内联变量，并持有一个 <meta name="theme-color">，其内容随计算后的 body 背景色更新。释放呈现器时，它会连同其他全局写入一起移除自己的元数据节点。
理解实现
实现细节——点击展开
`selectPanel(id)` 在改变选中态前检查实时 `main` 注册表；缺失的 key 会抛错并保留当前面板。`beginNavigation()` 为异步 UI 导航返回 abort signal。后续调用、有效面板选择（包括重复选择）或布局释放会中止该 signal，但不取消底层会话创建。消费者在提交导航或搬移草稿前检查 signal。 一次注册声明四个子slot并绑定 `ctx.layout` 的 `selectPanel`、`toggleSidebar`、`openRightbar(track, fullscreen)` 与 `closeRightbar`。同一个 root 存储把 `panelInfo` 选中态与 `layoutInfo` 测量、宽度偏好、呈现报告分开。`usePanelInfo` 订阅引用稳定的选中态对象，AppFrame 订阅引用稳定的布局对象。`rightbar` 的owner参数为实际 `width`、`viewportWidth` 与普通呈现的 `canShow`；占用方在空间不足时执行确定性的收起，变宽不自行重新展开。全屏隐藏宽度手柄，但不自行释放占用方要求保留的轨道。AppFrame 保持各列容器挂载。右栏的 root 控制器仅在选中会话界面时，经 `SessionProvider` 渲染 `rightbar.session`；内容卸载时的报告释放列宽。独立的标题组件仅在会话界面可见时使用所选会话标题，以构建配置的产品标题或本地化 `common.brand.localBuild` 为回退值；语言变化会更新该回退值。主题呈现器是第二个 effect：从解析后的快照做纯 DOM 写入——初始状态经 getter 读取一次，此后仅事件驱动，不经过 React。它先应用调色板、字号与 token 变量，再把渲染出的背景测量为唯一的颜色依据。 全屏呈现禁用网格和手柄过渡；占用方完全覆盖框架后才报告新的列宽。 退出全屏时，框架先保持无过渡并安装目标布局：关闭移除右轨道，恢复保留右轨道。后续普通几何操作恢复正常过渡。进一步探索
当布局面不够用时阅读以下页面。它们从框架进入它所渲染的栏与它所呈现的主题。
- ui-sidebar——占据
sidebar栏及其座位。 - ui-conversation——占据
main中的conversationkey。 - ui-sidebar-right——以每会话一个停靠面占据
rightbar栏。 - ui-theme——呈现器消费其解析快照的主题 seam。
- Web 客户端架构——浏览器插件行如何加载并注册槽位。
模型体验
无。布局外壳管理浏览器查看状态；这里没有任何内容进入模型请求。
KV Cache 影响
无；该包既不组装也不发送提供方请求。
已知限制与延期工作
这些限制界定了当前布局行为。它们是当前包约束，不是通用窗口管理器对比或任务积压。
- 面板几何是瞬时状态——重新加载会恢复侧栏默认值并隐藏右侧面板；每个拖出的宽度都是一份框架级偏好，不是按 Session 的事实。
- 极窄窗口——右栏关闭后，中栏仍可能小于400px；左侧56px控制栏保留。
- 轨道与面板沿同一条曲线运动——框架的轨道过渡和占位方的滑入读取同一组时长与缓动变量；占位方若自用一套，挤压时面板边缘就会与对话边缘脱开。
- 挤压重排期间无滚动锚定——布局变化可能移动读者的视口。
开发备注
维护者的工作上下文——点击展开
无。运行时不变式： 不发布伴生入口。ctx.layout 后的 viewing-state store 不发出 Cordis 事件；clamp 与轨道的时序由本包的 columns 与 service 规格直接断言。