20260823210241
This commit is contained in:
oneao committed
1 parent
5ff4583aeb
commit
f4c7413dc6
2766 files changed
+1836409
-94689
No files matched your search
@@ -0,0 +1,337 @@
|
||||
# UI组件库
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [package.json](file://fms-vue/package.json)
|
||||
- [main.js](file://fms-vue/src/main.js)
|
||||
- [App.vue](file://fms-vue/src/App.vue)
|
||||
- [tokens.css](file://fms-vue/src/theme/tokens.css)
|
||||
- [app.js](file://fms-vue/src/stores/app.js)
|
||||
- [Button.vue](file://fms-vue/src/components/ui/button/Button.vue)
|
||||
- [Input.vue](file://fms-vue/src/components/ui/input/Input.vue)
|
||||
- [Form.vue](file://fms-vue/src/components/ui/form/Form.vue)
|
||||
- [FmsTable.vue](file://fms-vue/src/components/fms-table/FmsTable.vue)
|
||||
- [FmsFile.vue](file://fms-vue/src/components/fms-file/FmsFile.vue)
|
||||
- [Modal.vue](file://fms-vue/src/components/ui/modal/Modal.vue)
|
||||
- [Dropdown.vue](file://fms-vue/src/components/ui/dropdown/Dropdown.vue)
|
||||
- [Select.vue](file://fms-vue/src/components/ui/select/Select.vue)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本仓库提供基于 Vue 3 的 FMS 自定义 UI 组件库，覆盖基础表单控件（按钮、输入框、选择器、下拉菜单等）、布局与反馈类组件（弹窗、抽屉、消息通知、标签、分页、分割器等），以及业务级组件（表格、文件管理）。组件统一通过 CSS 变量实现主题定制，支持浅色/深色模式切换；同时提供可访问性（a11y）属性与键盘交互。文档将系统说明各组件的 API、事件、插槽、样式与主题能力，并给出使用示例与最佳实践建议。
|
||||
|
||||
## 项目结构
|
||||
- 应用入口与初始化：
|
||||
- 应用启动流程在入口文件中完成路由就绪、Pinia 初始化、主题同步与挂载，确保首屏无闪烁且菜单一次性渲染。
|
||||
- 主题与状态：
|
||||
- 设计令牌集中定义于 CSS 变量，深色模式通过 .dark 覆盖；主题状态由 Pinia Store 管理，并在应用启动时同步到 DOM。
|
||||
- 组件组织：
|
||||
- 基础 UI 组件位于 components/ui，业务组件位于 components/fms-*。
|
||||
- 表格组件封装了虚拟滚动、行编辑、列拖拽、多选等能力；文件组件提供分类树、列表与预览三栏布局。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["应用入口<br/>main.js"] --> B["根组件<br/>App.vue"]
|
||||
B --> C["路由视图<br/>router-view"]
|
||||
A --> D["主题同步<br/>stores/app.js"]
|
||||
D --> E["CSS 变量主题<br/>theme/tokens.css"]
|
||||
C --> F["基础组件<br/>components/ui/*"]
|
||||
C --> G["业务组件<br/>components/fms-*"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [main.js:1-78](file://fms-vue/src/main.js#L1-L78)
|
||||
- [App.vue:1-15](file://fms-vue/src/App.vue#L1-L15)
|
||||
- [app.js:1-123](file://fms-vue/src/stores/app.js#L1-L123)
|
||||
- [tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
|
||||
章节来源
|
||||
- [main.js:1-78](file://fms-vue/src/main.js#L1-L78)
|
||||
- [App.vue:1-15](file://fms-vue/src/App.vue#L1-L15)
|
||||
- [app.js:1-123](file://fms-vue/src/stores/app.js#L1-L123)
|
||||
- [tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
|
||||
## 核心组件
|
||||
- 按钮 Button：多视觉变体、禁用/加载态、块级按钮、原生类型控制，支持无障碍提示。
|
||||
- 输入框 Input：多模式（默认/密码/数字/文本域）、清除、字数统计、前/后缀插槽、键盘与可访问性。
|
||||
- 表单 Form：水平/垂直布局、网格列数、必填标记、校验时机、全量校验与提交/重置事件。
|
||||
- 表格 FmsTable：虚拟滚动、列头拖拽、行拖拽排序、行多选、单元格编辑、主题跟随、区域选区编辑。
|
||||
- 文件 FmsFile：分类树、文件列表、预览面板三栏布局，模块解析与错误处理。
|
||||
- 弹窗 Modal：受控/非受控打开、全屏、拖拽、四边缩放、焦点陷阱、ESC/遮罩关闭。
|
||||
- 下拉 Dropdown：多种触发方式、键盘导航、菜单项收集与逃生舱插槽。
|
||||
- 选择器 Select：本地/远程筛选、自由输入、键盘导航、无障碍属性完善。
|
||||
|
||||
章节来源
|
||||
- [Button.vue:1-69](file://fms-vue/src/components/ui/button/Button.vue#L1-L69)
|
||||
- [Input.vue:1-370](file://fms-vue/src/components/ui/input/Input.vue#L1-L370)
|
||||
- [Form.vue:1-128](file://fms-vue/src/components/ui/form/Form.vue#L1-L128)
|
||||
- [FmsTable.vue:1-828](file://fms-vue/src/components/fms-table/FmsTable.vue#L1-L828)
|
||||
- [FmsFile.vue:1-262](file://fms-vue/src/components/fms-file/FmsFile.vue#L1-L262)
|
||||
- [Modal.vue:1-291](file://fms-vue/src/components/ui/modal/Modal.vue#L1-L291)
|
||||
- [Dropdown.vue:1-207](file://fms-vue/src/components/ui/dropdown/Dropdown.vue#L1-L207)
|
||||
- [Select.vue:1-526](file://fms-vue/src/components/ui/select/Select.vue#L1-L526)
|
||||
|
||||
## 架构总览
|
||||
组件库采用“基础组件 + 业务组件”的分层设计：
|
||||
- 基础组件聚焦通用交互与样式，通过 CSS 变量与主题系统保持一致性。
|
||||
- 业务组件组合基础组件与第三方库（如 stk-table-vue），封装复杂场景（表格编辑、文件管理等）。
|
||||
- 主题系统通过 Pinia Store 驱动 CSS 变量与 .dark 类切换，保证全局一致。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "主题与状态"
|
||||
S["Pinia Store<br/>app.js"]
|
||||
T["CSS 变量<br/>tokens.css"]
|
||||
end
|
||||
subgraph "基础组件"
|
||||
B["Button"]
|
||||
I["Input"]
|
||||
Fm["Form"]
|
||||
Dr["Dropdown"]
|
||||
Se["Select"]
|
||||
M["Modal"]
|
||||
end
|
||||
subgraph "业务组件"
|
||||
Tbl["FmsTable"]
|
||||
File["FmsFile"]
|
||||
end
|
||||
S --> T
|
||||
B --> T
|
||||
I --> T
|
||||
Fm --> T
|
||||
Dr --> T
|
||||
Se --> T
|
||||
M --> T
|
||||
Tbl --> T
|
||||
File --> T
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [app.js:1-123](file://fms-vue/src/stores/app.js#L1-L123)
|
||||
- [tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
- [Button.vue:1-69](file://fms-vue/src/components/ui/button/Button.vue#L1-L69)
|
||||
- [Input.vue:1-370](file://fms-vue/src/components/ui/input/Input.vue#L1-L370)
|
||||
- [Form.vue:1-128](file://fms-vue/src/components/ui/form/Form.vue#L1-L128)
|
||||
- [Dropdown.vue:1-207](file://fms-vue/src/components/ui/dropdown/Dropdown.vue#L1-L207)
|
||||
- [Select.vue:1-526](file://fms-vue/src/components/ui/select/Select.vue#L1-L526)
|
||||
- [Modal.vue:1-291](file://fms-vue/src/components/ui/modal/Modal.vue#L1-L291)
|
||||
- [FmsTable.vue:1-828](file://fms-vue/src/components/fms-table/FmsTable.vue#L1-L828)
|
||||
- [FmsFile.vue:1-262](file://fms-vue/src/components/fms-file/FmsFile.vue#L1-L262)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 按钮 Button
|
||||
- 设计目标：提供一致的视觉变体与交互状态，适配表单与工具栏场景。
|
||||
- 关键特性：
|
||||
- 视觉变体：主色、次要、描边、幽灵、危险、链接。
|
||||
- 状态：禁用、加载（显示旋转图标）、块级宽度。
|
||||
- 无障碍：aria-busy 指示加载状态。
|
||||
- 使用要点：
|
||||
- 通过 type 控制外观，htmlType 控制原生行为（button/submit/reset）。
|
||||
- 在表单中配合 Form 提交或独立操作。
|
||||
|
||||
章节来源
|
||||
- [Button.vue:1-69](file://fms-vue/src/components/ui/button/Button.vue#L1-L69)
|
||||
|
||||
### 输入框 Input
|
||||
- 设计目标：统一的输入体验，支持多种输入模式与辅助功能。
|
||||
- 关键特性：
|
||||
- 模式：默认、密码（可见性切换）、数字（输入规范化）、文本域（自动高度与拖拽调整）。
|
||||
- 交互：清除按钮、字数统计、前/后缀插槽。
|
||||
- 可访问性：aria-invalid、role、aria-label 等。
|
||||
- 使用要点：
|
||||
- 数字模式会保留中间态（如小数点），失焦时提交为数值。
|
||||
- 文本域支持拖拽手柄与键盘调整高度。
|
||||
|
||||
章节来源
|
||||
- [Input.vue:1-370](file://fms-vue/src/components/ui/input/Input.vue#L1-L370)
|
||||
|
||||
### 表单 Form
|
||||
- 设计目标：提供结构化表单布局与校验流程。
|
||||
- 关键特性：
|
||||
- 布局：水平/垂直、网格列数、最大宽度限制。
|
||||
- 校验：表单级规则与字段级规则合并，支持 change/blur 触发时机。
|
||||
- 事件：submit、submitFailed、reset。
|
||||
- 使用要点：
|
||||
- 通过 provide/inject 向子字段下发上下文，支持 validateAll 全量校验。
|
||||
- 重置时清空所有字段错误与触碰标记。
|
||||
|
||||
章节来源
|
||||
- [Form.vue:1-128](file://fms-vue/src/components/ui/form/Form.vue#L1-L128)
|
||||
|
||||
### 表格 FmsTable
|
||||
- 设计目标：高性能数据展示与编辑，满足企业级表格需求。
|
||||
- 关键特性：
|
||||
- 虚拟滚动：行数超过阈值启用，避免大列表卡顿。
|
||||
- 列头拖拽：支持列顺序调整，内置保护逻辑（选择列/序号列等不可拖拽）。
|
||||
- 行拖拽排序：开启后显示拖拽手柄，回传排序结果。
|
||||
- 行多选：在最前列插入复选框列，选中状态内聚管理。
|
||||
- 单元格编辑：根据列配置动态注入编辑器，支持区域选区编辑与键盘导航优化。
|
||||
- 主题：跟随应用深浅色模式，也可单独指定。
|
||||
- 使用要点：
|
||||
- columns 配置 editor 即可启用编辑；editable 可整体开关。
|
||||
- 暴露方法：scrollToRow、editRow、getSelectedArea、clearSelectedArea、setRowExpand、initVirtualScroll。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as "用户"
|
||||
participant T as "FmsTable"
|
||||
participant K as "键盘/鼠标"
|
||||
participant V as "stk-table"
|
||||
U->>K : 方向键/点击
|
||||
K->>T : area-selection-change
|
||||
T->>T : 计算目标行/列
|
||||
T->>V : setCurrentRow(静默)
|
||||
T->>T : activateEditing(row, col)
|
||||
T-->>U : 编辑器渲染/焦点定位
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [FmsTable.vue:450-505](file://fms-vue/src/components/fms-table/FmsTable.vue#L450-L505)
|
||||
- [FmsTable.vue:557-597](file://fms-vue/src/components/fms-table/FmsTable.vue#L557-L597)
|
||||
|
||||
章节来源
|
||||
- [FmsTable.vue:1-828](file://fms-vue/src/components/fms-table/FmsTable.vue#L1-L828)
|
||||
|
||||
### 文件 FmsFile
|
||||
- 设计目标：模块化文件管理，包含分类树、列表与预览。
|
||||
- 关键特性：
|
||||
- 模块解析：根据 moduleCode 获取 moduleId，失败时显示错误信息。
|
||||
- 分类树：懒加载与展开状态管理。
|
||||
- 三栏布局：Splitter 分隔，左侧固定宽度，中间固定宽度，右侧自适应。
|
||||
- 预览：支持前后切换当前文件。
|
||||
- 使用要点：
|
||||
- 暴露 moduleId 与 refreshCategories 方法。
|
||||
- 监听 uploaded/deleted/selected 事件以联动业务。
|
||||
|
||||
章节来源
|
||||
- [FmsFile.vue:1-262](file://fms-vue/src/components/fms-file/FmsFile.vue#L1-L262)
|
||||
|
||||
### 弹窗 Modal
|
||||
- 设计目标：提供可控、可访问、可拖拽缩放的对话框。
|
||||
- 关键特性：
|
||||
- 受控/非受控：open/defaultOpen 两种模式。
|
||||
- 交互：ESC 关闭、遮罩点击关闭、右上角关闭按钮、确认/取消。
|
||||
- 拖拽与缩放：标题栏拖拽移动，四边手柄调整宽高，全屏模式互斥。
|
||||
- 可访问性：role="dialog"、aria-modal、焦点陷阱、标题关联。
|
||||
- 使用要点：
|
||||
- confirmLoading 期间阻止关闭，避免异步流程被打断。
|
||||
- 打开时锁定滚动，关闭时恢复焦点。
|
||||
|
||||
章节来源
|
||||
- [Modal.vue:1-291](file://fms-vue/src/components/ui/modal/Modal.vue#L1-L291)
|
||||
|
||||
### 下拉 Dropdown
|
||||
- 设计目标：灵活的菜单容器，支持多种触发方式与键盘导航。
|
||||
- 关键特性：
|
||||
- 触发：click/hover/contextmenu。
|
||||
- 菜单来源：items 数组或默认插槽收集 <DropdownItem>，或 #menu 逃生舱。
|
||||
- 键盘：上下移动、Home/End、Enter 选择，自动滚动到活动项。
|
||||
- 使用要点：
|
||||
- 通过 provide 向子菜单传递选择与高亮状态。
|
||||
- 支持头部插槽用于头像/组织等富内容。
|
||||
|
||||
章节来源
|
||||
- [Dropdown.vue:1-207](file://fms-vue/src/components/ui/dropdown/Dropdown.vue#L1-L207)
|
||||
|
||||
### 选择器 Select
|
||||
- 设计目标：强大的选项选择控件，支持本地/远程筛选与自由输入。
|
||||
- 关键特性：
|
||||
- 筛选：本地默认匹配 label/value，或自定义 filterOption；远程模式触发 search 事件。
|
||||
- 自由输入：allowFreeInput 允许任意文本作为值。
|
||||
- 键盘：方向键导航、Enter 选择、Esc 取消。
|
||||
- 可访问性：role="combobox"/"listbox"、aria-expanded、aria-controls、aria-activedescendant。
|
||||
- 使用要点：
|
||||
- options 为空时使用默认插槽自定义选项，透出 select/close 方法。
|
||||
- 打开时清空筛选词并定位到当前选中项。
|
||||
|
||||
章节来源
|
||||
- [Select.vue:1-526](file://fms-vue/src/components/ui/select/Select.vue#L1-L526)
|
||||
|
||||
## 依赖关系分析
|
||||
- 构建与脚本：
|
||||
- 使用 Vite 进行开发与构建，Vitest 进行测试，Oxlint/Oxfmt 进行代码检查与格式化。
|
||||
- 运行时依赖：
|
||||
- Vue 3、Vue Router、Pinia（含持久化插件）、Axios、Dayjs、Lucide 图标、stk-table-vue（表格内核）、SortableJS、vuedraggable。
|
||||
- 组件间依赖：
|
||||
- 业务组件依赖基础组件与主题系统；表格依赖 stk-table-vue 并注册区域选择特性。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
P["package.json<br/>脚本与依赖"]
|
||||
M["main.js<br/>应用初始化"]
|
||||
S["stores/app.js<br/>主题状态"]
|
||||
T["theme/tokens.css<br/>CSS 变量"]
|
||||
C1["ui/*<br/>基础组件"]
|
||||
C2["fms-*<br/>业务组件"]
|
||||
P --> M
|
||||
M --> S
|
||||
S --> T
|
||||
M --> C1
|
||||
M --> C2
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [package.json:1-48](file://fms-vue/package.json#L1-L48)
|
||||
- [main.js:1-78](file://fms-vue/src/main.js#L1-L78)
|
||||
- [app.js:1-123](file://fms-vue/src/stores/app.js#L1-L123)
|
||||
- [tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
|
||||
章节来源
|
||||
- [package.json:1-48](file://fms-vue/package.json#L1-L48)
|
||||
- [main.js:1-78](file://fms-vue/src/main.js#L1-L78)
|
||||
|
||||
## 性能考量
|
||||
- 表格虚拟滚动：
|
||||
- 行数超过阈值才启用虚拟滚动，减少初始渲染开销；ResizeObserver 防抖合并尺寸变化，避免动画期间频繁重排。
|
||||
- 编辑器激活优化：
|
||||
- 键盘导航期间延迟激活编辑器，长按方向键全程保持零编辑器，松手后再激活最终行，避免每帧创建/销毁组件导致掉帧。
|
||||
- 主题切换：
|
||||
- 通过 CSS 变量与 .dark 类切换，避免大量样式重绘；应用启动前同步主题，防止首屏闪烁。
|
||||
- 输入框文本域：
|
||||
- 拖拽调整高度使用 requestAnimationFrame 合并更新，避免频繁重排。
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 应用启动失败：
|
||||
- 入口捕获异常并显示引导页错误信息与重试按钮，检查网络与路由就绪状态。
|
||||
- 表格编辑卡顿：
|
||||
- 检查是否在大列表中频繁创建编辑器；确认已启用虚拟滚动与区域选区编辑；关注 ResizeObserver 防抖是否生效。
|
||||
- 主题未生效：
|
||||
- 确认 Pinia Store 的 darkMode/primaryColor 已正确写入 DOM；检查 tokens.css 变量是否被覆盖。
|
||||
- 弹窗焦点丢失：
|
||||
- 确认焦点陷阱与 ESC 关闭逻辑；检查是否在关闭时恢复了触发元素焦点。
|
||||
|
||||
章节来源
|
||||
- [main.js:24-78](file://fms-vue/src/main.js#L24-L78)
|
||||
- [FmsTable.vue:56-96](file://fms-vue/src/components/fms-table/FmsTable.vue#L56-L96)
|
||||
- [app.js:104-123](file://fms-vue/src/stores/app.js#L104-L123)
|
||||
- [Modal.vue:118-177](file://fms-vue/src/components/ui/modal/Modal.vue#L118-L177)
|
||||
|
||||
## 结论
|
||||
本组件库以 CSS 变量为核心，结合 Pinia 状态管理，实现了统一的主题与深浅色模式；基础组件提供丰富的交互与可访问性支持，业务组件在此基础上封装复杂场景。通过虚拟滚动、编辑器激活优化与 ResizeObserver 防抖等手段，保证了大数据量下的流畅体验。建议在项目中优先使用这些组件以提升一致性、可维护性与用户体验。
|
||||
|
||||
[本节为总结，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
- 测试策略与质量保证：
|
||||
- 使用 Vitest 进行单元测试与集成测试，覆盖组件、服务、Store 与路由权限等。
|
||||
- 使用 Oxlint/Oxfmt 进行代码规范检查与格式化，保证团队一致性。
|
||||
- 针对表格虚拟滚动与权限路由等关键路径编写专项测试用例。
|
||||
|
||||
章节来源
|
||||
- [package.json:6-19](file://fms-vue/package.json#L6-L19)
|
||||
- [tests/README.md](file://fms-vue/tests/README.md)
|
||||
Reference in new issue
Block a user