npm package: @skyfox2000/webui
Description: 后台前端通用组件定义, 支持国际化
Author: skyfox2000@github.com
Latest version: 1.6.47

# 微前端子应用基础库 (@skyfox2000/webui)

## 项目概述

这是一个专为微前端架构设计的企业级前端组件库，提供了完整的后台管理系统通用组件、工具函数、类型定义和业务逻辑封装。该组件库是微前端生态系统的核心基础设施，为各个子应用提供统一的UI组件、数据处理、状态管理和业务功能支持。

## 核心特性

### 🧩 丰富的组件体系

- **表单组件**：完整的表单控件集合，支持复杂表单场景
- **布局组件**：灵活的页面布局和导航组件
- **内容组件**：数据展示和交互组件
- **通用组件**：基础UI组件和工具组件
- **错误处理**：统一的错误展示和异常处理组件

### 🛠️ 强大的工具函数库

- **数据处理**：统一的数据查询、保存、删除等操作
- **表单验证**：完整的表单验证框架和规则引擎
- **文件处理**：文件上传、下载、Excel处理等功能
- **缓存管理**：前端缓存策略和数据管理
- **事件总线**：组件间通信和事件管理

### 📋 完整的类型定义

- **TypeScript支持**：完整的类型定义和智能提示
- **业务类型**：页面、表格、表单、树控件等业务类型
- **工具类型**：按钮、选项、菜单等工具类型
- **数据类型**：API接口、上传文件等数据类型

### 🔗 微前端集成

- **状态管理**：基于Pinia的状态管理解决方案
- **路由管理**：支持微前端的路由集成和导航
- **主应用通信**：与主应用的数据交互和API调用
- **图标管理**：动态图标加载和缓存机制

## 技术架构

### 核心技术栈

- **框架核心**：Vue 3.5 + TypeScript 5.8 + Vite 6.3
- **构建工具**：Vite + Rollup + ESBuild
- **样式方案**：TailwindCSS 3.4 + PostCSS
- **代码规范**：ESLint + Prettier
- **类型生成**：vue-tsc + vite-plugin-dts

### 依赖集成

- **微前端基础**：@skyfox2000/microbase ^1.2.1
- **API管理**：@skyfox2000/fapi ^1.1.19
- **UI组件库**：Ant Design Vue ^4.2.6
- **状态管理**：Pinia ^2.3.0 + 持久化插件
- **路由管理**：Vue Router ^4.5.1

### 扩展功能

- **代码编辑器**：ACE Editor + Vue3-ACE-Editor
- **Excel处理**：@vue-office/excel + exceljs
- **数据导出**：@json2csv/plainjs
- **表单验证**：async-validator
- **拖拽功能**：vue-draggable-next
- **消息提示**：vue-m-message

## 组件库架构

### 1. 表单组件模块 (`/form`)

**功能职责**：提供完整的表单控件和输入组件

- **基础输入组件**

   - `input`: 文本输入框组件，支持多种输入类型
   - `textarea`: 多行文本输入组件
   - `autoComplete`: 自动完成输入组件
   - `datePicker`: 日期选择器组件
   - `rangePicker`: 日期范围选择器组件

- **选择类组件**

   - `select`: 下拉选择组件，支持远程数据加载
   - `treeSelect`: 树形选择组件，支持层级数据
   - `cascader`: 级联选择器组件
   - `radio`: 单选按钮组件
   - `checkbox`: 复选框组件
   - `switch`: 开关组件
   - `transfer`: 穿梭框组件

- **高级组件**

   - `aceEditor`: 代码编辑器组件，支持语法高亮
   - `propEditor`: 属性编辑器组件，支持动态属性配置
   - `upload`: 文件上传组件，支持多种上传方式

### 2. 布局组件模块 (`/layout`)

**功能职责**：提供页面布局和导航相关组件

- **页面布局**

   - `page`: 标准页面布局组件
   - `content`: 内容区域布局组件
   - `header`: 页面头部组件
   - `breadcrumb`: 面包屑导航组件

- **导航组件**

   - `menu`: 菜单导航组件，支持多级菜单
   - `datetime`: 时间显示组件

### 3. 内容组件模块 (`/content`)

**功能职责**：提供数据展示和交互组件

- **数据展示组件**
   - 表格组件：支持分页、排序、筛选等功能
   - 搜索组件：多条件搜索和筛选
   - 工具栏组件：操作按钮和工具集合

### 4. 通用组件模块 (`/common`)

