xmirror-components 1.0.30-alpha.8 → 1.0.30

package/README.md

@@ -37,31 +37,627 @@ npm install xmirror-components
 ## 🎯 核心组件
 
 ### AntdApp
-Ant Design 应用的根组件，提供全局配置和主题支持。
+
+Ant Design 应用的根组件，提供全局配置和主题支持。集成了全局加载状态管理和配置提供者功能。
+
+#### 特性
+- **全局状态管理**: 集成 message、notification、modal 等全局方法
+- **配置支持**: 内置 ConfigProvider 配置支持
+- **加载状态**: 集成 GlobalLoading 全局加载状态
+- **类型安全**: 完整的 TypeScript 类型支持
+
+#### 基本用法
+
+```typescript
+import { App, message, notification, modal } from 'xmirror-components'
+
+function MyApp() {
+  return (
+    <App
+      config={{
+        iconButton: {
+          size: 'small',
+          style: { color: '#1890ff' }
+        },
+        iconFont: {
+          className: 'my-iconfont'
+        }
+      }}
+    >
+      <div>你的应用内容</div>
+    </App>
+  )
+}
+
+// 使用全局方法
+const handleClick = () => {
+  message.success('操作成功')
+  notification.info({
+    message: '通知',
+    description: '这是一个通知消息'
+  })
+  modal.confirm({
+    title: '确认',
+    content: '确定要执行此操作吗？',
+    onOk: () => console.log('确认')
+  })
+}
+```
+
+#### API 参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `config` | `ConfigProviderConfigProps` | - | 全局配置选项 |
+| `children` | `React.ReactNode` | - | 子组件 |
 
 ### ConfigProvider
-配置提供者，用于设置国际化、主题等全局配置。
+
+配置提供者，用于设置国际化、主题等全局配置。支持组件级别的配置覆盖。
+
+#### 特性
+- **递归合并**: 支持配置的深度合并
+- **类型安全**: 完整的 TypeScript 类型定义
+- **组件配置**: 支持 IconButton、IconFont 等组件的全局配置
+
+#### 基本用法
+
+```typescript
+import { ConfigProvider } from 'xmirror-components'
+
+function App() {
+  return (
+    <ConfigProvider
+      config={{
+        iconButton: {
+          size: 'middle',
+          style: { 
+            color: '#1890ff',
+            borderRadius: '4px'
+          },
+          className: 'custom-icon-button'
+        },
+        iconFont: {
+          className: 'my-iconfont',
+          style: { fontSize: '16px' }
+        }
+      }}
+    >
+      <div>你的应用内容</div>
+    </ConfigProvider>
+  )
+}
+```
+
+#### API 参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `config` | `ConfigProviderConfigProps` | - | 配置对象 |
+
+##### ConfigProviderConfigProps
+
+```typescript
+interface ConfigProviderConfigProps {
+  iconButton?: {
+    size?: 'small' | 'middle' | 'large'
+    style?: React.CSSProperties
+    className?: string
+    render?: (props: any) => React.ReactNode
+  }
+  iconFont?: {
+    className?: string
+    style?: React.CSSProperties
+  }
+}
+```
 
 ### Table
