@cqsjjb/jjb-react-admin-component 3.2.0-rc.1 → 3.3.0-beta.0

package/ListDataContainer/index.d.ts

@@ -0,0 +1,190 @@
+
+import React, { ReactNode, ReactElement, RefAttributes } from 'react';
+import { TableProps, FormItemProps } from 'antd';
+import { OverTableProps } from '../Table';
+
+/**
+ * 基础表单项组件的通用类型约束
+ * 描述：定义搜索表单中所有表单项组件（如 Select、Input、DatePicker 等）的公共属性，
+ * 确保不同类型的表单项都能兼容「清除、占位符、子元素」等基础能力
+ * @type {BaseFieldComponent}
+ */
+type BaseFieldComponent = React.ComponentType<{
+    /** 是否支持清空选中值/输入值（通用表单项能力） */
+    allowClear?: boolean;
+    /** 输入/选择提示文本（提升用户体验） */
+    placeholder?: string;
+    /** 组件的子元素（如 Select.Option、DatePicker 的下拉内容等） */
+    children?: ReactNode;
+    /** 兼容组件的自定义属性（如 Select 的 options、Input 的 maxLength 等，避免类型约束过死） */
+    [key: string]: any;
+}>;
+
+/**
+ * 搜索表单单个配置项的接口
+ * 描述：用于定义搜索表单中每一个表单项的完整配置，包括组件类型、字段名、校验规则等，
+ * 组件内部会根据该配置自动生成对应的 Form.Item 结构
+ * 
+ * @interface SearchFormItemConfig
+ */
+export interface SearchFormItemConfig {
+    /** 表单项的核心组件（如 Select、Input、DatePicker 等，需符合 BaseFieldComponent 类型） */
+    field: BaseFieldComponent;
+    /** 表单项对应的表单字段名（与 form.validateFields() 返回的键名一致，用于数据提交） */
+    name: string;
+    /** 表单项的标签文本（显示在输入组件左侧，用于用户识别） */
+    label: string;
+    /** 传递给表单项组件的自定义属性（如 Select 的 options、Input 的 disabled 等） */
+    fieldProps?: Record<string, any>;
+    /** 传递给 antd Form.Item 的自定义属性（如 rules、hasFeedback、className 等） */
+    itemProps?: FormItemProps & Record<string, any>;
+    /** 表单项组件的子元素（如 Select.Option 列表、Radio.Group 的 Radio 按钮等） */
+    content?: ReactNode;
+    /** 是否为必填项（为 true 时，组件内部会自动添加「必填校验规则」和「*」标记） */
+    required?: boolean;
+    /** 兼容其他未明确列举的自定义属性（如 Form.Item 的 extra 提示文本等，预留扩展能力） */
+    [key: string]: any;
+}
+
+/**
+ * ListDataContainer 组件的 Props 接口
+ * 描述：定义通用列表容器组件的所有可配置属性，支持表格类型切换、搜索表单配置、分页初始值等，
+ * 通过泛型 T 关联「表格类型」和「表格属性」，确保类型一致性
+ * 
+ * @interface ListDataContainerProps
+ * @template T - 表格类型开关（true = 使用 ProTable；false = 使用 antd 原生 Table，默认 false）
+ */
+export interface ListDataContainerProps<T extends boolean = false> {
+    /**
+     * 表格列配置
+     * 描述：遵循 antd Table 组件的 columns 规范（即使使用 ProTable，列配置结构也与 antd 一致），
+     * 用于定义表格的列名、数据映射、渲染逻辑等
+     * @type {TableProps<any>['columns']}
+     */
+    columns: TableProps<any>['columns'];
+
+    /**
+     * 数据请求接口函数
+     * 描述：组件内部会调用该函数获取表格数据，需返回包含「列表数据」和「总数」的 Promise，
+     * 参数自动携带「分页信息」和「搜索表单值」，支持外部传入参数覆盖
+     * 
+     * @param {Object} params - 请求参数（分页参数 + 搜索表单参数 + 外部覆盖参数）
+     * @param {number} params.page - 当前页码（由组件内部分页状态维护）
+     * @param {number} params.pageSize - 每页条数（由组件内部分页状态维护）
+     * @param {any} params[key] - 搜索表单字段（与 searchFormConfig 中的 name 对应）
+     * @returns {Promise<Object>} 数据响应（需包含 list 和 total 字段）
+     * @returns {Array} response.data.list - 表格数据源数组
+     * @returns {number} response.data.total - 数据总数（用于分页计算）
+     */
+    fetchDataApi: (params: {
+        page: number;
+        pageSize: number;
+        [key: string]: any;
+    }) => Promise<{
+        data: {
+            list: any[];
+            total: number;
+            [key: string]: any;
+        };
+        [key: string]: any;
+    }>;
+
+    /**
+     * 搜索表单配置数组
+     * 描述：由 SearchFormItemConfig 类型的配置项组成，组件内部会根据该数组自动生成搜索表单，
+     * 不传递则不显示搜索表单
+     * @type {SearchFormItemConfig[]}
+     * @optional
+     */
+    searchFormConfig?: SearchFormItemConfig[];
+
+    /**
+     * 表格行的唯一标识字段名
+     * 描述：用于 antd Table/ProTable 的 rowKey 属性，确保表格行的唯一性（避免渲染警告），
+     * 默认值为 'id'（若数据的唯一标识字段不是 id，需手动传递）
+     * @type {string}
+     * @default 'id'
+     * @optional
+     */
+    rowKey?: string;
+
+    /**
+     * 初始分页配置
+     * 描述：定义表格初始的分页状态（如默认页码、每页条数、是否显示分页控件等），
+     * 基于 antd Table 的 pagination 类型扩展，确保分页能力符合通用需求
+     * 
+     * @type {TableProps<any>['pagination'] & Object}
+     * @property {number} [current=1] - 默认当前页码
+     * @property {number} [pageSize=10] - 默认每页条数
+     * @property {boolean} [showSizeChanger=true] - 是否显示「条数切换」控件（如 10/20/50 条）
+     * @property {boolean} [showQuickJumper=true] - 是否显示「快速跳转」输入框
+     * @property {Function} [showTotal] - 总数显示文案（如 (total) => `共 ${total} 条`）
+     * @optional
+     */
+    initialPagination?: TableProps<any>['pagination'] & {
+        current?: number;
+        pageSize?: number;
+        showSizeChanger?: boolean;
+        showQuickJumper?: boolean;
+        showTotal?: (total: number) => ReactNode;
+    };
+
+    /**
+     * 表格组件的自定义属性
+     * 描述：根据 proTable 开关动态匹配对应的表格属性类型，支持覆盖组件内部的默认配置（如 loading、pagination 等）
+     * - 当 proTable={true} 时：支持 OverTableProps（项目自定义 ProTable 的所有属性）
+     * - 当 proTable={false} 时：支持 TableProps（antd 原生 Table 的所有属性）
+     * 
+     * @type {T extends true ? OverTableProps<any> : TableProps<any>}
+     * @optional
+     * @example
+     */
+    tableProps?: T extends true
+    ? OverTableProps<any>  // ProTable 专属属性（如 search、toolBar 等）
+    : TableProps<any>;    // antd 原生 Table 属性（如 bordered、scroll 等）
+
+    /**
+     * 表格类型切换开关
+     * 描述：控制组件内部使用「项目自定义 ProTable」还是「antd 原生 Table」，
+     * 泛型 T 会自动根据该值推断，确保 tableProps 类型匹配
+     * 
+     * @type {T}
+     * @default false - 默认使用 antd 原生 Table
+     * @optional
+     */
+    proTable?: T;
+}
+
+/**
+ * ListDataContainer 组件通过 ref 暴露的方法接口
+ * 描述：组件内部通过 useImperativeHandle 暴露的方法，允许父组件调用以实现「数据刷新」等能力
+ * 
+ * @interface ListDataContainerExposedMethods
+ */
+export interface ListDataContainerExposedMethods {
+    /**
+     * 数据刷新方法
+     * 描述：触发表格数据重新请求，支持传入参数覆盖默认的「分页+搜索」参数，
+     * 适用于父组件主动刷新数据（如弹窗关闭后刷新列表）
+     * 
+     * @param {Record<string, any>} [overrideParams] - 覆盖请求的参数（如 { status: 1, type: 2 }）
+     * @returns {Promise<void>} - 数据请求完成的 Promise（可用于等待刷新结束）
+     */
+    loadDataSource: (overrideParams?: Record<string, any>) => Promise<void>;
+}
+
+/**
+ * 通用列表数据容器组件声明
+ * 描述：泛型组件，整合「搜索表单 + 表格 + 分页 + 数据请求」的完整列表解决方案，
+ * 支持切换表格类型，暴露刷新方法，适用于项目中各类列表页面（如数据管理、列表查询等）
+ * 
+ * @component ListDataContainer
+ * @template T - 表格类型开关（true = ProTable；false = antd Table，默认 false）
+ * @param {ListDataContainerProps<T> & RefAttributes<ListDataContainerExposedMethods>} props - 组件 props
+ * @returns {ReactElement} - 列表容器组件的 React 元素
+ */
+declare const ListDataContainer: <T extends boolean = false>(
+    props: ListDataContainerProps<T> & RefAttributes<ListDataContainerExposedMethods>
+) => ReactElement;
+
+export default ListDataContainer;