**功能职责**：提供基础UI组件和工具组件

- **基础组件**
   - 按钮组件：各种类型的操作按钮
   - 图标组件：图标显示和管理
   - 提示组件：工具提示和帮助信息

### 5. 错误处理模块 (`/error`)

**功能职责**：提供错误展示和异常处理组件

- **错误页面**
   - 404页面组件：页面未找到处理
   - 异常展示组件：系统异常和错误展示

## 工具函数库

### 数据处理工具

```typescript
// 统一的数据操作接口
export { doQuery, doExecute, doSave, doDelete } from '@/utils/data';

// 表格数据处理
export { gridQueryList, gridQueryFind, gridRowUpdate, gridStatusUpdate } from '@/utils/table';
```

### 表单验证工具

```typescript
// 表单验证框架
export { initValidate, formValidate, validateData, useInputFactory } from '@/utils/form-validate';

// Excel文件处理
export { validateExcel, processExcelFile } from '@/utils/form-excel';
```

### 文件处理工具

```typescript
// 文件上传下载
export { downloadBlob, donwloadFromMinio } from '@/utils/download';
export { AsyncUploader } from '@/utils/file-upload';

// 数据导出
export { exportSelectedRows, exportResults } from '@/utils/export-table';
```

### 缓存和状态管理

```typescript
// 缓存管理
export { CacheKeys, Cache, initCacheCheck } from '@/utils/cache';

// 状态管理
export { pinia } from '@/stores/pinia';

// 选项数据管理
export { loadOption, unloadOption, getSelectedValues } from '@/utils/options';
```

## 类型定义体系

### 核心业务类型

```typescript
// 页面控制类型
export type { PageControl, PageControlOption } from '@/typings/page.d';

// 表格控制类型
export type { GridControl, GridControlOption } from '@/typings/table.d';

// 表单控制类型
export type { EditorControl, EditorControlOption } from '@/typings/form.d';

// 树控件类型
export type { TreeControl, TreeControlOption, TreeNode } from '@/typings/tree.d';
```

### 工具和数据类型

```typescript
// 工具按钮类型
export type { ButtonTool, ButtonTools, IconTool } from '@/typings/tools.d';

// 文件上传类型
export type { UploadFile, MinioFile } from '@/typings/upload.d';

// 选项数据类型
export type { OptionItemProps, SelectValue } from '@/typings/option.d';
```

## 项目结构

```
@skyfox2000/webui/
├── src/
│   ├── assets/              # 静态资源
│   │   └── global.css      # 全局样式
│   ├── components/         # 组件库
│   │   ├── form/           # 表单组件
│   │   │   ├── input/      # 输入框组件
│   │   │   ├── select/     # 选择器组件
│   │   │   ├── upload/     # 上传组件
│   │   │   └── ...         # 其他表单组件
│   │   ├── layout/         # 布局组件
│   │   │   ├── page/       # 页面布局
│   │   │   ├── header/     # 页头组件
│   │   │   ├── menu/       # 菜单组件
│   │   │   └── ...         # 其他布局组件
│   │   ├── content/        # 内容组件
│   │   ├── common/         # 通用组件
│   │   ├── error/          # 错误处理组件
│   │   └── index.ts        # 组件导出
│   ├── utils/              # 工具函数
│   │   ├── data.ts         # 数据处理工具
│   │   ├── form-validate.ts # 表单验证工具
│   │   ├── table.ts        # 表格工具
│   │   ├── file-upload.ts  # 文件上传工具
│   │   └── ...             # 其他工具函数
│   ├── typings/            # 类型定义
│   │   ├── page.d.ts       # 页面类型
│   │   ├── form.d.ts       # 表单类型
│   │   ├── table.d.ts      # 表格类型
│   │   └── ...             # 其他类型定义
│   ├── stores/             # 状态管理
│   ├── router/             # 路由管理
│   ├── directives/         # 自定义指令
│   ├── const/              # 常量定义
│   └── index.ts            # 主入口文件
├── lib/                    # 构建输出
│   ├── webui.es.js         # ES模块
│   ├── webui.css           # 样式文件
│   ├── index.d.ts          # 类型声明
│   └── es/                 # 按需导入文件
├── package.json            # 项目配置
├── vite.config.ts          # Vite配置
├── tsconfig.json           # TypeScript配置
└── README.md               # 项目说明
```

## 安装使用

### 安装方式

```bash
npm install @skyfox2000/webui
# 或
pnpm add @skyfox2000/webui
```

### 基本使用