-功能强大的表格组件，支持排序、筛选、分页、列设置等功能。
+
+功能强大的表格组件，支持排序、筛选、分页、列设置、列宽调整等功能。
+
+#### 特性
+- **列管理**: 支持列的显示/隐藏、排序、宽度调整
+- **本地存储**: 自动保存用户的列配置到本地存储
+- **响应式**: 支持响应式布局和滚动
+- **可扩展**: 支持自定义渲染和样式
+- **类型安全**: 完整的 TypeScript 泛型支持
+
+#### 基本用法
+
+```typescript
+import { Table } from 'xmirror-components'
+
+function UserTable() {
+  const columns = [
+    {
+      title: '姓名',
+      dataIndex: 'name',
+      key: 'name',
+      sorter: true,
+      filters: [
+        { text: '张三', value: 'zhangsan' },
+        { text: '李四', value: 'lisi' }
+      ]
+    },
+    {
+      title: '年龄',
+      dataIndex: 'age',
+      key: 'age',
+      sorter: true
+    },
+    {
+      title: '邮箱',
+      dataIndex: 'email',
+      key: 'email',
+      ellipsis: true
+    }
+  ]
+
+  const dataSource = [
+    { id: 1, name: '张三', age: 25, email: 'zhangsan@example.com' },
+    { id: 2, name: '李四', age: 30, email: 'lisi@example.com' }
+  ]
+
+  return (
+    <Table
+      columns={columns}
+      dataSource={dataSource}
+      rowKey="id"
+      pagination={{
+        current: 1,
+        pageSize: 10,
+        total: 100
+      }}
+      columnsSort={true}
+      columnsVisible={true}
+      columnsResizable={true}
+      tableId="user-table"
+    />
+  )
+}
+```
+
+#### 高级用法
+
+```typescript
+// 自定义列渲染
+const columns = [
+  {
+    title: '状态',
+    dataIndex: 'status',
+    key: 'status',
+    render: (status: string) => (
+      <Tag color={status === 'active' ? 'green' : 'red'}>
+        {status === 'active' ? '激活' : '禁用'}
+      </Tag>
+    )
+  },
+  {
+    title: '操作',
+    key: 'action',
+    render: (_, record) => (
+      <Space>
+        <IconButton icon="edit" onClick={() => handleEdit(record)} />
+        <IconButton icon="delete" onClick={() => handleDelete(record)} />
+      </Space>
+    )
+  }
+]
+
+// 使用本地存储的列配置
+<Table
+  columns={columns}
+  dataSource={dataSource}
+  columnsSort={true}        // 启用列排序
+  columnsVisible={true}     // 启用列显示/隐藏
+  columnsResizable={true}   // 启用列宽调整
+  tableId="unique-table-id" // 唯一标识，用于本地存储
+/>
+```
+
+#### API 参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `columns` | `ColumnType[]` | `[]` | 表格列配置 |
+| `dataSource` | `any[]` | `[]` | 数据源 |
+| `columnsSort` | `boolean` | `false` | 是否启用列排序 |
+| `columnsVisible` | `boolean` | `false` | 是否启用列显示/隐藏 |
+| `columnsResizable` | `boolean` | `false` | 是否启用列宽调整 |
+| `tableId` | `string` | `''` | 表格唯一标识，用于本地存储 |
 
 ### SearchArea
-搜索区域组件，提供灵活的搜索和筛选功能。
+
+搜索区域组件，提供灵活的搜索和筛选功能。支持展开/收起动画和自定义布局。
+
+#### 特性
+- **动画效果**: 平滑的展开/收起动画
+- **响应式布局**: 支持多种屏幕尺寸的响应式布局
+- **自定义配置**: 支持自定义列布局和样式
+- **Hook支持**: 提供 useSearchArea Hook 进行状态管理
+
+#### 基本用法
+
+```typescript
+import { SearchArea } from 'xmirror-components'
+
+function SearchForm() {
+  const handleSearch = (values: any) => {
+    console.log('搜索参数:', values)
+  }
+
+  const handleReset = () => {
+    console.log('重置搜索')
+  }
+
+  return (
+    <SearchArea
+      onSearch={handleSearch}
+      onReset={handleReset}
+      loading={false}
+    >
+      <SearchArea.Item name="name" label="姓名">
+        <Input placeholder="请输入姓名" />
+      </SearchArea.Item>
+      <SearchArea.Item name="status" label="状态">
+        <Select placeholder="请选择状态">
+          <Option value="active">激活</Option>
+          <Option value="inactive">禁用</Option>
+        </Select>
+      </SearchArea.Item>
+    </SearchArea>
+  )
+}
+```
+
+#### 使用 Hook 管理状态
+
+```typescript
+import { SearchArea } from 'xmirror-components'
+
+function AdvancedSearch() {
+  const searchArea = SearchArea.useSearchArea(false) // 默认收起
+
+  return (
+    <div>
+      <SearchArea.ToggleButton
+        onClick={searchArea.toggle}
+        show={searchArea.show}
+      >
+        高级搜索
+      </SearchArea.ToggleButton>
+      
+      <SearchArea
+        instance={searchArea}
+        onSearch={handleSearch}
+      >
+        {/* 搜索表单项 */}
+      </SearchArea>
+    </div>
+  )
+}
+```
+
+#### API 参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `onSearch` | `(data: any) => void` | - | 搜索回调函数 |
+| `onReset` | `() => void` | - | 重置回调函数 |
+| `onClose` | `() => void` | - | 收起回调函数 |
+| `loading` | `boolean` | `false` | 加载状态 |
+| `instance` | `SearchAreaHooks` | - | 外部状态管理实例 |
+| `col` | `ColProps` | `{}` | 列配置 |
+| `row` | `RowProps` | `{}` | 行配置 |
 
 ### GlobalLoading
