# 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)