diff --git a/frontend/ui-ux.md b/frontend/ui-ux.md index fec77e9..29c0eba 100644 --- a/frontend/ui-ux.md +++ b/frontend/ui-ux.md @@ -8,7 +8,7 @@ tags: - standard summary: 本文定义项目技术栈选型、z-index层级规范及响应式布局要求 cover: /assets/default-cover.jpg -updated: '2026-07-20' +updated: '2026-08-15' --- ## 技术栈规范 @@ -16,7 +16,7 @@ updated: '2026-07-20' | ---------- | ----------------------------- | ---------------------------------------------------------------------- | | 前端框架 | Vue 3 + JavaScript | 不使用 TypeScript | | 构建工具 | Vite + pnpm | 包管理统一使用 pnpm | -| UI 框架 | tdesign-vue-next | 严格使用第三方组件，尽可能少使用原始标签 | +| UI 框架 | tdesign-vue-next | 严格使用 TDesign 组件，尽可能少使用原始 HTML 标签 | | 图标库 | tdesign-icons-vue-next | 所有 icon 统一使用 tdesign-icons-vue-next | | 状态管理 | Pinia | 全局状态集中管理 | | 代码规范 | eslint + @antfu/eslint-config | 统一代码风格 | @@ -33,23 +33,23 @@ updated: '2026-07-20' | 100 | sticky | sticky 表头、吸顶筛选栏 | | 200 | local-floating | 页面局部浮动按钮、局部工具栏 | | 300 | fixed-nav | 顶部导航、移动端底部导航 | -| 400 | dropdown | Dropdown、Select、DatePicker、Autocomplete | -| 500 | popover | Popover、Tooltip、HoverCard | +| 400 | dropdown | Dropdown、Select、DatePicker、AutoComplete | +| 500 | popover | Popup、Tooltip、Popconfirm | | 800 | overlay-local | 页面局部遮罩、局部 loading | | 1000 | overlay | 全局遮罩 | | 1100 | drawer | Drawer、侧边抽屉 | -| 1200 | modal | Modal、Dialog | -| 1300 | modal-floating | Modal 内部 Dropdown、Popover、Tooltip | -| 1400 | toast | Toast、全局通知 | +| 1200 | modal | Dialog | +| 1300 | modal-floating | Dialog 内部 Dropdown、Popup、Tooltip | +| 1400 | toast | Message、Notification | | 1500 | global-loading | 全屏 Loading、页面阻断加载 | | 2000 | onboarding | 新手引导、产品引导遮罩 | | 3000 | system | 系统级弹窗、强制升级、维护提示 | | 9000 | emergency | 特殊兜底层，必须注释说明 | | 9999 | max | 最高优先级，仅限极特殊场景 | -- 多数场景使用 Tailwind `z-{number}` 直接对应（`z-100`、`z-300`、`z-400`、`z-500`、`z-1200`、`z-1300`）。 -- 1000 之后是 4 位数，Tailwind 默认不提供，使用 `z-[1000]` / `z-[1300]` 等任意值语法。 -- 0 ~ 500 用 `z-` 原生档位；不随意使用 `z-[9999]`。 +- 层级统一通过项目维护的 CSS 变量管理，如 `--z-dropdown: 400`、`--z-drawer: 1100`、`--z-dialog: 1200`、`--z-message: 1400`、`--z-loading: 1500`。 +- TDesign 弹层组件（Dropdown、Popup、Dialog、Drawer、Message、Notification、Loading）通过主题变量或包裹层对齐上述层级，避免与项目 z-index 体系冲突。 +- 0 ~ 500 为常规内容层级，1000 以上为弹层体系；不随意使用最高档位 `--z-max`。 ## Scroll 滚动规范 @@ -60,11 +60,11 @@ updated: '2026-07-20' | 滚动恢复 | 支持页面级 scroll restoration | 列表页返回时恢复原滚动位置，普通页面进入默认滚动到顶部 | | 滚动区域 | 明确 scroll-root | Layout 层定义主滚动容器，业务组件不得随意创建页面滚动区域 | | 局部滚动 | scroll-section | 大列表、日志、代码区域等允许局部滚动，但必须明确高度和边界 | -| 弹窗滚动 | Modal / Drawer 独立滚动 | 弹窗内部内容滚动，不影响 body 滚动状态 | -| Body 锁定 | Overlay 打开时禁止背景滚动 | Modal、Drawer、全屏遮罩打开时锁定 body，关闭后恢复 | +| 弹窗滚动 | Dialog / Drawer 独立滚动 | 弹窗内部内容滚动，不影响 body 滚动状态 | +| Body 锁定 | Overlay 打开时禁止背景滚动 | Dialog、Drawer、全屏遮罩打开时锁定 body，关闭后恢复 | | Sticky | 必须绑定正确滚动容器 | sticky 元素必须位于对应 scroll container 内，避免定位失效 | -| 表格滚动 | VXE Table 统一处理 | 表格内部横向滚动，禁止页面整体横向滚动 | -| 表格固定 | 使用组件能力 | VXE Table 固定表头、固定列必须使用组件配置，不手写定位实现 | +| 表格滚动 | TDesign Table 统一处理 | 表格内部横向滚动，禁止页面整体横向滚动 | +| 表格固定 | 使用组件能力 | TDesign Table 固定表头、固定列必须使用组件配置，不手写定位实现 | | 大数据列表 | 必须虚拟滚动 | 超过指定数据量的大列表必须使用虚拟列表优化性能 | | 滚动事件 | Hook 统一封装 | 禁止页面散落 addEventListener，统一通过 useScroll 等 hooks 管理 | | 滚动监听 | 必须节流优化 | scroll 事件必须使用 throttle / requestAnimationFrame 降低性能消耗 | @@ -72,7 +72,7 @@ updated: '2026-07-20' | 减少动画 | 支持 prefers-reduced-motion | 用户开启减少动画模式时关闭滚动动画效果 | | 锚点定位 | 统一 scrollToAnchor | 禁止业务组件直接调用 scrollIntoView，统一封装滚动方法 | | Sticky 偏移 | 使用 scroll-margin-top | 页面存在固定导航时，锚点定位必须考虑顶部遮挡问题 | -| 返回顶部 | local-floating 层级 | 返回顶部按钮使用 z-200，超过滚动阈值后显示 | +| 返回顶部 | local-floating 层级 | 返回顶部按钮使用 local-floating 层级（200），超过滚动阈值后显示，优先使用 TDesign BackTop 组件 | | 横向滚动 | 禁止页面级横向滚动 | 页面禁止 overflow-x 滚动，特殊区域必须局部控制 | | 移动端滚动 | 适配 Touch 滚动 | 支持 iOS / Android 惯性滚动，避免滚动卡顿 | | 滚动高度稳定 | 避免 CLS | Skeleton、图片、异步内容必须保持高度稳定，避免滚动位置跳动 | @@ -116,7 +116,7 @@ updated: '2026-07-20' | API 结构 | 按模块拆分 | `api/modules/*.api.js`，禁止写在组件内 | | 请求拦截 | Token + Error 统一处理 | 自动注入 token、统一处理 401/500 | | 响应结构 | 标准化返回 | `{ code, data, message }` 统一格式 | -| 错误处理 | 全局错误中心 | Toast + 日志 + 可选上报 | +| 错误处理 | 全局错误中心 | Message + 日志 + 可选上报 | | 取消请求 | AbortController | 页面切换自动取消未完成请求 | | 并发控制 | 防重复请求 | 相同 key 请求去重 | | Loading 管理 | 请求级 + 页面级 | 避免手动控制 loading 状态 | @@ -131,15 +131,15 @@ updated: '2026-07-20' | 模块加载 | 局部骨架屏 | 卡片、列表、表格、详情区按实际内容占位 | | 数据刷新 | 保留旧数据 + 局部 Loading | 不清空页面，避免用户失去上下文 | | 表单提交 | 按钮 Loading + 禁用提交按钮 | 防重复提交，提交中保留表单内容 | -| 表格加载 | VXE Table loading / 表格骨架 | 表头固定，行高稳定，禁止整页遮罩替代表格加载 | +| 表格加载 | TDesign Table loading / 表格骨架 | 表头固定，行高稳定，禁止整页遮罩替代表格加载 | | 路由切换 | 页面级 Loading | 只在跨页面等待明显时使用，优先展示目标页骨架 | | 阻断型任务 | 全局 Loading | 仅限鉴权初始化、应用启动、强制等待等不可交互场景 | - 骨架屏必须贴近真实布局：标题、头像、卡片、表格行、按钮区域要按最终尺寸占位，禁止使用一整块灰色矩形糊弄。 -- 骨架屏风格必须匹配 Animal Island：圆角、柔和底色、轻微点状或软边框质感；禁止使用生硬的 Tailwind 默认灰阶风格。 +- 骨架屏风格必须匹配 TDesign 设计语言：圆角、柔和底色、轻微点状或软边框质感；禁止使用生硬的默认灰阶风格。 - 骨架元素必须有稳定宽高、`min-height` 或固定行高，加载完成前后不能造成明显 CLS。 - 首次进入页面优先使用骨架屏；只有小面积异步操作、按钮提交、短时请求才使用 spinner / loading icon。 -- 局部 Loading 使用层级 `z-800`；全屏 Loading 使用 `z-[1500]`，不得随意使用 `z-[9999]`。 +- 局部 Loading 使用层级 `--z-overlay-local: 800`；全屏 Loading 使用 `--z-global-loading: 1500`，不得随意使用最高档位。 - 加载超过 3 秒必须展示明确状态文案；超过 8 秒必须提供重试、取消或返回入口。 - 请求失败后必须进入错误态，数据为空必须进入空态，不能让 loading 无限停留。 - 页面级异步状态应由 composable、Pinia 或 API SDK 统一管理；禁止在多个组件里散落重复的 `isLoading` 和手写请求状态。