-全局加载状态管理组件。
+
+全局加载状态管理组件，提供美观的加载动画和全局状态控制。
+
+#### 特性
+- **动画效果**: 流畅的进入/退出动画
+- **全局控制**: 通过 setGlobalLoading 函数全局控制
+- **美观设计**: 现代化的加载动画效果
+- **高性能**: 使用 CSSTransition 优化性能
+
+#### 基本用法
+
+```typescript
+import { GlobalLoading, setGlobalLoading } from 'xmirror-components'
+
+function App() {
+  const handleAsyncOperation = async () => {
+    setGlobalLoading(true)
+    try {
+      await fetchData()
+    } finally {
+      setGlobalLoading(false)
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={handleAsyncOperation}>
+        执行异步操作
+      </button>
+      <GlobalLoading />
+    </div>
+  )
+}
+```
+
+#### 在 AntdApp 中使用
+
+```typescript
+import { App, setGlobalLoading } from 'xmirror-components'
+
+// AntdApp 已内置 GlobalLoading，可直接使用
+function MyApp() {
+  const handleRequest = async () => {
+    setGlobalLoading(true)
+    try {
+      await api.getData()
+    } finally {
+      setGlobalLoading(false)
+    }
+  }
+
+  return <App>{/* 你的应用 */}</App>
+}
+```
+
+#### API 参考
+
+| 方法 | 类型 | 说明 |
+|------|------|------|
+| `setGlobalLoading` | `(loading: boolean) => void` | 设置全局加载状态 |
 
 ### IconButton
-图标按钮组件，支持多种图标类型。
+
+图标按钮组件，支持多种图标类型和自定义配置。
+
+#### 特性
+- **图标支持**: 支持 IconFont 和 React 图标组件
+- **Tooltip 支持**: 内置 Tooltip 提示功能
+- **权限控制**: 支持权限标识和隐藏控制
+- **样式定制**: 支持自定义样式和主题
+
+#### 基本用法
+
+```typescript
+import { IconButton } from 'xmirror-components'
+
+function ActionButtons() {
+  return (
+    <Space>
+      <IconButton
+        icon="edit"
+        title="编辑"
+        onClick={() => console.log('编辑')}
+      />
+      <IconButton
+        icon="delete"
+        title="删除"
+        disabled
+        disabledReason="无权限删除"
+        onClick={() => console.log('删除')}
+      />
+      <IconButton
+        icon={<CustomIcon />}
+        title="自定义图标"
+        size="large"
+        loading
+      />
+    </Space>
+  )
+}
+```
+
+#### 使用 React 图标
+
+```typescript
+import { EditOutlined, DeleteOutlined } from '@ant-design/icons'
+
+function CustomButtons() {
+  return (
+    <Space>
+      <IconButton
+        icon={<EditOutlined />}
+        title="编辑"
+        onClick={handleEdit}
+      />
+      <IconButton
+        icon={<DeleteOutlined />}
+        title="删除"
+        onClick={handleDelete}
+      />
+    </Space>
+  )
+}
+```
+
+#### API 参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `icon` | `React.ReactNode \| string` | - | 图标 |
+| `title` | `React.ReactNode` | - | 提示内容 |
+| `onClick` | `(e: React.MouseEvent) => void` | - | 点击事件 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `disabledReason` | `React.ReactNode` | - | 禁用原因 |
+| `hide` | `boolean` | `false` | 是否隐藏 |
+| `size` | `'small' \| 'middle' \| 'large'` | `'small'` | 按钮大小 |
+| `loading` | `boolean` | `false` | 加载状态 |
 
 ### IconFont
