xmirror-components 1.0.30-alpha.5 → 1.0.30-alpha.7

package/README.md

@@ -1,266 +1,291 @@
 # XMirror Components
 
-一个基于 React 和 Ant Design 的高质量组件库，提供了一系列实用的 UI 组件和 Hooks，帮助开发者快速构建现代化的 Web 应用。
+一个基于 React + TypeScript + Ant Design 的现代化组件库，提供高质量、可复用的 UI 组件和 Hooks。
 
-## ✨ 特性
+## 🚀 特性
 
-- 🚀 **基于 Ant Design 5.x** - 继承 Ant Design 的设计语言和交互体验
-- 📦 **开箱即用** - 提供常用的业务组件和工具函数
-- 🎯 **TypeScript 支持** - 完整的 TypeScript 类型定义
-- 🔧 **高度可定制** - 支持主题定制和样式覆盖
-- 📱 **响应式设计** - 适配各种屏幕尺寸
-- 🎨 **现代化 UI** - 符合当前设计趋势的组件样式
+- **TypeScript 支持**: 完整的类型定义和类型安全
+- **现代化架构**: 基于 React 18+ 和最新的前端技术栈
+- **Ant Design 集成**: 与 Ant Design 5.x 完美集成
+- **高性能**: 优化的渲染性能和内存管理
+- **可扩展**: 模块化设计，易于扩展和定制
+- **国际化**: 内置多语言支持
 
 ## 📦 安装
 
 ```bash
 npm install xmirror-components
-# 或
-yarn add xmirror-components
-# 或
-pnpm add xmirror-components
 ```
 
 ## 🔧 依赖要求
 
-- React >= 16.9.0
-- React DOM >= 16.9.0
-- Ant Design >= 5.0.0
-
-## 🚀 快速开始
-
-### 1. 引入组件
-
-```tsx
-import { App, CheckboxValue, SwitchValue, IconFont, IconButton, useRequest } from 'xmirror-components';
+```json
+{
+  "peerDependencies": {
+    "antd": ">=5.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "@ant-design/icons": ">=5.0.0",
+    "ahooks": ">=3.0.0",
+    "lodash-es": ">=4.17.0",
+    "react-intl": ">=7.0.0",
+    "react-transition-group": ">=4.4.0"
+  }
+}
 ```
 
-### 2. 使用 App 组件包装应用
+## 🎯 核心组件
 
-```tsx
-import React from 'react';
-import { App } from 'xmirror-components';
-
-function MyApp() {
-  return (
-    <App>
-      <YourAppContent />
-    </App>
-  );
-}
-```
+### AntdApp
+Ant Design 应用的根组件，提供全局配置和主题支持。
 
-## 📚 组件文档
+### ConfigProvider
+配置提供者，用于设置国际化、主题等全局配置。
 
-### App 组件
+### Table
+功能强大的表格组件，支持排序、筛选、分页、列设置等功能。
 
-Ant Design 5.x 的 App 组件封装，提供全局的 message、notification、modal 等静态方法。
+### SearchArea
+搜索区域组件，提供灵活的搜索和筛选功能。
 
-```tsx
-import { App, message, notification, modal } from 'xmirror-components';
+### GlobalLoading
+全局加载状态管理组件。
 
-function MyComponent() {
-  const handleClick = () => {
-    message.success('操作成功！');
-    notification.info('这是一条通知');
-    modal.confirm({
-      title: '确认删除',
-      content: '确定要删除这条记录吗？',
-    });
-  };
+### IconButton
+图标按钮组件，支持多种图标类型。
 
-  return (
-    <App>
-      <button onClick={handleClick}>显示消息</button>
-    </App>
-  );
-}
-```
+### IconFont
+图标字体组件，支持自定义图标。
 
-### CheckboxValue 组件
+### SwitchValue
+开关值组件，用于布尔值的切换。
 
-支持自定义选中/未选中值的复选框组件。
+### CheckboxValue
+复选框值组件，用于多选值的管理。
 
-```tsx
-import { CheckboxValue } from 'xmirror-components';
+## 🪝 核心 Hooks
 
-function MyForm() {
-  const [status, setStatus] = useState('Y');
+### useTable
 
-  return (
-    <CheckboxValue
-      checked={status}
-      trueValue="Y"
-      falseValue="N"
-      trueLabel="已启用"
-      falseLabel="未启用"
-      onChange={(value) => setStatus(value)}
-    />
-  );
-}
-```
+一个功能强大的表格数据管理 Hook，提供完整的数据获取、分页、排序、筛选、多选等功能。
 
-**Props:**
+#### 特性
 
-| 参数 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| checked | 当前选中值 | any | - |
-| onChange | 变化时回调 | (value, event) => void | - |
-| trueValue | 选中时的值 | any | true |
-| falseValue | 未选中时的值 | any | false |
-| trueLabel | 选中时显示的文本 | string | '' |
-| falseLabel | 未选中时显示的文本 | string | '' |
+- **类型安全**: 完整的 TypeScript 泛型支持
+- **数据管理**: 自动处理数据获取、缓存和更新
+- **分页支持**: 内置分页逻辑和状态管理
+- **排序筛选**: 支持列排序和条件筛选
+- **多选支持**: 支持行选择和跨页选择
+- **定时刷新**: 可配置的定时数据刷新
+- **错误处理**: 完善的错误处理和用户提示
+- **性能优化**: 使用 useMemoizedFn 和 useCallback 优化性能
 
-### SwitchValue 组件
+#### 基本用法
 
-支持自定义开关值的开关组件。
+```typescript
+import { useTable } from 'xmirror-components/hooks/useTable'
 
