gzkx-package 0.1.47 → 0.1.49

package/README.md

@@ -1,269 +1,1214 @@
-# CommonPage 组件库
+# 自定义组件使用文档
 
-一个基于 React 和 Ant Design 的通用页面组件库，提供完整的 CRUD 功能。
+本文档详细介绍了项目中四个核心自定义组件的使用方法和参数说明。
+
+---
+
+## 目录
+
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [组件列表](#组件列表)
+  1. [CommonPage 通用页面组件](#1-commonpage-通用页面组件)
+  2. [CustomTable 自定义表格组件](#2-customtable-自定义表格组件)
+  3. [CustomForm 自定义表单组件](#3-customform-自定义表单组件)
+  4. [CustomAdd 新增/编辑弹窗组件](#4-customadd-新增编辑弹窗组件)
+
+---
 
 ## 安装
 
+### 使用 npm
+
 ```bash
 npm install gzkx-package
-# 或
+```
+
+### 使用 yarn
+
+```bash
 yarn add gzkx-package
-# 或
+```
+
+### 使用 pnpm
+
+```bash
 pnpm add gzkx-package
 ```
 
-## 使用
+---
+
+## 快速开始
+
+### 1. 安装依赖
+
+确保项目中已安装以下依赖（peerDependencies）：
+
+```bash
+npm install antd axios dayjs lodash pinyin-pro react react-dom
+```
+
+**版本要求：**
+- `antd`: ^5.0.0
+- `axios`: ^1.0.0
+- `dayjs`: ^1.11.0
+- `lodash`: ^4.17.0
+- `pinyin-pro`: ^3.0.0
+- `react`: ^18.0.0 或 ^19.0.0
+- `react-dom`: ^18.0.0 或 ^19.0.0
+
+### 2. 引入样式
+
+在项目入口文件（如 `main.tsx` 或 `App.tsx`）中引入样式：
+
+```tsx
+// 引入 Ant Design 样式
+import 'antd/dist/reset.css';
+
+// 引入组件库样式
+import 'gzkx-package/style';
+
+```
+
+### 3. 基本使用
 
-### 基础用法
+导入并使用组件：
 
 ```tsx
-import React from 'react';
 import { CommonPage } from 'gzkx-package';
-// 引入样式文件（推荐使用直接路径）
+import type { FormItemConfig } from 'gzkx-package';
+import type { AddItemConfig } from 'gzkx-package';
 import 'gzkx-package/dist/style.css';
 
-function App() {
-  const searchFormConfig = [
+
+const MyPage = () => {
+  // 搜索表单配置
+  const searchFormConfig: FormItemConfig[] = [
+    {
+      type: 'input',
+      label: '姓名',
+      name: 'name',
+      colSpan: 6,
+    },
+  ];
+
+  // 新增/编辑表单配置
+  const addFormConfig: AddItemConfig[] = [
+    {
+      type: 'input',
+      label: '姓名',
+      name: 'name',
+      rules: [{ required: true, message: '请输入姓名' }],
+      colSpan: 12,
+    },
+  ];
+
+  // 表格列配置
+  const tableColumns = [
+    {
+      title: '姓名',
+      dataIndex: 'name',
+      key: 'name',
+      width: 150,
+    },
+  ];
+
+  // API 地址配置
+  const URL = {
+    search: '/user/list',
+    add: '/user/add',
+    edit: '/user/edit',
+    delete: '/user/delete',
+  };
+
+  return (
+    <CommonPage
+      searchFormConfig={searchFormConfig}
+      addFormConfig={addFormConfig}
+      tableColumns={tableColumns}
+      URL={URL}
+      tableId="my-table"
+      isReset={true}
+    />
+  );
+};
+
+export default MyPage;
+```
+
+### 4. 导出组件列表
+
+本组件库主要导出以下组件：
+
+| 组件名 | 说明 | 导入方式 |
+|--------|------|---------|
+| `CommonPage` | 通用页面组件 | `import { CommonPage } from 'gzkx-package'` |
+| `CustomTable` | 自定义表格组件 | `import { CustomTable } from 'gzkx-package'` |
+| `CustomForm` | 自定义表单组件 | `import { CustomForm } from 'gzkx-package'` |
+| `CustomAdd` | 新增/编辑弹窗组件 | `import { CustomAdd } from 'gzkx-package'` |
+
+### 5. TypeScript 类型导出
+
+```tsx
+import type { 
+  FormItemConfig,      // 搜索表单配置类型
+  AddItemConfig,       // 新增/编辑表单配置类型
+  ValidateConfig,      // 验证配置类型
+  CommonPageHandle,    // CommonPage Ref 类型
+  CustomTableHandle,   // CustomTable Ref 类型
+  CustomColumnType,    // 自定义表格列类型
+  CustomColumnsType,   // 自定义表格列数组类型
+} from 'gzkx-package';
+```
+
+---
+
+## 组件列表
+
+## 1. CommonPage 通用页面组件
+
+### 1.1 组件概述
+
+`CommonPage` 是一个集成了搜索表单、数据表格、新增/编辑弹窗的通用页面组件，适用于大部分 CRUD 操作场景。
+
+### 1.2 Props 参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `searchFormConfig` | `FormItemConfig[] \| null` | 是 | - | 搜索表单配置项数组 |
+| `addFormConfig` | `AddItemConfig[]` | 是 | - | 新增/编辑表单配置项数组 |
+| `tableColumns` | `any[]` | 是 | - | 表格列配置数组 |
+| `URL` | `object` | 是 | - | API 接口地址配置，包含 `search`, `add`, `edit`, `delete`, `view` |
+| `tableId` | `string` | 否 | - | 表格唯一 ID，用于保存用户的表格配置 |
+| `isnopage` | `boolean` | 否 | `false` | 是否不分页 |
+| `topHeight` | `number` | 否 | - | 顶部高度（像素） |
+| `tableHeight` | `number` | 否 | `150` | 表格高度调整参数 |
+| `actionWidth` | `number` | 否 | `150` | 操作列宽度 |
+| `editText` | `string` | 否 | `'编辑'` | 编辑按钮文本 |
+| `viewText` | `string` | 否 | `'查看'` | 查看按钮文本 |
+| `delText` | `string` | 否 | `'删除'` | 删除按钮文本 |
+| `isaddtab` | `boolean` | 否 | `false` | 新增/编辑表单是否分 Tab 显示 |
+| `isReset` | `boolean` | 否 | `false` | 是否显示重置按钮 |
+| `addisdisabled` | `object` | 否 | `{ isdisabled: false, message: '' }` | 新增按钮禁用配置 |
+| `postParams` | `object` | 否 | - | 请求参数配置对象 |
+| `limit` | `object` | 否 | 全部为 `true` | 操作权限限制配置 |
+| `CustomOperations` | `ReactNode \| Function` | 否 | - | 自定义操作列内容 |
+| `PropOtherButton` | `ReactNode \| Function` | 否 | - | 搜索表单右侧的其他按钮 |
+| `CustomModalFooter` | `Function` | 否 | - | 自定义弹窗底部按钮 |
+| `proplist` | `any[]` | 否 | - | 假数据（用于测试） |
+| `editdclickback` | `Function` | 否 | - | 点击编辑/新增时的回调函数 |
+| `oneditFormChange` | `Function` | 否 | - | 编辑表单值变化时的回调 |
+| `onSearchFormChange` | `Function` | 否 | - | 搜索表单值变化时的回调 |
+| `onRowClick` | `Function` | 否 | - | 表格行点击回调 |
+| `onDelete` | `Function` | 否 | - | 删除成功后的回调 |
+| `onSearch` | `Function` | 否 | - | 搜索按钮点击后的回调 |
+| `onReset` | `Function` | 否 | - | 重置按钮点击后的回调 |
+| `onView` | `Function` | 否 | - | 查看按钮点击后的回调 |
+| `validateConfig` | `ValidateConfig` | 否 | - | 表单验证配置 |
+| `tableConfig` | `any` | 否 | - | 表格额外配置 |
+
+#### 1.2.1 详细参数说明
+
+**postParams 对象结构：**
+
+```typescript
+{
+  addParams?: any;      // 新增时额外携带的参数
+  delParams?: any;      // 删除时额外携带的参数
+  editParams?: any;     // 编辑时额外携带的参数
+  searchParams?: any;   // 搜索时额外携带的参数
+}
+```
+
+**limit 对象结构：**
+
+```typescript
+{
+  addLimit?: boolean;    // 是否显示新增按钮，默认 true
+  delLimit?: boolean;    // 是否显示删除按钮，默认 true
+  editLimit?: boolean;   // 是否显示编辑按钮，默认 true
+  searchLimit?: boolean; // 是否显示搜索功能，默认 true
+}
+```
+
+**URL 对象结构：**
+
+```typescript
+{
+  search: string;   // 查询接口地址
+  add?: string;     // 新增接口地址
+  edit?: string;    // 编辑接口地址
+  delete?: string;  // 删除接口地址
+  view?: string;    // 查看接口地址（可选，如果没有则使用 edit）
+}
+```
+
+### 1.3 Ref 暴露的方法
+
+使用 `ref` 可以调用组件内部方法：
+
+```typescript
+interface CommonPageHandle {
+  getList: (parentParams?: any) => Promise<void>;  // 刷新列表
+  setFieldsValue: (values: any) => void;           // 设置表单字段值
+  getFieldsValue: () => any;                        // 获取表单字段值
+  reload: () => void;                               // 重新加载列表
+  getSearchFieldsValue: () => any;                  // 获取搜索表单值
+  setSearchFieldsValue: (values: any) => void;      // 设置搜索表单值
+  /** 打开表格配置弹窗 */
+  openSettingModal: () => void;                     // 打开表格配置弹窗
+  /** 关闭表格配置弹窗 */
+  closeSettingModal: () => void;                    // 关闭表格配置弹窗
+}
+```
+
+### 1.4 使用示例
+
+```tsx
+import { useRef } from 'react';
+import CommonPage, { CommonPageHandle } from '@/components/customComponents/commonPage';
+import { FormItemConfig } from '@/components/customComponents/CustomForm';
+import { AddItemConfig } from '@/components/customComponents/CustomAdd';
+
+const DemoPage = () => {
+  const pageRef = useRef<CommonPageHandle>(null);
+
+  // 搜索表单配置
+  const searchFormConfig: FormItemConfig[] = [
     {
       type: 'input',
-      label: '名称',
+      label: '姓名',
       name: 'name',
-      placeholder: '请输入名称',
+      placeholder: '请输入姓名',
+      colSpan: 6,
     },
     {
       type: 'select',
       label: '状态',
       name: 'status',
       options: [
-        { label: '启用', value: '1' },
-        { label: '禁用', value: '0' },
+        { label: '启用', value: 1 },
+        { label: '禁用', value: 0 },
       ],
+      colSpan: 6,
+    },
+    {
+      type: 'rangePicker',
+      label: '日期范围',
+      name: 'createTime/endTime',
+      colSpan: 6,
     },
   ];
 
-  const addFormConfig = [
+  // 新增/编辑表单配置
+  const addFormConfig: AddItemConfig[] = [
     {
       type: 'input',
-      label: '名称',
+      label: '姓名',
       name: 'name',
-      rules: [{ required: true, message: '请输入名称' }],
+      rules: [{ required: true, message: '请输入姓名' }],
+      colSpan: 12,
+    },
+    {
+      type: 'InputNumber',
+      label: '年龄',
+      name: 'age',
+      colSpan: 12,
+    },
+    {
+      type: 'Radio',
+      label: '性别',
+      name: 'gender',
+      options: [
+        { label: '男', value: 1 },
+        { label: '女', value: 0 },
+      ],
+      colSpan: 12,
+    },
+    {
+      type: 'textarea',
+      label: '备注',
+      name: 'remark',
+      colSpan: 24,
     },
   ];
 
+  // 表格列配置
   const tableColumns = [
     {
-      title: 'ID',
-      dataIndex: 'id',
-      key: 'id',
-    },
-    {
-      title: '名称',
+      title: '姓名',
       dataIndex: 'name',
       key: 'name',
+      width: 150,
+    },
+    {
+      title: '年龄',
+      dataIndex: 'age',
+      key: 'age',
+      width: 100,
+    },
+    {
+      title: '性别',
+      dataIndex: 'gender',
+      key: 'gender',
+      width: 100,
+      render: (text: number) => (text === 1 ? '男' : '女'),
+    },
+    {
+      title: '创建时间',
+      dataIndex: 'createTime',
+      key: 'createTime',
+      width: 180,
     },
   ];
 
+  // API 地址配置
   const URL = {
-    search: '/api/search',
-    add: '/api/add',
-    edit: '/api/edit',
-    delete: '/api/delete',
+    search: '/api/user/list',
+    add: '/api/user/add',
+    edit: '/api/user/edit',
+    delete: '/api/user/delete',
   };
 
   return (
     <CommonPage
+      ref={pageRef}
       searchFormConfig={searchFormConfig}
       addFormConfig={addFormConfig}
       tableColumns={tableColumns}
       URL={URL}
+      tableId="user-table"
+      isReset={true}
+      postParams={{
+        searchParams: { orgId: '123' },
+      }}
+      onRowClick={(record) => {
+        console.log('点击了行:', record);
+      }}
+      onDelete={(record) => {
+        console.log('删除了:', record);
+      }}
+      onSearch={() => {
+        console.log('搜索触发');
+      }}
+      onReset={() => {
+        console.log('重置触发');
+      }}
+      onView={(record) => {
+        console.log('查看了:', record);
+      }}
     />
   );
-}
+};
 
-export default App;
+export default DemoPage;
 ```
 
-### 使用 ref 调用组件方法
+---
 
-```tsx
-import React, { useRef } from 'react';
-import { CommonPage, CommonPageHandle } from 'gzkx-package';
+## 2. CustomTable 自定义表格组件
 
-function App() {
-  const commonPageRef = useRef<CommonPageHandle>(null);
+### 2.1 组件概述
 
-  const handleRefresh = () => {
-    commonPageRef.current?.reload();
-  };
+`CustomTable` 是对 Ant Design Table 组件的增强封装，支持用户自定义表格列配置、保存配置到后端、序号列、树形数据等功能。
+
+### 2.2 Props 参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `columns` | `ColumnsType<any>` | 是 | - | 表格列配置 |
+| `dataSource` | `any[]` | 是 | - | 表格数据源 |
+| `loading` | `boolean` | 否 | `false` | 加载状态 |
+| `pagination` | `object \| false` | 否 | - | 分页配置 |
+| `handleTableChange` | `Function` | 否 | - | 表格变化回调 |
+| `size` | `'small' \| 'middle' \| 'large'` | 否 | `'middle'` | 表格尺寸 |
+| `tableId` | `string` | 否 | - | 表格唯一 ID，用于保存列配置 |
+| `onRowClick` | `Function` | 否 | - | 行点击回调 |
+| `page` | `object` | 否 | - | 分页信息（用于序号计算） |
+| `showTableConfig` | `boolean` | 否 | `true` | 是否显示表格配置按钮和序号列 |
+| `...rest` | `any` | 否 | - | 其他 Ant Design Table 原生属性 |
+
+### 2.3 特色功能
 
-  const handleSetFormValues = () => {
-    commonPageRef.current?.setFieldsValue({
-      name: '测试名称',
-    });
+1. **表格配置功能**：用户可以自定义列的显示、宽度、对齐方式、排序等，配置会保存到后端。
+2. **自动序号列**：自动添加序号列（可通过 `showTableConfig` 控制）。
+3. **树形数据支持**：支持展开/收起树形数据。
+4. **Tooltip 支持**：单元格内容过长时自动显示 Tooltip。
+
+### 2.4 Ref 暴露的方法
+
+使用 `ref` 可以调用组件内部方法：
+
+```typescript
+interface CustomTableHandle {
+  openSettingModal: () => void;   // 打开表格配置弹窗
+  closeSettingModal: () => void;  // 关闭表格配置弹窗
+}
+```
+
+**使用示例：**
+
+```tsx
+import { useRef } from 'react';
+import CustomTable, { CustomTableHandle } from '@/components/customComponents/CustomTable';
+
+const Demo = () => {
+  const tableRef = useRef<CustomTableHandle>(null);
+
+  const handleOpenConfig = () => {
+    tableRef.current?.openSettingModal();
   };
 
   return (
     <>
-      <button onClick={handleRefresh}>刷新列表</button>
-      <button onClick={handleSetFormValues}>设置表单值</button>
-      <CommonPage
-        ref={commonPageRef}
-        searchFormConfig={searchFormConfig}
-        addFormConfig={addFormConfig}
-        tableColumns={tableColumns}
-        URL={URL}
+      <Button onClick={handleOpenConfig}>打开表格配置</Button>
+      <CustomTable
+        ref={tableRef}
+        columns={columns}
+        dataSource={dataSource}
+        tableId="my-table"
       />
     </>
   );
+};
+```
+
+### 2.5 使用示例
+
+```tsx
+import CustomTable from '@/components/customComponents/CustomTable';
+
+const DemoTable = () => {
+  const [dataSource, setDataSource] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [pagination, setPagination] = useState({
+    current: 1,
+    pageSize: 10,
+    total: 0,
+  });
+
+  const columns = [
+    {
+      title: '姓名',
+      dataIndex: 'name',
+      key: 'name',
+      width: 150,
+    },
+    {
+      title: '年龄',
+      dataIndex: 'age',
+      key: 'age',
+      width: 100,
+    },
+    {
+      title: '地址',
+      dataIndex: 'address',
+      key: 'address',
+      width: 300,
+    },
+  ];
+
+  return (
+    <CustomTable
+      columns={columns}
+      dataSource={dataSource}
+      loading={loading}
+      pagination={pagination}
+      tableId="demo-table"
+      page={pagination}
+      showTableConfig={true}
+      onRowClick={(record) => {
+        console.log('点击行:', record);
+      }}
+      handleTableChange={(newPagination) => {
+        setPagination(newPagination);
+      }}
+    />
+  );
+};
+```
+
+### 2.6 列配置弹窗说明
+
+当 `showTableConfig={true}` 时，序号列旁边会显示设置图标，点击后打开配置弹窗，可以配置：
+
+- **显示名称**：列的显示标题
+- **表头对齐**：左/中/右对齐
+- **内容对齐**：左/中/右对齐
+- **数据格式**：字符串/数字/日期
+- **宽度**：列宽
+- **是否启用**：是否显示该列
+- **允许排序**：是否允许排序
+- **排序**：列的显示顺序
+
+---
+
+## 3. CustomForm 自定义表单组件
+
+### 3.1 组件概述
+
+`CustomForm` 是一个基于配置的表单组件，通过传入配置数组即可快速生成表单，支持多种表单项类型。
+
+### 3.2 Props 参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `config` | `FormItemConfig[]` | 是 | - | 表单项配置数组 |
+| `onFinish` | `Function` | 否 | - | 表单提交回调 |
+| `onSearch` | `Function` | 否 | - | 搜索按钮点击回调 |
+| `onReset` | `Function` | 否 | - | 重置按钮点击回调 |
+| `initialValues` | `object` | 否 | - | 表单初始值 |
+| `layout` | `'horizontal' \| 'vertical' \| 'inline'` | 否 | `'horizontal'` | 表单布局 |
+| `labelCol` | `object` | 否 | `{ span: 5 }` | label 栅格布局 |
+| `wrapperCol` | `object` | 否 | `{ span: 19 }` | 控件栅格布局 |
+| `submitButtonText` | `string` | 否 | `'搜索'` | 提交按钮文本 |
+| `resetButtonText` | `string` | 否 | `'重置'` | 重置按钮文本 |
+| `isReset` | `boolean` | 否 | `false` | 是否显示重置按钮 |
+| `OtherButton` | `ReactNode \| Function` | 否 | - | 其他按钮 |
+| `onSearchFormChange` | `Function` | 否 | - | 表单值变化回调 |
+| `...restFormProps` | `any` | 否 | - | 其他 Ant Design Form 原生属性 |
+
+### 3.3 FormItemConfig 配置项
+
+```typescript
+interface FormItemConfig {
+  type: 'input' | 'select' | 'rangePicker' | 'datePicker' | 'password' | 
+        'treeSelect' | 'radio' | 'deptSelect' | 'orgSelect';
+  label: string;              // 标签文本
+  name: string;               // 字段名
+  placeholder?: string;       // 占位符
+  options?: FormItemOption[]; // 选项（用于 select、radio 等）
+  rules?: any[];              // 验证规则
+  colSpan?: number;           // 栅格占位（默认 6，即一行 4 个）
+  labelCol?: number;          // label 栅格占位（默认 5）
+  wrapperCol?: number;        // 控件栅格占位（默认 19）
+  initialValue?: any;         // 初始值
+  defaultValue?: any;         // 默认值
+  [key: string]: any;         // 其他属性
+}
+
+interface FormItemOption {
+  label: React.ReactNode;
+  value: string | number;
 }
 ```
 
-## API
-
-### CommonPage Props
-
-| 属性 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| searchFormConfig | 搜索表单配置 | FormItemConfig[] \| null | null |
-| addFormConfig | 新增/编辑表单配置 | AddItemConfig[] | - |
-| tableColumns | 表格列配置 | any[] | - |
-| URL | API 接口地址配置 | { search?: string; add?: string; edit?: string; delete?: string; view?: string } | - |
-| topHeight | 顶部高度 | number | - |
-| isnopage | 是否不分页 | boolean | false |
-| tableHeight | 表格高度 | number | 150 |
-| actionWidth | 操作列宽度 | number | 150 |
-| delText | 删除按钮文本 | string | '删除' |
-| editText | 编辑按钮文本 | string | '编辑' |
-| viewText | 查看按钮文本 | string | '查看' |
-| CustomOperations | 自定义操作列 | React.ReactNode \| ((record: any) => React.ReactNode) | - |
-| PropOtherButton | 其他按钮 | React.ReactNode \| ((record: any) => React.ReactNode) | - |
-| CustomModalFooter | 自定义模态框底部 | ((record: any) => React.ReactNode) | - |
-| addisdisabled | 是否禁用新增按钮 | { isdisabled: boolean; message: string } | { isdisabled: false, message: '' } |
-| postParams | POST 请求参数 | { addParams?: any; delParams?: any; editParams?: any; searchParams?: any } | - |
-| limit | 权限控制 | { addLimit?: boolean; delLimit?: boolean; editLimit?: boolean; searchLimit?: boolean } | { addLimit: true, delLimit: true, editLimit: true, searchLimit: true } |
-| proplist | 假数据（用于测试） | any[] | - |
-| editdclickback | 编辑/新增点击回调 | (record?: any) => void | - |
-| oneditFormChange | 表单值变化回调 | (changedValues: any, allValues: any) => void | - |
-| onRowClick | 行点击回调 | (record: any, event: any) => void | - |
-| tableId | 表格ID（用于保存表格配置） | string | - |
-| isaddtab | 是否使用 Tab 表单 | boolean | false |
-
-### CommonPageHandle Methods
-
-| 方法 | 说明 | 类型 |
-|------|------|------|
-| getList | 获取列表数据 | (parentParams?: any) => Promise<void> |
-| setFieldsValue | 设置表单值 | (values: any) => void |
-| getFieldsValue | 获取表单值 | () => any |
-| reload | 重新加载列表 | () => void |
-
-## 注意事项
-
-### 依赖要求
-
-本组件库依赖以下 peer dependencies，请确保在使用前已安装：
-
-- `react` >= 18.0.0
-- `react-dom` >= 18.0.0
-- `antd` >= 5.0.0
-- `lodash` >= 4.17.0
-- `dayjs` >= 1.11.0
-- `pinyin-pro` >= 3.0.0
-- `axios` >= 1.0.0
-
-### API 请求配置
-
-组件内部使用 `commonPost` 函数进行 API 请求。由于组件依赖项目特定的 API 函数，您需要：
-
-1. **提供 `commonPost` 函数**：组件需要从 `@/api/common` 导入 `commonPost` 函数。如果您的项目结构不同，需要：
-   - 创建对应的 API 文件，或
-   - 修改组件中的导入路径
-
-2. **提供 `auth` 工具**：组件需要从 `@/utils/auth` 导入 `auth` 对象。如果您的项目结构不同，需要：
-   - 创建对应的工具文件，或
-   - 修改组件中的导入路径
-
-3. **API 响应格式**：确保 API 返回符合以下格式：
+### 3.4 支持的表单类型
+
+| type 值 | 说明 | 额外属性 |
+|---------|------|---------|
+| `input` | 普通输入框 | - |
+| `password` | 密码输入框 | - |
+| `select` | 下拉选择 | `options` |
+| `radio` | 单选框 | `options` |
+| `rangePicker` | 日期范围选择 | - |
+| `datePicker` | 日期选择 | - |
+| `treeSelect` | 树形选择 | `options` (treeData 格式) |
+| `deptSelect` | 科室选择（自动加载数据） | - |
+| `orgSelect` | 机构选择（自动加载数据） | - |
+
+### 3.5 Ref 暴露的方法
 
 ```typescript
-{
-  code: 200,
-  msg: 'success',
-  data: {
-    list: [], // 或直接是数组
-    pageNum: 1,
-    pageSize: 15,
-    total: 0
-  }
+interface CustomFormHandle {
+  setFieldsValue: (values: any) => void;  // 设置表单值
+  getFieldsValue: () => any;              // 获取表单值
+}
+```
+
+### 3.6 使用示例
+
+```tsx
+import { useRef } from 'react';
+import CustomForm, { FormItemConfig } from '@/components/customComponents/CustomForm';
+
+const DemoForm = () => {
+  const formRef = useRef<any>(null);
+
+  const formConfig: FormItemConfig[] = [
+    {
+      type: 'input',
+      label: '用户名',
+      name: 'username',
+      placeholder: '请输入用户名',
+      colSpan: 6,
+      rules: [{ required: true, message: '请输入用户名' }],
+    },
+    {
+      type: 'select',
+      label: '角色',
+      name: 'role',
+      options: [
+        { label: '管理员', value: 'admin' },
+        { label: '普通用户', value: 'user' },
+      ],
+      colSpan: 6,
+    },
+    {
+      type: 'rangePicker',
+      label: '日期范围',
+      name: 'dateRange',
+      colSpan: 6,
+    },
+    {
+      type: 'orgSelect',
+      label: '机构',
+      name: 'orgId',
+      colSpan: 6,
+    },
+  ];
+
+  const handleSearch = (values: any) => {
+    console.log('搜索参数:', values);
+  };
+
+  const handleReset = (form: any) => {
+    console.log('重置表单');
+  };
+
+  return (
+    <CustomForm
+      ref={formRef}
+      config={formConfig}
+      onSearch={handleSearch}
+      onReset={handleReset}
+      isReset={true}
+      submitButtonText="查询"
+      resetButtonText="重置"
+      OtherButton={
+        <Button onClick={() => console.log(formRef.current?.getFieldsValue())}>
+          获取表单值
+        </Button>
+      }
+    />
+  );
+};
+```
+
+---
+
+## 4. CustomAdd 新增/编辑弹窗组件
+
+### 4.1 组件概述
+
+`CustomAdd` 是一个功能强大的弹窗表单组件，支持新增、编辑、查看三种模式，支持多种表单项类型、表单验证、Tab 分组等。
+
+### 4.2 Props 参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `visible` | `boolean` | 是 | - | 弹窗是否可见 |
+| `mode` | `'add' \| 'edit' \| 'view'` | 是 | - | 模式：新增/编辑/查看 |
+| `config` | `AddItemConfig[]` | 是 | - | 表单项配置数组 |
+| `initialValues` | `object` | 否 | - | 初始值（编辑/查看模式） |
+| `onOk` | `Function` | 是 | - | 确定按钮回调 |
+| `onCancel` | `Function` | 是 | - | 取消按钮回调 |
+| `title` | `string` | 否 | 自动生成 | 弹窗标题 |
+| `loading` | `boolean` | 否 | `false` | 确定按钮加载状态 |
+| `tab` | `boolean` | 否 | `false` | 是否分 Tab 显示 |
+| `modalProps` | `object` | 否 | - | Modal 额外属性 |
+| `oneditFormChange` | `Function` | 否 | - | 表单值变化回调 |
+| `CustomModalFooter` | `Function` | 否 | - | 自定义底部按钮 |
+| `validateConfig` | `ValidateConfig` | 否 | - | 验证配置 |
+
+### 4.3 AddItemConfig 配置项
+
+```typescript
+interface AddItemConfig {
+  type: 'input' | 'inputoption' | 'inputnumberoption' | 'select' | 
+        'rangePicker' | 'datePicker' | 'password' | 'InputNumber' | 
+        'Radio' | 'upload' | 'textarea' | 'area' | 'treeSelect' | 
+        'richText' | 'doubleValue' | 'file' | 'deptSelect' | 
+        'orgSelect' | 'uploadByte';
+  label: string;                // 标签文本
+  name: string;                 // 字段名
+  placeholder?: string;         // 占位符
+  options?: FormItemOption[];   // 选项
+  rules?: any[];                // 验证规则
+  colSpan?: number;             // 栅格占位（默认 6）
+  defaultValue?: any;           // 默认值
+  
+  // 特殊字段（根据 type 使用）
+  optionname?: string;          // inputoption 类型的下拉框字段名
+  labelName?: string;           // select 类型保存 label 的字段名
+  firstLabel?: string;          // doubleValue 第一个输入框字段名
+  secondLabel?: string;         // doubleValue 第二个输入框字段名
+  separator?: string;           // doubleValue 分隔符
+  dateFormat?: string;          // 日期格式化字符串
+  
+  [key: string]: any;           // 其他属性
+}
+```
+
+### 4.4 支持的表单类型
+
+| type 值 | 说明 | 额外配置 |
+|---------|------|---------|
+| `input` | 普通输入框 | 支持拼音码自动生成 |
+| `password` | 密码输入框 | - |
+| `textarea` | 多行文本 | - |
+| `InputNumber` | 数字输入框 | - |
+| `select` | 下拉选择 | `options`, `labelName` |
+| `Radio` | 单选框 | `options` |
+| `datePicker` | 日期选择 | `dateFormat` |
+| `rangePicker` | 日期范围 | `dateFormat`，name 格式："startDate/endDate" |
+| `treeSelect` | 树形选择 | `options`, `multiple` |
+| `upload` | 图片上传 | - |
+| `file` | 文件上传 | - |
+| `uploadByte` | 字节流上传 | - |
+| `area` | 地址选择器 | - |
+| `richText` | 富文本编辑器 | - |
+| `deptSelect` | 科室选择 | - |
+| `orgSelect` | 机构选择 | - |
+| `inputoption` | 输入框+下拉框组合 | `optionname`, `options` |
+| `inputnumberoption` | 数字输入框+下拉框组合 | `optionname`, `options` |
+| `doubleValue` | 双输入框（如范围） | `firstLabel`, `secondLabel`, `separator` |
+
+### 4.5 ValidateConfig 验证配置
+
+```typescript
+interface ValidateConfig {
+  validateApi: string;              // 验证接口地址
+  validateFields: string[];         // 需要验证的字段名数组
+  validateMethod?: 'GET' | 'POST';  // 请求方法，默认 POST
+  validateParams?: (values: any) => any; // 自定义验证参数处理函数
+  validateMessage?: string;         // 验证失败提示，默认 "验证失败"
+  union?: boolean;                  // 是否联合验证，默认 true
+  realtime?: boolean;               // 是否实时验证，默认 false
+  realtimeDelay?: number;           // 实时验证防抖延迟（毫秒），默认 500
+  group?: string[][];               // 分组验证配置
 }
 ```
 
-### 项目结构要求
+### 4.6 Ref 暴露的方法
+
+```typescript
+interface CustomAddHandle {
+  setFieldsValue: (values: any) => void;  // 设置表单值
+  getFieldsValue: () => any;              // 获取表单值
+}
+```
+
+### 4.7 使用示例
+
+#### 4.7.1 基础使用
+
+```tsx
+import { useState, useRef } from 'react';
+import CustomAdd, { AddItemConfig } from '@/components/customComponents/CustomAdd';
+
+const Demo = () => {
+  const [visible, setVisible] = useState(false);
+  const [mode, setMode] = useState<'add' | 'edit' | 'view'>('add');
+  const [initialValues, setInitialValues] = useState<any>(null);
+  const addRef = useRef<any>(null);
+
+  const addFormConfig: AddItemConfig[] = [
+    {
+      type: 'input',
+      label: '姓名',
+      name: 'name',
+      rules: [{ required: true, message: '请输入姓名' }],
+      colSpan: 12,
+    },
+    {
+      type: 'InputNumber',
+      label: '年龄',
+      name: 'age',
+      colSpan: 12,
+    },
+    {
+      type: 'Radio',
+      label: '性别',
+      name: 'gender',
+      options: [
+        { label: '男', value: 1 },
+        { label: '女', value: 0 },
+      ],
+      colSpan: 12,
+      defaultValue: 1,
+    },
+    {
+      type: 'datePicker',
+      label: '出生日期',
+      name: 'birthDate',
+      dateFormat: 'YYYY-MM-DD',
+      colSpan: 12,
+    },
+    {
+      type: 'orgSelect',
+      label: '所属机构',
+      name: 'orgId',
+      rules: [{ required: true, message: '请选择机构' }],
+      colSpan: 12,
+    },
+    {
+      type: 'deptSelect',
+      label: '所属科室',
+      name: 'deptId',
+      colSpan: 12,
+    },
+    {
+      type: 'textarea',
+      label: '备注',
+      name: 'remark',
+      colSpan: 24,
+    },
+  ];
+
+  const handleOk = async (values: any) => {
+    console.log('提交的值:', values);
+    // 调用接口...
+    setVisible(false);
+  };
+
+  return (
+    <>
+      <Button onClick={() => { setMode('add'); setVisible(true); }}>
+        新增
+      </Button>
+
+      <CustomAdd
+        ref={addRef}
+        visible={visible}
+        mode={mode}
+        config={addFormConfig}
+        initialValues={initialValues}
+        onOk={handleOk}
+        onCancel={() => setVisible(false)}
+        loading={false}
+      />
+    </>
+  );
+};
+```
 
-组件使用路径别名 `@/` 来导入依赖。如果您的项目结构不同，需要：
+#### 4.7.2 分 Tab 使用
 
-1. 在 `tsconfig.json` 中配置路径别名：
-```json
+```tsx
+const tabFormConfig = [
+  {
+    label: '基本信息',
+    children: [
+      {
+        type: 'input',
+        label: '姓名',
+        name: 'name',
+        rules: [{ required: true, message: '请输入姓名' }],
+        colSpan: 12,
+      },
+      {
+        type: 'InputNumber',
+        label: '年龄',
+        name: 'age',
+        colSpan: 12,
+      },
+    ],
+  },
+  {
+    label: '详细信息',
+    children: [
+      {
+        type: 'textarea',
+        label: '个人简介',
+        name: 'bio',
+        colSpan: 24,
+      },
+    ],
+  },
+];
+
+<CustomAdd
+  visible={visible}
+  mode={mode}
+  config={tabFormConfig}
+  tab={true}  // 启用 Tab
+  onOk={handleOk}
+  onCancel={() => setVisible(false)}
+/>
+```
+
+#### 4.7.3 带验证配置
+
+```tsx
+const validateConfig: ValidateConfig = {
+  validateApi: '/api/user/validate',
+  validateFields: ['username', 'email'],
+  validateMethod: 'POST',
+  union: true,              // 联合验证
+  realtime: true,           // 实时验证
+  realtimeDelay: 500,       // 500ms 防抖
+  validateMessage: '字段重复',
+};
+
+<CustomAdd
+  visible={visible}
+  mode={mode}
+  config={addFormConfig}
+  validateConfig={validateConfig}
+  onOk={handleOk}
+  onCancel={() => setVisible(false)}
+/>
+```
+
+#### 4.7.4 特殊类型示例
+
+```tsx
+// 双输入框（范围）
 {
-  "compilerOptions": {
-    "paths": {
-      "@/*": ["src/*"]
-    }
-  }
+  type: 'doubleValue',
+  label: '价格范围',
+  name: 'priceRange',
+  firstLabel: 'minPrice',
+  secondLabel: 'maxPrice',
+  firstPlaceholder: '最低价',
+  secondPlaceholder: '最高价',
+  separator: '至',
+  lastUnit: '元',
+  colSpan: 24,
+}
+
+// 输入框+下拉框组合
+{
+  type: 'inputoption',
+  label: '剂量',
+  name: 'dosage',
+  optionname: 'dosageUnit',
+  options: [
+    { label: 'mg', value: 'mg' },
+    { label: 'g', value: 'g' },
+  ],
+  colSpan: 12,
+}
+
+// 日期范围（自动拆分为两个字段）
+{
+  type: 'rangePicker',
+  label: '有效期',
+  name: 'startDate/endDate',  // 会自动拆分为 startDate 和 endDate
+  dateFormat: 'YYYY-MM-DD',
+  colSpan: 12,
 }
 ```
 
-2. 确保以下文件存在：
-   - `src/api/common.ts` - 包含 `commonPost` 函数
-   - `src/utils/auth.ts` - 包含 `auth` 对象
-   - `src/utils/request.ts` - 包含 `post` 和 `get` 函数
-   - `src/utils/pycode.ts` - 包含拼音转换函数
-   - `src/api/table.ts` - 包含表格配置相关的 API 函数
+---
+
+## 5. 常见使用场景
+
+### 5.1 完整的 CRUD 页面
+
+```tsx
+import { useRef } from 'react';
+import CommonPage from '@/components/customComponents/commonPage';
 
-### 业务组件依赖
+const UserManagePage = () => {
+  const pageRef = useRef<any>(null);
 
-组件还依赖以下业务组件（如果使用相关功能）：
-- `AreaSelector` - 地址选择器
-- `ImageUploadComponent` - 图片上传组件
-- `FileUploadComponent` - 文件上传组件
-- `RichText` - 富文本编辑器
+  const searchFormConfig = [
+    { type: 'input', label: '用户名', name: 'username', colSpan: 6 },
+    { type: 'input', label: '手机号', name: 'phone', colSpan: 6 },
+    { 
+      type: 'select', 
+      label: '状态', 
+      name: 'status', 
+      options: [
+        { label: '启用', value: 1 },
+        { label: '禁用', value: 0 },
+      ],
+      colSpan: 6,
+    },
+  ];
 
-如果您的项目中没有这些组件，需要：
-1. 创建对应的组件，或
-2. 在表单配置中避免使用相关类型（`area`、`upload`、`file`、`richText`）
+  const addFormConfig = [
+    { 
+      type: 'input', 
+      label: '用户名', 
+      name: 'username', 
+      rules: [{ required: true, message: '请输入用户名' }],
+      colSpan: 12,
+    },
+    { 
+      type: 'password', 
+      label: '密码', 
+      name: 'password', 
+      rules: [{ required: true, message: '请输入密码' }],
+      colSpan: 12,
+    },
+    { type: 'input', label: '手机号', name: 'phone', colSpan: 12 },
+    { type: 'input', label: '邮箱', name: 'email', colSpan: 12 },
+    { 
+      type: 'Radio', 
+      label: '状态', 
+      name: 'status', 
+      options: [
+        { label: '启用', value: 1 },
+        { label: '禁用', value: 0 },
+      ],
+      defaultValue: 1,
+      colSpan: 12,
+    },
+  ];
 
-### 样式引入
+  const tableColumns = [
+    { title: '用户名', dataIndex: 'username', key: 'username', width: 150 },
+    { title: '手机号', dataIndex: 'phone', key: 'phone', width: 150 },
+    { title: '邮箱', dataIndex: 'email', key: 'email', width: 200 },
+    { 
+      title: '状态', 
+      dataIndex: 'status', 
+      key: 'status', 
+      width: 100,
+      render: (text: number) => text === 1 ? '启用' : '禁用',
+    },
+    { title: '创建时间', dataIndex: 'createTime', key: 'createTime', width: 180 },
+  ];
 
-请确保在使用组件前引入样式文件。有两种方式：
+  const URL = {
+    search: '/api/user/list',
+    add: '/api/user/add',
+    edit: '/api/user/edit',
+    delete: '/api/user/delete',
+  };
+
+  return (
+    <CommonPage
+      ref={pageRef}
+      searchFormConfig={searchFormConfig}
+      addFormConfig={addFormConfig}
+      tableColumns={tableColumns}
+      URL={URL}
+      tableId="user-management-table"
+      isReset={true}
+    />
+  );
+};
+```
+
+### 5.2 自定义操作列
 
-**方式1（推荐）：**
 ```tsx
-import 'gzkx-package/dist/style.css';
+<CommonPage
+  searchFormConfig={searchFormConfig}
+  addFormConfig={addFormConfig}
+  tableColumns={tableColumns}
+  URL={URL}
+  CustomOperations={(record) => (
+    <>
+      <a onClick={() => handleResetPassword(record)}>重置密码</a>
+      <a onClick={() => handleAssignRole(record)}>分配角色</a>
+    </>
+  )}
+/>
 ```
 
-**方式2：**
+### 5.3 带权限控制
+
 ```tsx
-import 'gzkx-package/style';
+<CommonPage
+  searchFormConfig={searchFormConfig}
+  addFormConfig={addFormConfig}
+  tableColumns={tableColumns}
+  URL={URL}
+  limit={{
+    addLimit: hasPermission('user:add'),
+    editLimit: hasPermission('user:edit'),
+    delLimit: hasPermission('user:delete'),
+    searchLimit: true,
+  }}
+/>
 ```
 
-**注意：** 如果遇到样式文件找不到的错误，请使用方式1直接引入 `dist/style.css`。
+---
 
-## 开发
+## 6. 注意事项
 
-```bash
-# 安装依赖
-npm install
+### 6.1 表单字段命名
+
+1. **日期范围字段**：使用 `/` 分隔，如 `startDate/endDate`，组件会自动拆分为两个字段。
+2. **输入框+下拉框组合**：使用 `name` 和 `optionname` 分别定义两个字段。
+3. **双输入框**：使用 `firstLabel` 和 `secondLabel` 定义两个字段名。
+
+### 6.2 数据格式
+
+1. **日期数据**：后端返回的日期字符串会自动转换为 dayjs 对象，提交时根据 `dateFormat` 格式化。
+2. **树形选择多选**：多选时，后端返回逗号分隔的字符串（如 "1,2,3"），组件会自动转换为数组。
+
+### 6.3 性能优化
+
+1. **tableId**：为表格设置唯一 ID，用户的列配置会保存到后端，避免每次都重新配置。
+2. **防抖**：组件内部已对列表刷新、实时验证等操作做了防抖处理。
 
-# 开发模式
-npm run dev
+### 6.4 样式定制
 
-# 构建库
-npm run build:lib
+组件使用了 CSS Modules，如需定制样式，可以：
+1. 通过 `className` 传入自定义类名
+2. 通过 `style` 传入内联样式
+3. 修改组件的 `.less` 文件
 
-# 发布到 npm
-npm publish
+---
+
+## 7. 常见问题
+
+### Q1: 如何在表单提交前进行自定义验证？
+
+使用 `validateConfig` 配置，指定验证接口和字段：
+
+```tsx
+const validateConfig = {
+  validateApi: '/api/validate',
+  validateFields: ['username'],
+  realtime: true,
+};
 ```
 
-## License
+### Q2: 如何实现联动选择（如省市区）？
+
+1. 在 `CustomForm` 中使用 `onSearchFormChange` 监听字段变化
+2. 在 `CustomAdd` 中使用 `oneditFormChange` 监听字段变化
+
+```tsx
+<CustomAdd
+  oneditFormChange={(changedValues, allValues) => {
+    if (changedValues.provinceId) {
+      // 加载对应的城市列表
+      loadCities(changedValues.provinceId);
+    }
+  }}
+/>
+```
+
+### Q3: 如何获取/设置表单值？
+
+使用 `ref` 调用组件方法：
+
+```tsx
+const formRef = useRef<any>(null);
+
+// 获取值
+const values = formRef.current?.getFieldsValue();
+
+// 设置值
+formRef.current?.setFieldsValue({ name: '张三' });
+```
+
+### Q4: 查看模式如何支持双击复制？
+
+`CustomAdd` 组件在 `view` 模式下，大部分字段支持双击复制功能，会自动将字段值复制到剪贴板。
+
+### Q5: 如何实现表格行高亮选中？
+
+在 `CommonPage` 中，点击的行会自动高亮，通过 `currentRecord` 状态和 `rowClassName` 实现。
+
+---
+
+## 8. 更新日志
+
+- **2025-11-24**: CustomTable 添加了表格配置保存功能
+- **2025-04-27**: CommonPage 组件创建
+- **2025-04-23**: CustomTable 组件创建
+
+---
+
+## 9. 技术支持
 
-MIT
+如有问题，请联系开发团队或查看源代码注释。