-图标字体组件，支持自定义图标。
+
+图标字体组件，支持自定义图标字体。
+
+#### 特性
+- **字体图标**: 支持 iconfont 字体图标
+- **Symbol 模式**: 支持 SVG Symbol 模式
+- **样式定制**: 支持自定义样式和类名
+- **类型安全**: 完整的 TypeScript 类型支持
+
+#### 基本用法
+
+```typescript
+import { IconFont } from 'xmirror-components'
+
+function IconExamples() {
+  return (
+    <Space>
+      {/* 字体图标模式 */}
+      <IconFont type="icon-home" />
+      <IconFont type="icon-user" size={24} />
+      
+      {/* Symbol 模式 */}
+      <IconFont type="icon-setting" symbol />
+    </Space>
+  )
+}
+```
+
+#### 配置全局样式
+
+```typescript
+import { ConfigProvider } from 'xmirror-components'
+
+function App() {
+  return (
+    <ConfigProvider
+      config={{
+        iconFont: {
+          className: 'my-iconfont',
+          style: { fontSize: '16px', color: '#1890ff' }
+        }
+      }}
+    >
+      <IconFont type="icon-custom" />
+    </ConfigProvider>
+  )
+}
+```
+
+#### API 参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `type` | `string` | - | 图标类型 |
+| `symbol` | `boolean` | `false` | 是否使用 Symbol 模式 |
+| `className` | `string` | - | 自定义类名 |
+| `style` | `React.CSSProperties` | - | 自定义样式 |
 
 ### SwitchValue
-开关值组件，用于布尔值的切换。
+
+开关值组件，支持自定义选中和未选中的值。
+
+#### 特性
+- **自定义值**: 支持任意类型的选中/未选中值
+- **类型安全**: 完整的 TypeScript 泛型支持
+- **简单易用**: 与原生 Switch 组件 API 一致
+
+#### 基本用法
+
+```typescript
+import { SwitchValue } from 'xmirror-components'
+
+function SwitchExamples() {
+  const [status, setStatus] = useState('active')
+
+  return (
+    <Space direction="vertical">
+      {/* 字符串值 */}
+      <SwitchValue
+        checked={status}
+        trueValue="active"
+        falseValue="inactive"
+        onChange={(value) => setStatus(value)}
+      />
+      
+      {/* 数字值 */}
+      <SwitchValue
+        checked={isEnabled}
+        trueValue={1}
+        falseValue={0}
+        onChange={(value) => setIsEnabled(value)}
+      />
+      
+      {/* 对象值 */}
+      <SwitchValue
+        checked={config}
+        trueValue={{ enabled: true, level: 'high' }}
+        falseValue={{ enabled: false, level: 'low' }}
+        onChange={(value) => setConfig(value)}
+      />
+    </Space>
+  )
+}
+```
+
+#### API 参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `checked` | `T \| F` | - | 当前值 |
+| `trueValue` | `T` | `true` | 选中值 |
+| `falseValue` | `F` | `false` | 未选中值 |
+| `onChange` | `(value: T \| F, event) => void` | - | 值变化回调 |
 
 ### CheckboxValue