-```tsx
-import { SwitchValue } from 'xmirror-components';
+interface User {
+  id: number
+  name: string
+  email: string
+  status: 'active' | 'inactive'
+}
 
-function MyComponent() {
-  const [enabled, setEnabled] = useState(1);
+function UserTable() {
+  const { tableProps, search, rowSelection } = useTable<User>(
+    // 请求函数
+    async (params) => {
+      const response = await fetchUsers(params)
+      return {
+        records: response.data,
+        total: response.total,
+        current: response.current,
+        size: response.pageSize
+      }
+    },
+    // 配置选项
+    {
+      rowKey: 'id',
+      immediate: true,
+      showRowSelection: true,
+      defaultPagination: {
+        current: 1,
+        pageSize: 20
+      }
+    }
+  )
 
   return (
-    <SwitchValue
-      checked={enabled}
-      trueValue={1}
-      falseValue={0}
-      onChange={(value) => setEnabled(value)}
+    <Table
+      {...tableProps}
+      columns={[
+        { title: 'ID', dataIndex: 'id', key: 'id' },
+        { title: '姓名', dataIndex: 'name', key: 'name' },
+        { title: '邮箱', dataIndex: 'email', key: 'email' },
+        { title: '状态', dataIndex: 'status', key: 'status' }
+      ]}
     />
-  );
+  )
 }
 ```
 
-### IconFont 组件
+#### 高级用法
+
+```typescript
+const { tableProps, search, rowSelection } = useTable<User>(
+  fetchUsers,
+  {
+    rowKey: 'id',
+    interval: 30000, // 30秒自动刷新
+    multiPageSelection: true, // 支持跨页选择
+    onBeforeRequest: async (params) => {
+      // 请求前处理
+      console.log('请求参数:', params)
+      return params
+    },
+    onAfterRequest: async (response) => {
+      // 响应后处理
+      console.log('响应数据:', response)
+      return response.records
+    }
+  }
+)
+```
 
-图标字体组件，支持 symbol 模式和普通模式。
+#### API 参考
 
-```tsx
-import { IconFont } from 'xmirror-components';
+##### OptionsProps<T>
 
-function MyComponent() {
-  return (
-    <div>
-      {/* 普通模式 */}
-      <IconFont type="icon-user" />
-      
-      {/* Symbol 模式 */}
-      <IconFont type="icon-home" symbol />
-    </div>
-  );
-}
-```
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rowKey` | `keyof T \| string` | `'id'` | 行数据的唯一标识字段 |
+| `interval` | `false \| number` | `false` | 定时刷新间隔（毫秒） |
+| `immediate` | `boolean` | `true` | 是否立即执行首次请求 |
+| `defaultPagination` | `object` | `{current: 1, pageSize: 10}` | 默认分页配置 |
+| `showRowSelection` | `boolean` | `false` | 是否显示行选择 |
+| `multiPageSelection` | `boolean` | `false` | 是否支持跨页选择 |
+| `onBeforeRequest` | `function` | - | 请求前回调函数 |
+| `onAfterRequest` | `function` | - | 响应后回调函数 |
 
-### IconButton 组件
+##### ReturnData<T>
 
-图标按钮组件，提供更好的交互体验。
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `loading` | `boolean` | 加载状态 |
+| `tableProps` | `object` | 表格组件的 props |
+| `search` | `object` | 搜索相关功能 |
+| `rowSelection` | `object` | 行选择相关功能 |
 
-```tsx
-import { IconButton } from 'xmirror-components';
+#### 搜索和筛选
 
-function MyComponent() {
-  return (
-    <IconButton
-      icon="icon-edit"
-      onClick={() => console.log('编辑')}
-      tooltip="编辑"
-    />
-  );
-}
-```
+```typescript
+// 提交搜索
+search.submit({ status: 'active', keyword: 'john' })
+
+// 刷新数据
+search.refresh()
 
-### GlobalLoading 组件
+// 获取当前搜索参数
+console.log(search.params)
 
-全局加载组件，用于页面级别的加载状态。
+// 获取分页信息
+console.log(search.pagination)
+```
 
-```tsx
-import { GlobalLoading } from 'xmirror-components';
+#### 行选择
 
