06-UI交互规范.md 6.06 KB

Edit Raw Blame History



06-UI交互规范


本项目所有页面布局以项目根 prototype/ 目录下的静态 HTML mockup 为权威。前端阶段（fe-feature-*）实现时直接以 prototype/ HTML 推导组件树与样式。本文件仅承载跨页面通用规则与 Design Tokens。


一、通用交互规则


1.1 操作反馈


成功提示：使用 Ant Design message.success()，默认 3s 自动消失；新增 / 修改 / 删除等写操作必须给反馈。

失败提示：使用 message.error() 显示后端返回的 message 字段；表单字段级错误用 Form 的 validateStatus="error" + help 同步显示。

危险操作二次确认：删除 / 禁用 / 重置密码等不可逆操作必须用 Modal.confirm({ okType: 'danger' }) 二次确认，按钮文案使用业务动词（如「确认禁用」），不用「确定」。

长耗时按钮 loading：提交类按钮在请求未返回前必须置为 loading=true 并禁用，避免重复提交；查询类操作在表格组件上启用 loading 属性即可。


1.2 数据展示


空状态：列表 / 表格无数据时使用 <Empty description="暂无数据" />，明细页无数据时附加「返回列表」按钮。

加载状态：页面级加载用 <Spin spinning> 包裹主区域；表格 / 卡片局部加载用组件自带 loading 属性。

异常状态：接口 5xx 或网络异常时显示 <Result status="error" title="加载失败" extra={<Button>重试</Button>} />；403 时显示「无权限」并提供「返回首页」按钮。


1.3 权限控制（前端）


菜单级：登录后由后端返回菜单权限码列表，前端 Layout 按权限码过滤后渲染左侧菜单。

按钮级：包装 <AuthButton code="USR:ADD">新增</AuthButton>，权限码不在用户列表时直接不渲染（避免显示再禁用）。

路由级：在 React Router 外层包 <AuthRoute />，路由元数据声明 meta.code，无权限重定向 403 页面。

关联后端 RBAC：权限码格式 <模块代码>:<动作>（如 USR:ADD / USR:EDIT / USR:DELETE），与后端 Spring Security @PreAuthorize("hasAuthority('USR:ADD')") 一一对应。


二、Design Tokens


所有色值统一以 CSS 变量定义于 src/styles/tokens.css；命名规范见 docs/04 § 2.5。


2.1 全局调色板

与 Ant Design 5 主题对齐，统一通过 <ConfigProvider theme={{ token: {...} }}> 注入。


语义
变量名
默认值
用途


主色
--color-primary
#1677ff
主操作按钮 / 链接 / 选中态


成功
--color-success
#52c41a
成功消息 / 启用状态标签


警告
--color-warning
#faad14
警告消息 / 待处理状态


错误
--color-error
#ff4d4f
错误消息 / 危险按钮 / 禁用状态


主文字
--color-text-primary
rgba(0, 0, 0, 0.88)
正文 / 表格内容


次文字
--color-text-secondary
rgba(0, 0, 0, 0.65)
辅助说明 / 占位


边框
--color-border
#d9d9d9
表单输入 / 卡片边界


背景
--color-bg-base
#ffffff
页面主背景


弱背景
--color-bg-layout
#f5f5f5
页面 layout 间隙 / 灰底


2.2 组件级状态色


序号
组件
编辑bg
只读bg
悬浮bg
编辑fg
只读fg
悬浮fg
备注


1
表单输入框
var(--color-bg-base)
var(--color-bg-layout)
var(--color-bg-base)
var(--color-text-primary)
var(--color-text-secondary)
var(--color-text-primary)
只读态边框使用 transparent


2
下拉单选
var(--color-bg-base)
var(--color-bg-layout)
var(--color-bg-base)
var(--color-text-primary)
var(--color-text-secondary)
var(--color-text-primary)
—


3
表格行
—
var(--color-bg-base)
var(--color-bg-row-hover)
—
var(--color-text-primary)
var(--color-text-primary)
编辑态走 Modal，行内不编辑


4
主按钮
var(--color-primary)
var(--color-bg-layout)
var(--color-primary-hover)
#ffffff
var(--color-text-secondary)
#ffffff
危险按钮替换 --color-error


5
链接
—
—
var(--color-primary-hover)
var(--color-primary)
—
var(--color-primary-hover)
—


Token 默认值：


Token
默认值


--color-primary-hover
#4096ff


--color-bg-row-hover
#fafafa


2.3 引用约定


组件样式只用 var(--color-xxx)，禁止硬编码 hex / rgba。
新增 token 须先登记到 § 2.1 / 2.2 再补 tokens.css。
修改色值只改 tokens.css 一处，不允许组件覆盖。


三、页面清单


module_usr USR-用户管理


登录页 (/login)


类型: 表单页
对应 REQ: REQ-USR-001
入口菜单: 无（未登录态唯一可达页面）
主要交互: 表单输入 用户名 / 密码 / 版本 → 提交 → 成功跳首页 / 失败留页并显示通用错误消息；账号锁定时显示锁定提示


用户列表页 (/usr/users)


类型: 列表页
对应 REQ: REQ-USR-004
入口菜单: 系统管理 → 用户管理 → 用户列表
主要交互: 查询字段 + 匹配方式 + 查询值 三段筛选 → 表格分页展示 → 行内「编辑」「禁用 / 启用」按钮（权限码 USR:EDIT）；顶部「新增用户」按钮（权限码 USR:ADD）跳新增表单


用户新增页 (/usr/users/new)


类型: 表单页
对应 REQ: REQ-USR-002
入口菜单: 系统管理 → 用户管理 → 用户列表 → 新增按钮
主要交互: 员工名（下拉单选）选择后自动回填用户号 / 用户名；类型 / 语言下拉；权限组表格（多选）；提交校验失败显示字段级 validateStatus="error"；成功 message.success 后回列表页


用户编辑页 (/usr/users/:id/edit)


类型: 表单页
对应 REQ: REQ-USR-003
入口菜单: 用户列表 → 行内「编辑」按钮
主要交互: 复用新增表单组件；用户名只读；提供「重置密码」按钮（二次确认）；提供「禁用 / 启用」开关；禁用自己时按钮置灰