-复选框值组件，用于多选值的管理。
+
+复选框值组件，支持自定义选中值和标签。
+
+#### 特性
+- **自定义值**: 支持任意类型的选中/未选中值
+- **自定义标签**: 支持自定义显示标签
+- **类型安全**: 完整的 TypeScript 泛型支持
+
+#### 基本用法
+
+```typescript
+import { CheckboxValue } from 'xmirror-components'
+
+function CheckboxExamples() {
+  const [agreed, setAgreed] = useState(false)
+
+  return (
+    <Space direction="vertical">
+      {/* 基本用法 */}
+      <CheckboxValue
+        checked={agreed}
+        trueValue={true}
+        falseValue={false}
+        trueLabel="同意协议"
+        falseLabel="不同意协议"
+        onChange={(value) => setAgreed(value)}
+      />
+      
+      {/* 自定义值 */}
+      <CheckboxValue
+        checked={permission}
+        trueValue="admin"
+        falseValue="user"
+        trueLabel="管理员权限"
+        falseLabel="普通用户权限"
+        onChange={(value) => setPermission(value)}
+      />
+    </Space>
+  )
+}
+```
+
+#### API 参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `checked` | `T \| F` | - | 当前值 |
+| `trueValue` | `T` | `true` | 选中值 |
+| `falseValue` | `F` | `false` | 未选中值 |
+| `trueLabel` | `string` | `''` | 选中标签 |
+| `falseLabel` | `string` | `''` | 未选中标签 |
+| `onChange` | `(value: T \| F, event) => void` | - | 值变化回调 |
 
 ## 🪝 核心 Hooks
 
@@ -205,16 +801,517 @@ console.log(rowSelection.selectedRowKeys)
 
 ### useRequest
 
