workspace/code/fms/.qoder/repowiki/zh/content/UI组件库/UI组件库.md

UI组件库

**本文引用的文件** - [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)

目录

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-*。
  • 表格组件封装了虚拟滚动、行编辑、列拖拽、多选等能力；文件组件提供分类树、列表与预览三栏布局。

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
• App.vue:1-15
• app.js:1-123
• tokens.css:1-152

章节来源

• main.js:1-78
• App.vue:1-15
• app.js:1-123
• tokens.css:1-152

核心组件

• 按钮 Button：多视觉变体、禁用/加载态、块级按钮、原生类型控制，支持无障碍提示。
• 输入框 Input：多模式（默认/密码/数字/文本域）、清除、字数统计、前/后缀插槽、键盘与可访问性。
• 表单 Form：水平/垂直布局、网格列数、必填标记、校验时机、全量校验与提交/重置事件。
• 表格 FmsTable：虚拟滚动、列头拖拽、行拖拽排序、行多选、单元格编辑、主题跟随、区域选区编辑。
• 文件 FmsFile：分类树、文件列表、预览面板三栏布局，模块解析与错误处理。
• 弹窗 Modal：受控/非受控打开、全屏、拖拽、四边缩放、焦点陷阱、ESC/遮罩关闭。
• 下拉 Dropdown：多种触发方式、键盘导航、菜单项收集与逃生舱插槽。
• 选择器 Select：本地/远程筛选、自由输入、键盘导航、无障碍属性完善。

章节来源

• Button.vue:1-69
• Input.vue:1-370
• Form.vue:1-128
• FmsTable.vue:1-828
• FmsFile.vue:1-262
• Modal.vue:1-291
• Dropdown.vue:1-207
• Select.vue:1-526

架构总览

组件库采用“基础组件 + 业务组件”的分层设计：

• 基础组件聚焦通用交互与样式，通过 CSS 变量与主题系统保持一致性。
• 业务组件组合基础组件与第三方库（如 stk-table-vue），封装复杂场景（表格编辑、文件管理等）。
• 主题系统通过 Pinia Store 驱动 CSS 变量与 .dark 类切换，保证全局一致。

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
• tokens.css:1-152
• Button.vue:1-69
• Input.vue:1-370
• Form.vue:1-128
• Dropdown.vue:1-207
• Select.vue:1-526
• Modal.vue:1-291
• FmsTable.vue:1-828
• FmsFile.vue:1-262

详细组件分析

按钮 Button

• 设计目标：提供一致的视觉变体与交互状态，适配表单与工具栏场景。
• 关键特性：
  • 视觉变体：主色、次要、描边、幽灵、危险、链接。
  • 状态：禁用、加载（显示旋转图标）、块级宽度。
  • 无障碍：aria-busy 指示加载状态。
• 使用要点：
  • 通过 type 控制外观，htmlType 控制原生行为（button/submit/reset）。
  • 在表单中配合 Form 提交或独立操作。

章节来源

• Button.vue:1-69

输入框 Input

• 设计目标：统一的输入体验，支持多种输入模式与辅助功能。
• 关键特性：
  • 模式：默认、密码（可见性切换）、数字（输入规范化）、文本域（自动高度与拖拽调整）。
  • 交互：清除按钮、字数统计、前/后缀插槽。
  • 可访问性：aria-invalid、role、aria-label 等。
• 使用要点：
  • 数字模式会保留中间态（如小数点），失焦时提交为数值。
  • 文本域支持拖拽手柄与键盘调整高度。

章节来源

• Input.vue:1-370

表单 Form

• 设计目标：提供结构化表单布局与校验流程。
• 关键特性：
  • 布局：水平/垂直、网格列数、最大宽度限制。
  • 校验：表单级规则与字段级规则合并，支持 change/blur 触发时机。
  • 事件：submit、submitFailed、reset。
• 使用要点：
  • 通过 provide/inject 向子字段下发上下文，支持 validateAll 全量校验。
  • 重置时清空所有字段错误与触碰标记。

章节来源

• Form.vue:1-128

表格 FmsTable

• 设计目标：高性能数据展示与编辑，满足企业级表格需求。
• 关键特性：
  • 虚拟滚动：行数超过阈值启用，避免大列表卡顿。
  • 列头拖拽：支持列顺序调整，内置保护逻辑（选择列/序号列等不可拖拽）。
  • 行拖拽排序：开启后显示拖拽手柄，回传排序结果。
  • 行多选：在最前列插入复选框列，选中状态内聚管理。
  • 单元格编辑：根据列配置动态注入编辑器，支持区域选区编辑与键盘导航优化。
  • 主题：跟随应用深浅色模式，也可单独指定。
• 使用要点：
  • columns 配置 editor 即可启用编辑；editable 可整体开关。
  • 暴露方法：scrollToRow、editRow、getSelectedArea、clearSelectedArea、setRowExpand、initVirtualScroll。

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
• FmsTable.vue:557-597

章节来源

• FmsTable.vue:1-828

文件 FmsFile

• 设计目标：模块化文件管理，包含分类树、列表与预览。
• 关键特性：
  • 模块解析：根据 moduleCode 获取 moduleId，失败时显示错误信息。
  • 分类树：懒加载与展开状态管理。
  • 三栏布局：Splitter 分隔，左侧固定宽度，中间固定宽度，右侧自适应。
  • 预览：支持前后切换当前文件。
