@skyfox2000/webui 1.2.6 → 1.2.8

package/README.md

@@ -1,104 +1,454 @@
+# 微前端子应用基础库 (@skyfox2000/webui)
 
+## 项目概述
 
-## 系统管理平台
+这是一个专为微前端架构设计的企业级前端组件库，提供了完整的后台管理系统通用组件、工具函数、类型定义和业务逻辑封装。该组件库是微前端生态系统的核心基础设施，为各个子应用提供统一的UI组件、数据处理、状态管理和业务功能支持。
 
-### 安装使用步骤
+## 核心特性
 
-- **Install：**
+### 🧩 丰富的组件体系
 
-```text
-pnpm install
+- **表单组件**：完整的表单控件集合，支持复杂表单场景
+- **布局组件**：灵活的页面布局和导航组件
+- **内容组件**：数据展示和交互组件
+- **通用组件**：基础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';
 ```
 
-- **Build：**
+### 表单验证工具
 
-```text
-pnpm build
+```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';
+```
 
 ## 项目结构
 
-### 文件资源目录 📚
-项目采用了标准化的目录结构，便于组织代码和资源。以下是主要目录的详细说明：
-
-```
-Component/
-├── lib/               # 构建输出目录
-├── node_modules/       # 依赖包目录
-├── plugins/            # Vite插件定制目录
-├── src/                # 源代码目录
-│   ├── components/     # 公共组件目录
-│   └── vite-env.d.ts   # Vite环境类型定义
-├── package.json        # 项目依赖和脚本
-├── pnpm-lock.yaml      # 依赖锁定文件
-├── postcss.config.ts   # PostCSS配置
-├── tailwind.config.ts  # Tailwind CSS配置
-├── tsconfig.json       # TypeScript配置
-└── vite.config.ts      # Vite配置
-```
-
-## 源代码结构详解
-
-### 组件目录
-
-src/components/ 目录包含所有公共组件，每个组件都是独立的功能单元：
-
-```
-components/
-├── common/         # 通用基础组件
-│   ├── button/        # 按钮组件
-│   ├── icon/          # 图标组件
-│   ├── tooltip/       # 提示组件
-│   └── ...
-├── content/        # 内容相关组件
-│   ├── grid/          # 表格组件
-│   ├── search/        # 搜索组件
-│   ├── toolbar/       # 工具栏组件
-│   └── ...
-├── error/          # 错误处理组件
-│   ├── notFound/      # 404页面组件
-│   ├── exception/     # 异常展示组件
-│   └── ...
-├── form/           # 表单相关组件
-│   ├── aceEditor/     # ACE编辑器组件
-│   ├── datePicker/    # 日期选择组件
-│   ├── input/         # 输入框组件
-│   ├── propEditor/    # 属性编辑器组件
-│   ├── select/        # 下拉选择组件
-│   ├── switch/        # 开关组件
-│   ├── treeSelect/    # 树形选择组件
-│   └── ...
-├── layout/         # 布局组件
-│   ├── content/       # 内容布局组件
-│   ├── footer/        # 页脚组件
-│   ├── header/        # 页头组件
-│   ├── sidebar/       # 侧边栏组件
-│   └── ...
-└── index.ts        # 组件导出
-```
-
-### 开发环境 🔨
-
-- 使用 Vue3.5 + TypeScript 5.7 + Vite6 开发
-- UI组件: Ant-Design-Vue 4.2
-- CSS处理器: Tailwindcss 3.4
-- 状态管理: Pinia 2.3
-- 路由管理: VueRouter 4.5
-- API管理: @skyfox2000/fapi 1.1
-- 前端控制底座: @skyfox2000/webbase 1.0
-- 时间处理: dayjs 
-- Node环境: v18.16.0
-
-### Git commit ⻛格指南
-
-- feat: 增加新功能
-- fix: 修复问题
-- style: 代码⻛格相关⽆影响运⾏结果的
-- perf: 优化/性能提升
-- refactor: 重构
-- revert: 撤销修改
-- test: 测试相关
-- docs: ⽂档/注释
-- chore: 依赖更新/脚⼿架配置修改等
-- ci: 持续集成
+```
+@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/
+
+---
+
+_该微前端子应用基础库是企业级微前端生态系统的核心基础设施，为各个子应用提供统一、高效、可扩展的前端解决方案。_