-基于 ahooks 的请求管理 Hook，提供请求状态管理和缓存功能。
+基于 ahooks 的请求管理 Hook，提供请求状态管理和缓存功能。扩展了错误处理和数据处理能力。
+
+#### 特性
+- **错误处理**: 自动显示错误消息，支持自定义错误处理
+- **数据处理**: 自动处理嵌套的响应数据结构
+- **类型安全**: 完整的 TypeScript 泛型支持
+- **缓存支持**: 基于 ahooks 的缓存机制
+- **插件系统**: 支持 ahooks 插件生态
+
+#### 基本用法
+
+```typescript
+import { useEffect } from 'react'
+import { Select } from 'antd'
+import { useRequest } from 'xmirror-components'
+import { getUserOptions } from '@/api/home/user'
+
+
+function Index ({ ...props }) {
+  const {
+    loading,
+    data
+  } = useRequest(getUserOptions)
+
+  return (
+    <Select
+      className="w-180"
+      loading={loading}
+      placeholder="请选择"
+      options={data}
+      {...props}
+    />
+  )
+}
+
+export default Index
+```
+
+```typescript
+import { useEffect } from 'react'
+import { Select } from 'antd'
+import { useRequest } from 'xmirror-components'
+import { getProfitOptions } from '@/api/home/vendor/credit/detail/listing-information'
+
+interface Props {
+  vendorId: string
+
+  [prop: string]: any
+}
+
+function Index ({ vendorId, ...props }: Props) {
+  const {
+    loading,
+    data,
+    run
+  } = useRequest(() => {
+    return getProfitOptions(vendorId)
+  }, {
+    manual: true // 关闭自动进入页面自动请求
+  })
+
+  useEffect(() => {
+    if (vendorId) {
+      run()
+    }
+  }, [vendorId])
+
+  return (
+    <Select
+      className="w-180"
+      loading={loading}
+      placeholder="请选择季度"
+      options={data}
+      {...props}
+    />
+  )
+}
+
+export default Index
+```
+
+#### 处理嵌套数据结构
+
+```typescript
+// 当 API 返回 { code: 200, data: [...], success: true } 格式时
+const { data } = useRequest(
+  async () => {
+    const response = await fetch('/api/users')
+    return response.json() // 返回 { code: 200, data: [...], success: true }
+  }
+)
+
+// data 将直接是用户数组，而不是 { code, data, success } 对象
+console.log(data) // [...]
+```
+
+#### 自定义错误处理
+
+```typescript
+const { data, loading } = useRequest(
+  fetchUsers,
+  {
+    errorMessage: false, // 禁用自动错误消息
+    onError: (error) => {
+      // 自定义错误处理
+      console.error('请求失败:', error)
+      notification.error({
+        message: '自定义错误提示',
+        description: error.message
+      })
+    }
+  }
+)
+```
+
+#### 使用插件
+
+```typescript
+import { useRequest } from 'xmirror-components'
+import { useDebouncePlugin, usePollingPlugin } from 'ahooks'
+
+function SearchComponent() {
+  const [keyword, setKeyword] = useState('')
+
+  const { data, loading } = useRequest(
+    (params) => searchUsers(params),
+    {
+      errorMessage: true,
+      refreshDeps: [keyword]
+    },
+    [
+      useDebouncePlugin({ wait: 300 }), // 防抖
+      usePollingPlugin({ interval: 5000 }) // 轮询
+    ]
+  )
+
+  return (
+    <div>
+      <Input
+        value={keyword}
+        onChange={(e) => setKeyword(e.target.value)}
+        placeholder="搜索用户"
+      />
+      {/* 搜索结果 */}
+    </div>
+  )
+}
+```
+
+#### API 参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `errorMessage` | `boolean` | `true` | 是否显示错误消息 |
+| `onError` | `(error: Error, params: any[]) => void` | - | 错误回调函数 |
+
+##### 返回值
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `data` | `TData` | 处理后的数据 |
+| `loading` | `boolean` | 加载状态 |
+| `error` | `Error \| undefined` | 错误信息 |
+| `refresh` | `() => void` | 刷新函数 |
+| `mutate` | `(data: TData) => void` | 手动设置数据 |
+| `cancel` | `() => void` | 取消请求 |
+
+##### 扩展选项
+
+useRequest 支持所有 ahooks useRequest 的选项，包括：
+
+- `cacheKey`: 缓存键
+- `refreshDeps`: 依赖刷新
+- `pollingInterval`: 轮询间隔
+- `ready`: 是否准备就绪
+- `onSuccess`: 成功回调
+- `onError`: 错误回调
+- `onFinally`: 完成回调
+
+## 🚀 快速开始
+
+### 完整示例
+
+```typescript
+import React from 'react'
+import { 
+  App, 
+  Table, 
+  SearchArea, 
+  IconButton, 
+  useTable, 
+  useRequest,
+  message 
+} from 'xmirror-components'
+import { Input, Select, Button, Space } from 'antd'
+
+// 用户管理页面示例
+function UserManagement() {
+  // 使用 useTable Hook 管理表格数据
+  const { tableProps, search, rowSelection } = useTable(
+    async (params) => {
+      const response = await fetch('/api/users', {
+        method: 'POST',
+        body: JSON.stringify(params)
+      })
+      return response.json()
+    },
+    {
+      rowKey: 'id',
+      showRowSelection: true,
+      defaultPagination: { current: 1, pageSize: 20 }
+    }
+  )
+
+  // 使用 useRequest Hook 处理删除操作
+  const { run: deleteUser } = useRequest(
+    async (id: number) => {
+      await fetch(`/api/users/${id}`, { method: 'DELETE' })
+    },
+    {
+      onSuccess: () => {
+        message.success('删除成功')
+        search.refresh() // 刷新表格
+      }
+    }
+  )
+
+  const columns = [
+    {
+      title: '姓名',
+      dataIndex: 'name',
+      key: 'name',
+      sorter: true
+    },
+    {
+      title: '邮箱',
+      dataIndex: 'email',
+      key: 'email'
+    },
+    {
+      title: '状态',
+      dataIndex: 'status',
+      key: 'status',
+      render: (status: string) => (
+        <span style={{ color: status === 'active' ? 'green' : 'red' }}>
+          {status === 'active' ? '激活' : '禁用'}
+        </span>
+      )
+    },
+    {
+      title: '操作',
+      key: 'action',
+      render: (_, record) => (
+        <Space>
+          <IconButton
+            icon="edit"
+            title="编辑"
+            onClick={() => handleEdit(record)}
+          />
+          <IconButton
+            icon="delete"
+            title="删除"
+            onClick={() => deleteUser(record.id)}
+          />
+        </Space>
+      )
+    }
+  ]
+
+  return (
+    <div>
+      {/* 搜索区域 */}
+      <SearchArea
+        onSearch={(values) => search.submit(values)}
+        onReset={() => search.submit({})}
+      >
+        <SearchArea.Item name="name" label="姓名">
+          <Input placeholder="请输入姓名" />
+        </SearchArea.Item>
+        <SearchArea.Item name="status" label="状态">
+          <Select placeholder="请选择状态">
+            <Select.Option value="active">激活</Select.Option>
+            <Select.Option value="inactive">禁用</Select.Option>
+          </Select>
+        </SearchArea.Item>
+      </SearchArea>
+
+      {/* 表格 */}
+      <Table
+        {...tableProps}
+        columns={columns}
+        columnsSort={true}
+        columnsVisible={true}
+        columnsResizable={true}
+        tableId="user-management"
+      />
+    </div>
+  )
+}
+
+// 应用入口
+function App() {
+  return (
+    <App
+      config={{
+        iconButton: {
+          size: 'small',
+          style: { color: '#1890ff' }
+        }
+      }}
+    >
+      <UserManagement />
+    </App>
+  )
+}
+
+export default App
+```
 
 ## 🎨 样式系统
 
 组件库使用 CSS-in-JS 方案，支持主题定制和样式覆盖。
 