package/ListDataContainer/index.js

@@ -0,0 +1,205 @@
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+import React, { useState, useEffect, useCallback, useImperativeHandle, forwardRef } from 'react';
+import { Table, Row, Col, Form } from 'antd';
+import { isEqual } from 'lodash';
+import SearchForm from '../SearchForm';
+import ProTable from '../Table';
+
+/**
+ * @component ListDataContainer
+ * @description 通用列表数据容器组件，提供搜索表单、数据表格、分页等功能的完整列表页面解决方案
+ * 
+ * @props {Array} columns - 表格列配置，遵循Ant Design Table组件的columns规范
+ * @props {Function} fetchDataApi - 数据获取API函数，接收分页和搜索参数，返回包含list和total的对象
+ * @props {Array} searchFormConfig - 搜索表单配置数组
+ *   @param {React.Component} searchFormConfig[].field - 表单项组件(如ControlWrapper.Select)
+ *   @param {string} searchFormConfig[].name - 表单项字段名
+ *   @param {string} searchFormConfig[].label - 表单项标签
+ *   @param {Object} searchFormConfig[].fieldProps - 传递给字段组件的属性
+ *   @param {Object} searchFormConfig[].itemProps - 传递给Form.Item的属性
+ *   @param {React.ReactNode} searchFormConfig[].content - 字段组件的子元素(如Select.Option列表)
+ *   @param {boolean} searchFormConfig[].required - 是否必填
+ * @props {string} rowKey - 表格行键值，默认为'id'
+ * @props {Object} initialPagination - 初始分页配置，包含current、pageSize等分页属性
+ * @props {Object} tableProps - 传递给Table组件的属性
+ * @props {boolean} proTable - 是否使用ProTable组件，默认为false
+ * @example
+ * // 基础用法
+ * <ListDataContainer
+ *   columns={tableColumns}
+ *   fetchDataApi={getCourseList}
+ *   searchFormConfig={[
+ *     {
+ *       field: Select,
+ *       name: 'status',
+ *       label: '状态',
+ *     }
+ *     {
+ *       field: Input,
+ *       name: 'name',
+ *       label: '名称',
+ *       required: true,
+ *     }
+ *   ]}
+ * />
+ * 
+ */
+
+const SELECT_COMPONENTS = ['Select', 'TreeSelect', 'Cascader', 'DatePicker', 'TimePicker', 'Checkbox', 'Radio', 'Switch', 'Slider', 'Upload'];
+const INPUT_COMPONENTS = ['Input', 'InputNumber'];
+const ListDataContainer = /*#__PURE__*/forwardRef(({
+  columns,
+  fetchDataApi,
+  searchFormConfig = [],
+  rowKey = 'id',
+  initialPagination = {
+    current: 1,
+    pageSize: 10,
+    showSizeChanger: true,
+    showQuickJumper: true,
+    showTotal: total => `共 ${total} 条记录`
+  },
+  tableProps = {},
+  proTable = false
+}, ref) => {
+  const [form] = Form.useForm();
+  const [tableData, setTableData] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [pagination, setPagination] = useState(initialPagination);
+  const [totalCount, setTotalCount] = useState(0);
+  const getComponentName = Component => {
+    return Component.displayName || Component.constructor.name;
+  };
+
+  /**
+   * 数据加载与刷新方法
+   * @param {Object} [overrideParams={}] - 可选，用于覆盖内部参数的键值对
+   *   若传入，会覆盖同名的表单参数和分页参数（如page、pageSize或搜索字段）
+   */
+  const loadDataSource = useCallback(async (overrideParams = {}) => {
+    if (!fetchDataApi) return;
+    setLoading(true);
+    try {
+      // 1. 获取组件内部的表单参数
+      const formValues = await form.validateFields();
+
+      // 2. 构造基础参数：分页参数 + 表单参数
+      const baseParams = {
+        page: pagination.current,
+        pageSize: pagination.pageSize,
+        ...formValues
+      };
+
+      // 3. 用外部传入的参数覆盖基础参数（同名参数以外部为准）
+      const requestParams = {
+        ...baseParams,
+        ...overrideParams
+      };
+
+      // 4. 发起请求
+      const response = await fetchDataApi(requestParams);
+      setTableData(response.data.list || []);
+      setTotalCount(response.data.total || 0);
+    } catch (error) {
+      console.error('列表数据请求失败：', error);
+      setTableData([]);
+      setTotalCount(0);
+    } finally {
+      setLoading(false);
+    }
+  }, [fetchDataApi, pagination, form]);
+
+  // 暴露刷新方法给父组件
+  useImperativeHandle(ref, () => ({
+    // 外部调用时可传入覆盖参数
+    loadDataSource: (overrideParams = {}) => loadDataSource(overrideParams)
+  }));
+  const handleFinish = values => {
+    // 搜索时重置到第一页，并用表单值覆盖（values会合并到baseParams中）
+    setPagination(prev => ({
+      ...prev,
+      current: 1
+    }));
+    loadDataSource(values);
+  };
+  const handleReset = () => {
+    // 清空表单
+    form.setFieldsValue(searchFormConfig.reduce((obj, item) => {
+      obj[item.name] = undefined;
+      return obj;
+    }, {}));
+    // 重置分页并使用内部默认参数查询
+    setPagination(initialPagination);
+    loadDataSource();
+  };
+  const handlePaginationChange = newPagination => {
+    // 更新分页后，用新分页参数查询
+    setPagination(newPagination);
+  };
+
+  // 分页变化时自动重新加载
+  useEffect(() => {
+    // 避免初始加载时重复调用，判断两个对象是否相等
+    if (!isEqual(pagination, initialPagination)) {
+      loadDataSource();
+    }
+  }, [pagination, loadDataSource]);
+  const generateFormItems = () => {
+    return searchFormConfig.map((item, index) => {
+      const {
+        field: FieldComponent,
+        name,
+        label,
+        required,
+        fieldProps = {},
+        itemProps = {},
+        content,
+        ...restProps
+      } = item;
+      return /*#__PURE__*/React.createElement(Form.Item, _extends({
+        key: `search-item-${name}-${index}`,
+        name: name,
+        label: label
+      }, required ? {
+        required: true,
+        rules: [{
+          required: true,
+          message: `${SELECT_COMPONENTS.includes(getComponentName(FieldComponent)) ? '请选择' : '请输入'}${label}`
+        }]
+      } : {}, itemProps, restProps), /*#__PURE__*/React.createElement(FieldComponent, _extends({
+        allowClear: true,
+        placeholder: `${SELECT_COMPONENTS.includes(getComponentName(FieldComponent)) ? '请选择' : '请输入'}${label}`
+      }, fieldProps), content || null));
+    }).filter(Boolean);
+  };
+  const TableComponent = proTable ? ProTable : Table;
+  return /*#__PURE__*/React.createElement(Row, {
+    gutter: [16, 24]
+  }, /*#__PURE__*/React.createElement(Col, {
+    span: 24
+  }, /*#__PURE__*/React.createElement(SearchForm, {
+    expand: true,
+    form: form,
+    loading: loading,
+    formLine: generateFormItems(),
+    onReset: handleReset,
+    onFinish: handleFinish
+  })), /*#__PURE__*/React.createElement(Col, {
+    span: 24
+  }, /*#__PURE__*/React.createElement(TableComponent, _extends({
+    columns: columns,
+    dataSource: tableData,
+    rowKey: rowKey,
+    loading: loading,
+    pagination: {
+      ...pagination,
+      total: totalCount
+    },
+    onChange: handlePaginationChange,
+    scroll: {
+      x: 'max-content'
+    },
+    bordered: true
+  }, tableProps))));
+});
+export default ListDataContainer;

