6.1 KiB
6.1 KiB
可拖动预览区与侧栏折叠设计
状态：已实现并验证
创建日期：2026-05-28
实现日期：2026-05-28
背景
当前界面是左侧知识库导航、中间对话、右侧预览的三段式布局。左侧栏固定 270px，右侧预览打开后固定 420px。这个设计稳定，但在直接预览 HTML/PDF/页面产物时，右侧区域偏窄，用户常常需要全屏才能看清内容；全屏又会完全遮住对话上下文。
本设计补强现有产品方向：对话仍是主屏，右侧预览仍是辅助面板，但允许用户在“边聊边看”和“重点看预览”之间快速调整空间。
目标
- 右侧预览区可以通过鼠标拖动左边缘变宽或变窄。
- 左侧知识库栏可以折叠成窄图标栏，释放更多横向空间。
- 窄图标栏的每个按钮都有悬停文字提示。
- 用户调整后的侧栏状态和预览宽度会被记住。
- 保留现有全屏预览按钮，作为只看产物的极端模式。
不做什么
- 不把三栏全部做成自由拖动。左侧栏是导航区，折叠已经能解决占空间问题。
- 不新增 npm 依赖。
- 不改变知识库、对话、产物的数据结构。
- 不改变右侧预览的内容渲染方式。
方案选择
采用“右侧预览可拖动 + 左侧栏折叠为窄图标栏”。
对比过三个方向：
- 只让右侧预览可拖动：最稳，改动集中，但左侧仍占固定空间。
- 三栏都可拖动：自由度最高，但容易拖乱界面，状态和边界复杂度更高。
- 预设宽度 + 全屏：简单，但不如拖动自然。
最终方案在第一个方向上补上左侧栏折叠，既保留清晰心智，又能明显释放预览空间。
交互设计
左侧栏
完整侧栏保持当前结构：顶部品牌和操作按钮，下面是知识库与对话列表，底部是新建和添加入口。
新增一个“切换侧栏”按钮，放在侧栏顶部，与刷新、设置同级。点击后侧栏在两种状态间切换：
- 完整侧栏：显示知识库、对话、按钮文字。
- 窄图标栏：只显示核心图标，不显示长文字。
窄图标栏至少包含：
- 展开侧栏
- 当前知识库入口
- 新建知识库
- 添加现有库
- 设置
所有图标按钮都需要悬停提示，例如“展开侧栏”“当前知识库”“新建知识库”“添加现有库”“设置”。
折叠状态不应该让用户迷路：窄栏始终保留展开按钮，且当前知识库入口要能表达“当前仍在某个库里”。
右侧预览
右侧预览打开时，在它的左边缘显示一条细拖动把手。
交互规则：
- 按住把手向左拖，预览区变宽。
- 按住把手向右拖，预览区变窄。
- 双击把手，恢复默认宽度。
- 关闭预览区后释放空间。
- 再次打开预览区时使用上次宽度。
- 全屏按钮保留，进入全屏后不显示拖动把手。
宽度边界
右侧预览宽度需要限制在合理范围内：
- 默认宽度：420px。
- 最小宽度：360px，保证预览和标签仍可用。
- 最大宽度：视口宽度的 70%，但必须给中间对话保留至少 420px。
当窗口太窄时，优先保证对话区可用；移动端沿用现有逻辑，右侧预览占满屏幕，不启用拖动。
状态记忆
使用本地浏览器存储记住：
- 侧栏是否折叠。
- 右侧预览宽度。
刷新页面后恢复上次状态。异常值需要自动回到默认值，避免用户因为窗口变化进入不可用布局。
页面结构
整体仍是三段式：
- 左：导航区，完整侧栏或窄图标栏。
- 中：对话区，占用剩余空间。
- 右：预览区，打开时显示，宽度可调整。
中间对话区不设置固定宽度，而是随左右两侧变化自动伸缩。这样右侧拉宽时，对话区自然变窄；右侧收窄或关闭时，对话区自然变宽。
实现边界
预计改动集中在：
web/src/App.tsx：保存侧栏状态、预览宽度，并传给组件。web/src/components/Sidebar.tsx：支持完整侧栏和窄图标栏两种形态。web/src/components/RightDrawer.tsx：增加拖动把手和宽度回调。web/src/index.css：增加折叠侧栏、拖动把手、宽度状态的样式。
不需要改后端。
可访问性与细节
- 侧栏切换按钮需要有明确的
aria-label。 - 拖动把手需要可聚焦，并提供键盘兜底：左右方向键调整宽度，Home 或双击恢复默认宽度。
- 拖动中避免选中文本。
- 拖动中给把手明确的 hover/active 状态。
- 窄图标栏的提示文案使用现有 tooltip 样式。
验收标准
- 点击侧栏切换按钮，侧栏能在完整侧栏和窄图标栏之间切换。
- 窄图标栏按钮悬停时都有清楚提示。
- 打开右侧预览后，拖动左边缘能改变宽度。
- 双击拖动把手能恢复默认预览宽度。
- 预览区拉宽时，中间对话不会被挤到无法使用。
- 刷新页面后，侧栏折叠状态和预览宽度仍保持。
- 移动端或窄屏下不启用拖动，预览继续按现有方式占满屏幕。
验证计划
- 运行前端检查。
- 启动应用。
- 打开已有 HTML 产物预览。
- 手动切换侧栏折叠状态。
- 手动拖动右侧预览宽度并双击恢复。
- 刷新页面确认状态保持。
- 缩小窗口确认不会出现不可用布局。
实施结果
已按本文档方案实现：
- 左侧栏支持完整侧栏与窄图标栏切换。
- 窄图标栏保留展开、当前知识库、刷新、新建、添加、设置入口。
- 窄图标栏按钮均有悬停提示。
- 右侧预览支持拖动左边缘调整宽度。
- 双击拖动边缘恢复默认宽度。
- 侧栏折叠状态和预览宽度会在本地保留。
- 移动端沿用全屏预览，不显示拖动边缘。
验证结果：
npm run typecheck通过。- 受控浏览器验证默认预览宽度为 420px。
- 受控浏览器验证拖动后预览区可变宽，并保持对话区可用。
- 受控浏览器验证双击拖动边缘可恢复默认宽度。
- 受控浏览器验证侧栏可折叠为 52px 窄图标栏，刷新后仍保持。
- 受控浏览器验证移动端预览占满屏幕，拖动边缘隐藏。