+### 主题定制
+
+```typescript
+import { ConfigProvider } from 'xmirror-components'
+
+function App() {
+  return (
+    <ConfigProvider
+      config={{
+        iconButton: {
+          style: {
+            color: '#1890ff',
+            borderRadius: '6px'
+          }
+        },
+        iconFont: {
+          style: {
+            fontSize: '16px',
+            color: '#666'
+          }
+        }
+      }}
+    >
+      {/* 你的应用 */}
+    </ConfigProvider>
+  )
+}
+```
+
+### 自定义样式
+
+```typescript
+import styled from '@emotion/styled'
+import { Table } from 'xmirror-components'
+
+const CustomTable = styled(Table)`
+  .ant-table-thead > tr > th {
+    background-color: #f5f5f5;
+    font-weight: 600;
+  }
+  
+  .ant-table-tbody > tr:hover > td {
+    background-color: #f0f9ff;
+  }
+`
+
+function MyTable() {
+  return <CustomTable {...props} />
+}
+```
+
 ## 🌍 国际化
 
 内置国际化支持，使用 react-intl 实现多语言切换。
 
+### 基本配置
+
+```typescript
+import { ConfigProvider } from 'xmirror-components'
+import { IntlProvider } from 'react-intl'
+import zhCN from 'antd/locale/zh_CN'
+import enUS from 'antd/locale/en_US'
+
+const messages = {
+  'zh-CN': require('./locales/zh-CN.json'),
+  'en-US': require('./locales/en-US.json')
+}
+
+function App() {
+  const [locale, setLocale] = useState('zh-CN')
+  
+  return (
+    <IntlProvider locale={locale} messages={messages[locale]}>
+      <ConfigProvider locale={locale === 'zh-CN' ? zhCN : enUS}>
+        {/* 你的应用 */}
+      </ConfigProvider>
+    </IntlProvider>
+  )
+}
+```
+
+## 📋 最佳实践
+
+### 1. 组件组合使用
+
+```typescript
+// 推荐：组合使用多个组件
+function DataTable() {
+  const { tableProps, search } = useTable(fetchData)
+  
+  return (
+    <div>
+      <SearchArea onSearch={search.submit}>
+        {/* 搜索表单项 */}
+      </SearchArea>
+      <Table {...tableProps} />
+    </div>
+  )
+}
+```
+
+### 2. 错误处理
+
+```typescript
+// 推荐：统一的错误处理
+const { data, loading, error } = useRequest(fetchData, {
+  errorMessage: true, // 自动显示错误消息
+  onError: (error) => {
+    // 记录错误日志
+    console.error('API Error:', error)
+  }
+})
+```
+
+### 3. 性能优化
+
+```typescript
+// 推荐：使用 useMemo 优化渲染
+const columns = useMemo(() => [
+  {
+    title: '姓名',
+    dataIndex: 'name',
+    render: (text) => <span>{text}</span>
+  }
+], [])
+
+// 推荐：使用 useCallback 优化事件处理
+const handleEdit = useCallback((record) => {
+  // 编辑逻辑
+}, [])
+```
+
+### 4. 类型安全
+
+```typescript
+// 推荐：定义完整的类型
+interface User {
+  id: number
+  name: string
+  email: string
+  status: 'active' | 'inactive'
+}
+
+const { tableProps } = useTable<User>(fetchUsers, {
+  rowKey: 'id'
+})
+```
+
+## 🔧 常见问题
+
+### Q: 如何自定义表格样式？
+
+A: 使用 styled-components 或 emotion 包装 Table 组件：
+
+```typescript
+import styled from '@emotion/styled'
+import { Table } from 'xmirror-components'
+
+const CustomTable = styled(Table)`
+  .ant-table-thead > tr > th {
+    background-color: #f5f5f5;
+  }
+`
+```
+
+### Q: 如何处理大量数据？
+
+A: 使用虚拟滚动或分页加载：
+
+```typescript
+const { tableProps } = useTable(fetchData, {
+  defaultPagination: { current: 1, pageSize: 50 }
+})
+```
+
+### Q: 如何实现权限控制？
+
+A: 使用 IconButton 的权限属性：
+
+```typescript
+<IconButton
+  icon="delete"
+  hide={!hasPermission('delete')}
+  disabled={!hasPermission('delete')}
+  disabledReason="无删除权限"
+/>
+```
+
 ## 📚 开发指南
 
 ### 项目结构
