# 可拖动预览区与侧栏折叠设计 状态：已实现并验证 创建日期：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 样式。 ## 验收标准 1. 点击侧栏切换按钮，侧栏能在完整侧栏和窄图标栏之间切换。 2. 窄图标栏按钮悬停时都有清楚提示。 3. 打开右侧预览后，拖动左边缘能改变宽度。 4. 双击拖动把手能恢复默认预览宽度。 5. 预览区拉宽时，中间对话不会被挤到无法使用。 6. 刷新页面后，侧栏折叠状态和预览宽度仍保持。 7. 移动端或窄屏下不启用拖动，预览继续按现有方式占满屏幕。 ## 验证计划 - 运行前端检查。 - 启动应用。 - 打开已有 HTML 产物预览。 - 手动切换侧栏折叠状态。 - 手动拖动右侧预览宽度并双击恢复。 - 刷新页面确认状态保持。 - 缩小窗口确认不会出现不可用布局。 ## 实施结果 已按本文档方案实现： - 左侧栏支持完整侧栏与窄图标栏切换。 - 窄图标栏保留展开、当前知识库、刷新、新建、添加、设置入口。 - 窄图标栏按钮均有悬停提示。 - 右侧预览支持拖动左边缘调整宽度。 - 双击拖动边缘恢复默认宽度。 - 侧栏折叠状态和预览宽度会在本地保留。 - 移动端沿用全屏预览，不显示拖动边缘。 验证结果： - `npm run typecheck` 通过。 - 受控浏览器验证默认预览宽度为 420px。 - 受控浏览器验证拖动后预览区可变宽，并保持对话区可用。 - 受控浏览器验证双击拖动边缘可恢复默认宽度。 - 受控浏览器验证侧栏可折叠为 52px 窄图标栏，刷新后仍保持。 - 受控浏览器验证移动端预览占满屏幕，拖动边缘隐藏。