-function MyComponent() {
-  const [loading, setLoading] = useState(false);
+```typescript
+// 获取选中的行
+console.log(rowSelection.selectedRows)
 
-  return (
-    <GlobalLoading loading={loading}>
-      <YourContent />
-    </GlobalLoading>
-  );
-}
+// 获取选中的行键
+console.log(rowSelection.selectedRowKeys)
 ```
 
-## 🎣 Hooks
-
 ### useRequest
 
-基于 ahooks 的 useRequest 封装，提供统一的错误处理和数据处理。
+基于 ahooks 的请求管理 Hook，提供请求状态管理和缓存功能。
 
-```tsx
-import { useRequest } from 'xmirror-components';
-
-function MyComponent() {
-  const { data, loading, run } = useRequest(
-    async (params) => {
-      const response = await fetch('/api/data', { params });
-      return response.json();
-    },
-    {
-      manual: true,
-      errorMessage: true, // 自动显示错误信息
-    }
-  );
+## 🎨 样式系统
 
-  return (
-    <div>
-      <button onClick={() => run({ page: 1 })} disabled={loading}>
-        {loading ? '加载中...' : '获取数据'}
-      </button>
-      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
-    </div>
-  );
-}
-```
+组件库使用 CSS-in-JS 方案，支持主题定制和样式覆盖。
 
-## 🎨 主题定制
+## 🌍 国际化
 
-组件库支持通过 CSS 变量进行主题定制：
+内置国际化支持，使用 react-intl 实现多语言切换。
 
-```css
-:root {
-  --primary-color: #1890ff;
-}
-```
+## 📚 开发指南
 
 ### 项目结构
 
 ```
 src/
 ├── components/          # 组件目录
-│   ├── AntdApp/        # App 组件
-│   ├── CheckboxValue/  # 复选框组件
-│   ├── SwitchValue/    # 开关组件
-│   ├── IconFont/       # 图标组件
-│   ├── IconButton/     # 图标按钮组件
-│   └── GlobalLoading/  # 全局加载组件
+│   ├── AntdApp/        # 应用根组件
+│   ├── ConfigProvider/ # 配置提供者
+│   ├── Table/          # 表格组件
+│   ├── SearchArea/     # 搜索区域
+│   └── ...            # 其他组件
 ├── hooks/              # Hooks 目录
-│   └── useRequest/     # 请求 Hook
-└── index.ts           # 入口文件
+│   ├── useTable/       # 表格数据管理 Hook
+│   └── useRequest/     # 请求管理 Hook
+└── index.ts            # 主入口文件
 ```
 
-## 🤝 贡献指南
+### 开发环境
 
-我们欢迎所有形式的贡献，包括但不限于：
+```bash
+# 安装依赖
+npm install
 
-- 🐛 Bug 报告
-- 💡 新功能建议
-- 📝 文档改进
-- 🔧 代码贡献
+# 启动开发服务器
+npm run dev
+
+# 构建项目
+npm run build
+
+# 代码检查
+npm run lint
+```
+
+### 添加新组件
+
+1. 在 `src/components/` 目录下创建组件目录
+2. 实现组件逻辑和类型定义
+3. 在 `src/index.ts` 中导出组件
+4. 更新文档和示例
+
+### 添加新 Hook
+
+1. 在 `src/hooks/` 目录下创建 Hook 目录
+2. 实现 Hook 逻辑和类型定义
+3. 在 `src/index.ts` 中导出 Hook
+4. 更新文档和示例
+
+## 🤝 贡献指南
+
+我们欢迎所有形式的贡献！请查看 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解详情。
 
 ## 📄 许可证
 
-本项目基于 [MIT](LICENSE) 许可证开源。
+本项目采用 MIT 许可证 - 查看 [LICENSE](./LICENSE) 文件了解详情。
+
+## 🔗 相关链接
+
+- [React 官方文档](https://react.dev/)
+- [Ant Design 官方文档](https://ant.design/)
+- [TypeScript 官方文档](https://www.typescriptlang.org/)
+- [Vite 官方文档](https://vitejs.dev/)
+
+## 📞 联系我们
+
+如有问题或建议，请通过以下方式联系我们：
+
+- 提交 Issue: [GitHub Issues](https://github.com/your-org/xmirror-components/issues)
+- 提交 PR: [GitHub Pull Requests](https://github.com/your-org/xmirror-components/pulls)
+- 邮箱: your-email@example.com
 
-## 🙏 致谢
+---
 
-- [Ant Design](https://ant.design/) - 优秀的 React UI 组件库
-- [ahooks](https://ahooks.js.org/) - 实用的 React Hooks 库
-- [React](https://reactjs.org/) - 用于构建用户界面的 JavaScript 库
+**XMirror Components** - 让前端开发更简单、更高效！ 🚀