package/Table/index.d.ts

@@ -3,7 +3,7 @@ import * as React from 'react';
 // @ts-ignore
 import type { TableProps } from 'antd';
 
-interface OverTableProps extends TableProps {
+export interface OverTableProps extends TableProps {
   // 是否禁用内容区滚动，默认-false
   disabledResizer?: boolean;
   // 当一个路由下存在多个表格的情况下 需要给每一个表格设置一个唯一存储索引 若没有设置则使用默认索引，请注意缓存数据会被覆盖

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cqsjjb/jjb-react-admin-component",
-  "version": "3.2.0-rc.1",
+  "version": "3.3.0-beta.0",
   "description": "jjb-react-admin-组件库@new",
   "main": "index.js",
   "author": "jjb-front-team",
@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "axios": "^1.6.5",
+    "lodash": "^4.17.21",
     "spark-md5": "^3.0.2",
     "cropperjs": "^1.6.2",
     "@wangeditor-next/editor": "latest",

package/ControlWrapper/index.less

@@ -1,38 +0,0 @@
-@com-prefix-cls: if(isdefined(@ant-prefix), @ant-prefix, ant);
-
-.@{com-prefix-cls}-form-item-control-label-wrapper {
-  .@{com-prefix-cls}-form-item-control-label-span {
-    border: 1px solid #d9d9d9;
-    height: 32px;
-    line-height: 30px;
-    box-sizing: border-box;
-    margin-right: -1px;
-    padding: 0 2px 0 8px;
-    border-top-left-radius: 4px;
-    border-bottom-left-radius: 4px;
-    white-space: nowrap;
-  }
-
-  &.@{com-prefix-cls}-form-item-control-label-has {
-    .@{com-prefix-cls}-select-selector, .@{com-prefix-cls}-picker, .@{com-prefix-cls}-input, .@{com-prefix-cls}-input-affix-wrapper {
-      border-top-left-radius: 0;
-      border-bottom-left-radius: 0;
-      border-left-color: transparent !important;
-      &:hover, &:focus, &:focus-within{
-        border-left-color: @colorPrimary !important;
-      }
-    }
-  }
-
-  &-default {
-    .@{com-prefix-cls}-form-item-control-label-span {
-      border-color: #d9d9d9;
-    }
-  }
-
-  &-dark {
-    .@{com-prefix-cls}-form-item-control-label-span {
-      border-color: #424242;
-    }
-  }
-}