yuxuanhui
80 lines
6.5 KiB
Markdown
80 lines
6.5 KiB
Markdown
# 设计响应式前端交互体系
|
|
|
|
## Goal
|
|
|
|
为知行量化建立一套可持续扩展的前端组件风格、交互风格和响应式布局体系，使高密度研究工作台在桌面端保持紧凑高效，在移动端仍可清晰导航、查询数据并完成关键操作；通过可交互 HTML 原型先验证视觉方向与布局行为，再进入生产实现。
|
|
|
|
## Background
|
|
|
|
- `zhixing-web/DESIGN.md` 给出了暖白画布、炭黑主色、白色浮层卡片、细边框、克制圆角和 Inter/Geist 替代字体等视觉方向；其原始参考偏营销页面，本任务需要将其收敛为高密度数据工作台语言。
|
|
- 当前应用为 React 19 + TypeScript + Vite，使用 TanStack Router、TanStack Query、Zustand、Tailwind CSS 4 与 Base UI；代码采用 feature 垂直切片，共享 UI 位于 `src/shared/ui/`。
|
|
- `zhixing-web/src/features/home/components/home-shell.tsx` 直接承载侧栏、顶栏和内容容器，且归属 `home` feature；窄屏仍保留 80px 侧栏，没有面向触控设备的独立导航模式。
|
|
- `zhixing-web/src/features/selection/pages/selection-results-page.tsx` 的信号表设置 `min-width: 720px` 并依赖横向滚动，当前没有分页。
|
|
- `zhixing-web/src/shared/ui/button.tsx` 与 `input.tsx` 的默认控件高度为 32px，适合紧凑桌面界面，但不足以直接作为移动端触控规格。
|
|
|
|
## Requirements
|
|
|
|
### R1. 统一视觉与组件语言
|
|
|
|
- 将 `DESIGN.md` 的视觉方向转译为适合量化研究工作台的设计 token 和组件规范。
|
|
- 覆盖按钮、输入框、选择器、标签、卡片、表格、分页、弹窗、提示反馈、空状态、加载状态与错误状态。
|
|
- 桌面布局保持紧凑，但不能以牺牲信息层级、键盘操作或可读性为代价。
|
|
- 移动端交互控件采用适合触控的命中区域，不能机械复用桌面端 32px 高度。
|
|
|
|
### R2. 响应式 Layout
|
|
|
|
- 将应用壳从 `home` feature 中抽离为跨 feature 的 layout 模块，页面不得各自实现断点和导航切换逻辑。
|
|
- layout 的 interface 只暴露页面需要声明的稳定信息，例如页面标题区、页面操作区与内容；激活导航由路由状态推导，断点、导航形态、内容宽度、滚动策略、移动安全区和触控适配留在实现内部。
|
|
- 桌面端支持高密度侧栏 + 顶部工具区 + 有最大宽度的内容区。
|
|
- 移动端使用底部导航承载四个核心入口，低频功能进入“更多”菜单；同时提供紧凑标题区、内容单列化与底部安全区处理。
|
|
- 页面内容在布局切换时保持功能与语义一致，不维护两套业务页面。
|
|
- 业务页面不重复展示大标题、眉题和说明模块；当前页面上下文由应用顶栏承担，内容区直接展示操作、指标与业务数据。
|
|
- 桌面数据工作台采用有界布局：从应用壳到业务数据区连续传递可用高度，页面外层不参与纵向滚动；移动端解除有界高度，恢复自然页面滚动。
|
|
|
|
### R3. 表格与分页
|
|
|
|
- 数据表格提供可理解的总数、当前范围、页码和每页数量交互。
|
|
- 桌面端保留列式高密度浏览；移动端为关键信息设计专门呈现策略，而非仅依赖横向滚动。
|
|
- 桌面表格消费操作区、指标区之后的全部剩余高度，仅数据行视口滚动；筛选栏、表头和分页保持可见，分页固定在数据面板底部。
|
|
- 分页控件同时支持鼠标、键盘和触控，并清楚表达禁用、当前页及加载状态。
|
|
- 首版原型使用内存数据演示分页；生产实现是否采用服务端分页由后续数据规模和接口契约决定。
|
|
|
|
### R4. HTML 交互原型
|
|
|
|
- 提供无需后端即可运行或直接打开的 HTML 原型。
|
|
- 原型至少包含桌面与移动视口切换、主导航、代表性研究页、表格分页以及关键组件状态。
|
|
- 原型用于评审设计，不作为生产代码直接合入正式路由。
|
|
- 原型要能展示布局状态和当前交互状态，使评审者看得见导航、分页、弹窗等行为变化。
|
|
|
|
### R5. 架构落点
|
|
|
|
- 应用级布局归入 `app/layout`，无业务语义的 UI primitive 归入 `shared/ui`；业务页面与业务数据呈现留在各自 feature。
|
|
- layout 模块应形成高杠杆的 interface：删除它会使响应式、导航和滚动复杂度重新散落到多个页面，而不是成为只转发 `className` 的浅模块。
|
|
- 保持现有 TanStack Router、Tailwind CSS 4、Base UI 与 feature 依赖方向，不在本迭代引入第二套组件框架。
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] HTML 原型可在桌面与移动视口间切换，并清晰展示两种布局形态。
|
|
- [ ] 桌面端在常见 1280px/1440px 宽度下呈现紧凑侧栏、工具区和数据内容，无不必要的大面积留白。
|
|
- [ ] 移动端在 375px/390px 宽度下无页面级水平溢出，主要操作可单手触达，内容不被导航或安全区遮挡。
|
|
- [ ] 原型包含统一的按钮、表单、标签、卡片、反馈、弹窗、表格与分页视觉和交互状态。
|
|
- [ ] 表格可实际翻页、切换每页数量，并展示总数、当前记录范围、当前页与禁用状态。
|
|
- [ ] 桌面端表格填满剩余视口高度，长列表仅滚动数据区，分页不随数据行滚出面板；页面不出现竞争或嵌套纵向滚动条。
|
|
- [ ] 移动端表格可读取并操作关键信息，不以整页横向滚动作为唯一方案。
|
|
- [ ] 技术设计明确 layout 模块的 seam、interface、内部职责、路由集成方式和页面迁移策略。
|
|
- [ ] 技术设计明确桌面密度与移动触控尺寸的 token/variant 关系，避免页面内散落设备判断。
|
|
- [ ] 规划说明 HTML 原型哪些决策会进入正式组件，哪些仅为验证用途。
|
|
|
|
## Out of Scope
|
|
|
|
- 本轮规划不修改后端接口、业务计算或数据同步流程。
|
|
- 原型阶段不实现完整生产组件库、不接入真实后端、不承诺暗色模式。
|
|
- 不照搬 `DESIGN.md` 中面向营销站的超大展示字号、定价卡片或产品截图布局。
|
|
- 未经单独确认，不提交、不推送、不发布原型。
|
|
|
|
## Product Decisions
|
|
|
|
- 移动端主导航采用“底部导航 + 更多菜单”，不使用顶部菜单按钮作为唯一主导航。该选择优先保证高频模块切换和单手可达性，并接受底部导航占用约 56–64px 视口空间的代价。
|
|
- 最终视觉结构采用 A「紧凑工作台」的应用壳与 C「主从研究台」的详情面板组合。
|
|
- 删除各页面内容区内重复的标题说明模块；桌面端由顶栏显示路由上下文，移动端由紧凑顶栏显示当前页面，内容区从按钮和核心数据开始。
|