@@ -273,7 +1370,27 @@ npm run lint
 
 ## 🔧 最近更新
 
-### v1.0.2 (2024-01-XX)
+### v1.0.30-alpha.10 (2024-01-XX)
+
+#### 修复
+- **TypeScript 导入路径修复**: 修复了所有文件中的 TypeScript 导入路径问题
+  - 移除了 `src/locale/index.ts` 中的 `.ts` 扩展名
+  - 移除了 `src/components/Table/Footer/index.tsx` 中的 `.ts` 扩展名
+  - 移除了 `src/locale/types.ts` 中的 `.ts` 扩展名
+  - 移除了 `src/main.tsx` 中的 `.tsx` 扩展名
+  - 修复了 React 导入问题，确保 JSX 正常工作
+
+#### 改进
+- 解决了 TypeScript 编译错误，确保项目能够正常构建
+- 提升了代码的兼容性和可维护性
+- 统一了项目的导入规范
+
+### v1.0.30-alpha.8 (2024-01-XX)
+
+#### 新增功能
+- **完整文档**: 为所有组件和 Hook 编写了详细的使用文档和 API 参考
+- **最佳实践**: 添加了组件组合使用、错误处理、性能优化等最佳实践指南
+- **完整示例**: 提供了完整的用户管理页面示例，展示组件库的实际应用
 
 #### 样式系统优化
 - **ResizableColumns 样式转换**: 将 `index.less` 文件转换为 `@emotion/styled` 形式
@@ -287,6 +1404,7 @@ npm run lint
 - 统一了项目的样式系统，全部使用 `@emotion/styled`
 - 提升了代码的类型安全性和可维护性
 - 优化了组件库的构建和打包流程
+- 完善了组件库的文档体系，提供更好的开发体验
 
 ### v1.0.1 (2024-01-XX)