```typescript
// 完整导入
import { usePageFactory, useGridFactory, useEditorFactory, doQuery, formValidate } from '@skyfox2000/webui';

// 导入样式
import '@skyfox2000/webui/webui.css';

// 按需导入组件
import BasicLayout from '@skyfox2000/webui/es/BasicLayout';
```

### 页面工厂使用示例

```typescript
import { usePageFactory, useGridFactory } from '@skyfox2000/webui';

// 创建页面控制器
const pageControl = usePageFactory({
   apiUrls: {
      query: '/api/users/query',
      save: '/api/users/save',
      delete: '/api/users/delete',
   },
});

// 创建表格控制器
const gridControl = useGridFactory({
   columns: [
      { title: '用户名', dataIndex: 'username' },
      { title: '邮箱', dataIndex: 'email' },
      { title: '状态', dataIndex: 'status' },
   ],
});
```

## 构建和发布

### 本地开发构建

```bash
# 安装依赖
pnpm install

# 开发构建（链接WebBase库）
pnpm build:dev

# 生产构建
pnpm build

# 类型声明生成
pnpm build:types
```

### 包导出配置

```json
{
   "exports": {
      ".": {
         "types": "./lib/index.d.ts",
         "default": "./lib/webui.es.js"
      },
      "./webui.css": {
         "default": "./lib/webui.css"
      },
      "./es/*": {
         "import": "./lib/es/*/index.js",
         "types": "./lib/*.d.ts"
      }
   }
}
```

## 微前端集成

### 状态管理集成

```typescript
import { pinia } from '@skyfox2000/webui';
import { useAppInfo, useUserInfo } from '@skyfox2000/webui';

// 在主应用中使用
app.use(pinia);

// 获取应用信息
const appInfo = useAppInfo();
const userInfo = useUserInfo();
```

### 路由集成

```typescript
import { AppRouter, pendingNavigation } from '@skyfox2000/webui';

// 路由导航处理
if (pendingNavigation.value) {
   pendingNavigation.value.next();
}
```

### 主应用通信

```typescript
import { getHostInfo, getUserInfo, mainAppPush } from '@skyfox2000/webui';

// 获取主应用数据
const hostInfo = getHostInfo();
const userInfo = getUserInfo();

// 主应用路由跳转
mainAppPush('/target-path');
```

## 组件开发指南

### 新增组件

1. 在对应的组件目录下创建组件文件
2. 实现组件逻辑和样式
3. 在组件目录的 `index.ts`中导出组件
4. 在主 `index.ts`中添加组件导出
5. 更新类型定义文件

### 工具函数开发

1. 在 `utils`目录下创建工具函数文件
2. 实现工具函数逻辑
3. 在主 `index.ts`中导出工具函数
4. 添加相应的类型定义

### 类型定义规范

1. 在 `typings`目录下创建类型定义文件
2. 使用清晰的命名约定
3. 添加详细的注释说明
4. 在主 `index.ts`中导出类型

## 性能优化

### 构建优化

- **Tree Shaking**: 支持按需导入，减少包体积
- **代码分割**: 组件按需加载，提高加载速度
- **类型优化**: 独立的类型声明文件，提升开发体验
- **样式分离**: CSS文件独立打包，支持按需加载

### 运行时优化

- **缓存机制**: 智能的数据缓存和状态管理
- **懒加载**: 组件和资源的懒加载机制
- **防抖节流**: 内置的防抖节流处理
- **内存管理**: 组件销毁时的内存清理

## 版本历史

- **v1.2.6**: 当前版本，完整的组件库功能
- **v1.2.x**: 功能增强和性能优化
- **v1.1.x**: 基础组件库版本
- **v1.0.x**: 初始版本

## 注意事项

1. **依赖管理**: 确保peerDependencies的版本兼容性
2. **类型安全**: 充分利用TypeScript的类型检查
3. **样式隔离**: 注意组件样式的作用域和冲突
4. **性能监控**: 关注组件的渲染性能和内存使用
5. **版本升级**: 注意破坏性变更和迁移指南

## 技术支持

- **Vue 3 官方文档**: https://vuejs.org/
- **Ant Design Vue**: https://antdv.com/
- **Vite 构建工具**: https://vitejs.dev/
- **TypeScript**: https://www.typescriptlang.org/
- **Pinia 状态管理**: https://pinia.vuejs.org/

---

_该微前端子应用基础库是企业级微前端生态系统的核心基础设施，为各个子应用提供统一、高效、可扩展的前端解决方案。_