• 使用要点：
  • 暴露 moduleId 与 refreshCategories 方法。
  • 监听 uploaded/deleted/selected 事件以联动业务。

章节来源

• FmsFile.vue:1-262

弹窗 Modal

• 设计目标：提供可控、可访问、可拖拽缩放的对话框。
• 关键特性：
  • 受控/非受控：open/defaultOpen 两种模式。
  • 交互：ESC 关闭、遮罩点击关闭、右上角关闭按钮、确认/取消。
  • 拖拽与缩放：标题栏拖拽移动，四边手柄调整宽高，全屏模式互斥。
  • 可访问性：role="dialog"、aria-modal、焦点陷阱、标题关联。
• 使用要点：
  • confirmLoading 期间阻止关闭，避免异步流程被打断。
  • 打开时锁定滚动，关闭时恢复焦点。

章节来源

• Modal.vue:1-291

下拉 Dropdown

• 设计目标：灵活的菜单容器，支持多种触发方式与键盘导航。
• 关键特性：
  • 触发：click/hover/contextmenu。
  • 菜单来源：items 数组或默认插槽收集 ，或 #menu 逃生舱。
  • 键盘：上下移动、Home/End、Enter 选择，自动滚动到活动项。
• 使用要点：
  • 通过 provide 向子菜单传递选择与高亮状态。
  • 支持头部插槽用于头像/组织等富内容。

章节来源

• Dropdown.vue:1-207

选择器 Select

• 设计目标：强大的选项选择控件，支持本地/远程筛选与自由输入。
• 关键特性：
  • 筛选：本地默认匹配 label/value，或自定义 filterOption；远程模式触发 search 事件。
  • 自由输入：allowFreeInput 允许任意文本作为值。
  • 键盘：方向键导航、Enter 选择、Esc 取消。
  • 可访问性：role="combobox"/"listbox"、aria-expanded、aria-controls、aria-activedescendant。
• 使用要点：
  • options 为空时使用默认插槽自定义选项，透出 select/close 方法。
  • 打开时清空筛选词并定位到当前选中项。

章节来源

• Select.vue:1-526

依赖关系分析

• 构建与脚本：
  • 使用 Vite 进行开发与构建，Vitest 进行测试，Oxlint/Oxfmt 进行代码检查与格式化。
• 运行时依赖：
  • Vue 3、Vue Router、Pinia（含持久化插件）、Axios、Dayjs、Lucide 图标、stk-table-vue（表格内核）、SortableJS、vuedraggable。
• 组件间依赖：
  • 业务组件依赖基础组件与主题系统；表格依赖 stk-table-vue 并注册区域选择特性。

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
• main.js:1-78
• app.js:1-123
• tokens.css:1-152

章节来源

• package.json:1-48
• main.js:1-78

性能考量

• 表格虚拟滚动：
  • 行数超过阈值才启用虚拟滚动，减少初始渲染开销；ResizeObserver 防抖合并尺寸变化，避免动画期间频繁重排。
• 编辑器激活优化：
  • 键盘导航期间延迟激活编辑器，长按方向键全程保持零编辑器，松手后再激活最终行，避免每帧创建/销毁组件导致掉帧。
• 主题切换：
  • 通过 CSS 变量与 .dark 类切换，避免大量样式重绘；应用启动前同步主题，防止首屏闪烁。
• 输入框文本域：
  • 拖拽调整高度使用 requestAnimationFrame 合并更新，避免频繁重排。

[本节为通用性能讨论，不直接分析具体文件]

故障排查指南

• 应用启动失败：
  • 入口捕获异常并显示引导页错误信息与重试按钮，检查网络与路由就绪状态。
• 表格编辑卡顿：
  • 检查是否在大列表中频繁创建编辑器；确认已启用虚拟滚动与区域选区编辑；关注 ResizeObserver 防抖是否生效。
• 主题未生效：
  • 确认 Pinia Store 的 darkMode/primaryColor 已正确写入 DOM；检查 tokens.css 变量是否被覆盖。
• 弹窗焦点丢失：
  • 确认焦点陷阱与 ESC 关闭逻辑；检查是否在关闭时恢复了触发元素焦点。

章节来源

• main.js:24-78
• FmsTable.vue:56-96
• app.js:104-123
• Modal.vue:118-177

结论

本组件库以 CSS 变量为核心，结合 Pinia 状态管理，实现了统一的主题与深浅色模式；基础组件提供丰富的交互与可访问性支持，业务组件在此基础上封装复杂场景。通过虚拟滚动、编辑器激活优化与 ResizeObserver 防抖等手段，保证了大数据量下的流畅体验。建议在项目中优先使用这些组件以提升一致性、可维护性与用户体验。

[本节为总结，不直接分析具体文件]

附录

• 测试策略与质量保证：
  • 使用 Vitest 进行单元测试与集成测试，覆盖组件、服务、Store 与路由权限等。
  • 使用 Oxlint/Oxfmt 进行代码规范检查与格式化，保证团队一致性。
  • 针对表格虚拟滚动与权限路由等关键路径编写专项测试用例。

章节来源

• package.json:6-19
• tests/README.md