zy-react-library 1.0.0

package/README.md

@@ -0,0 +1,14 @@
+# zy-react-library
+
+## 📦 安装
+
+```bash
+# yarn
+yarn add zy-react-library
+```
+
+## 📄 更新日志
+
+### v1.0.0 (2025-10-22)
+
+- 🎉 初始版本发布

package/components/FormBuilder/FormBuilder.d.ts

@@ -0,0 +1,31 @@
+import type { FormInstance, FormProps } from "antd/es/form";
+import type { Gutter } from "antd/es/grid/row";
+import type { FC } from "react";
+import type { FormOption, FormValues } from "./FormItemsRenderer";
+
+/**
+ * FormBuilder 组件属性
+ */
+export interface FormBuilderProps extends Omit<FormProps, "form"> {
+  /** 表单初始值 */
+  values?: FormValues;
+  /** 表单配置项数组 */
+  options: FormOption[];
+  /** 栅格间距，默认 24 */
+  gutter?: Gutter | [Gutter, Gutter];
+  /** 占据栅格列数，默认 12 */
+  span?: number | string;
+  /** 表单实例（通过 Form.useForm() 创建） */
+  form: FormInstance;
+  /** 自动生成必填规则，默认 true */
+  useAutoGenerateRequired?: boolean;
+  /** 表单提交回调 */
+  onFinish?: (values: any) => void;
+}
+
+/**
+ * 表单构建器组件
+ */
+declare const FormBuilder: FC<FormBuilderProps>;
+
+export default FormBuilder;

package/components/FormBuilder/FormBuilder.js

@@ -0,0 +1,41 @@
+import { Form, Row } from "antd";
+import FormItemsRenderer from "./FormItemsRenderer";
+
+/**
+ * 表单构建器组件
+ */
+const FormBuilder = (props) => {
+  const {
+    values,
+    options,
+    gutter = 24,
+    span = 12,
+    labelCol = { span: 4 },
+    onFinish,
+    useAutoGenerateRequired = true,
+    ...restProps
+  } = props;
+
+  return (
+    <Form
+      labelCol={labelCol}
+      scrollToFirstError
+      wrapperCol={{ span: 24 - labelCol.span }}
+      onFinish={onFinish}
+      initialValues={values}
+      {...restProps}
+    >
+      <Row gutter={gutter}>
+        <FormItemsRenderer
+          options={options}
+          span={span}
+          useAutoGenerateRequired={useAutoGenerateRequired}
+        />
+      </Row>
+    </Form>
+  );
+};
+
+FormBuilder.displayName = "FormBuilder";
+
+export default FormBuilder;

package/components/FormBuilder/FormItemsRenderer.d.ts

@@ -0,0 +1,107 @@
+import type { ColProps } from "antd/es/col";
+import type { FormItemProps, Rule } from "antd/es/form";
+import type { NamePath } from "rc-field-form/lib/interface";
+import type { FC, ReactNode } from "react";
+import type { FORM_ITEM_RENDER_ENUM } from "../../enum/formItemRender";
+
+/**
+ * 表单项渲染类型
+ */
+export type FormItemRenderType
+  = | (typeof FORM_ITEM_RENDER_ENUM)[keyof typeof FORM_ITEM_RENDER_ENUM]
+    | ((props: any) => ReactNode);
+
+/**
+ * 选项项数据类型
+ */
+export interface OptionItem {
+  /** 值字段 */
+  value?: any;
+  /** 标签字段 */
+  label?: string;
+  /** 字典ID */
+  dictionariesId?: any;
+  /** ID字段 */
+  id?: any;
+  /** 名称字段 */
+  name?: string;
+  [key: string]: any;
+}
+
+/**
+ * 字段键配置
+ */
+export interface itemsFieldConfig {
+  /** 值字段的键名，默认为 'value' */
+  valueKey?: string;
+  /** 标签字段的键名，默认为 'label' */
+  labelKey?: string;
+}
+
+/**
+ * 表单值类型
+ */
+export type FormValues = Record<string, any>;
+
+/**
+ * 表单配置项
+ */
+export interface FormOption {
+  /** 表单项字段名 */
+  name?: string | string[];
+  /** 表单项标签 */
+  label?: ReactNode;
+  /** 渲染类型 */
+  render?: FormItemRenderType;
+  /** 占据栅格列数，默认 12 */
+  span?: number | string;
+  /** 是否必填，默认 true，支持函数动态计算 */
+  required?: boolean | ((formValues: FormValues) => boolean);
+  /** 验证规则 */
+  rules?: Rule | Rule[];
+  /** 占位符文本，默认会根据传入的 render 类型自动判断（请选择、请输入）和 label 组合 */
+  placeholder?: ReactNode;
+  /** 提示信息，传入将在 label 右侧生成图标展示 tooltip */
+  tip?: ReactNode;
+  /** 是否隐藏，默认 false，支持函数动态计算 */
+  hidden?: boolean | ((formValues: FormValues) => boolean);
+  /** 是否自定义渲染，默认 false，将不生成 Col 和 Form.Item（ 仅生效 render、items、itemsField、componentProps ） */
+  customizeRender?: boolean;
+  /** 选项数据（用于 select、radio、checkbox） */
+  items?: OptionItem[];
+  /** 字段键配置 */
+  itemsField?: itemsFieldConfig;
+  /** 传递给表单控件的属性，支持函数动态计算 */
+  componentProps?: Record<string, any> | ((formValues: FormValues) => Record<string, any>);
+  /** 传递给 Form.Item 的属性，支持函数动态计算 */
+  formItemProps?: FormItemProps | ((formValues: FormValues) => FormItemProps);
+  /** label 栅格配置 */
+  labelCol?: ColProps;
+  /** wrapper 栅格配置 */
+  wrapperCol?: ColProps;
+  /** 是否应该更新（用于表单联动） */
+  shouldUpdate?: boolean | ((prevValues: FormValues, nextValues: FormValues, info: { source?: string }) => boolean);
+  /** 依赖字段（用于表单联动） */
+  dependencies?: NamePath[];
+}
+
+/**
+ * FormItemsRenderer 组件属性
+ */
+export interface FormItemsRendererProps {
+  /** 表单配置项数组 */
+  options: FormOption[];
+  /** 默认栅格占据列数，默认 12 */
+  span?: number;
+  /** 是否折叠（仅显示前3项），默认 false */
+  collapse?: boolean;
+  /** 自动生成必填规则，默认 true */
+  useAutoGenerateRequired?: boolean;
+}
+
+/**
+ * 表单项渲染器组件
+ */
+declare const FormItemsRenderer: FC<FormItemsRendererProps>;
+
+export default FormItemsRenderer;

package/components/FormBuilder/FormItemsRenderer.js

@@ -0,0 +1,345 @@
+import { InfoCircleOutlined } from "@ant-design/icons";
+import {
+  Checkbox,
+  Col,
+  DatePicker,
+  Divider,
+  Form,
+  Input,
+  InputNumber,
+  Radio,
+  Select,
+  Tooltip,
+} from "antd";
+import dayjs from "dayjs";
+import { FORM_ITEM_RENDER_ENUM } from "../../enum/formItemRender";
+
+const { TextArea } = Input;
+const { RangePicker } = DatePicker;
+
+/**
+ * 表单项渲染器组件
+ */
+const FormItemsRenderer = ({
+  options,
+  span = 12,
+  collapse = false,
+  useAutoGenerateRequired = true,
+}) => {
+  const form = Form.useFormInstance();
+
+  // 获取传给组件的属性
+  const getComponentProps = (option) => {
+    return typeof option.componentProps === "function"
+      ? option.componentProps(form.getFieldsValue())
+      : (option.componentProps || {});
+  };
+
+  // 获取传给formItem的属性
+  const getFormItemProps = (option) => {
+    const formItemProps = typeof option.formItemProps === "function"
+      ? option.formItemProps(form.getFieldsValue())
+      : (option.formItemProps || {});
+
+    // 为日期组件添加特殊处理
+    if ([
+      FORM_ITEM_RENDER_ENUM.DATE,
+      FORM_ITEM_RENDER_ENUM.DATE_MONTH,
+      FORM_ITEM_RENDER_ENUM.DATE_YEAR,
+      FORM_ITEM_RENDER_ENUM.DATETIME,
+    ].includes(option.render)) {
+      formItemProps.getValueFromEvent = (_, dateString) => dateString;
+      formItemProps.getValueProps = value => ({ value: value ? dayjs(value) : undefined });
+    }
+
+    // 为日期周组件添加特殊处理
+    if ([
+      FORM_ITEM_RENDER_ENUM.DATE_WEEK,
+    ].includes(option.render)) {
+      formItemProps.getValueFromEvent = (_, dateString) => dateString;
+      formItemProps.getValueProps = value => ({ value: value ? dayjs(value, "YYYY-wo") : undefined });
+    }
+
+    // 为日期范围组件添加特殊处理
+    if ([
+      FORM_ITEM_RENDER_ENUM.DATE_RANGE,
+      FORM_ITEM_RENDER_ENUM.DATETIME_RANGE,
+    ].includes(option.render)) {
+      formItemProps.getValueFromEvent = (_, dateString) => dateString;
+      formItemProps.getValueProps = value => ({ value: Array.isArray(value) ? value.map(v => v ? dayjs(v) : undefined) : undefined });
+    }
+
+    return formItemProps;
+  };
+
+  // 获取items里的value和label字段key
+  const getItemsFieldKey = (option) => {
+    return {
+      valueKey: option?.itemsField?.valueKey || "value",
+      labelKey: option?.itemsField?.labelKey || "label",
+    };
+  };
+
+  // 获取验证规则
+  const getRules = (option) => {
+    if (!useAutoGenerateRequired)
+      return option.rules ? (Array.isArray(option.rules) ? option.rules : [option.rules]) : [];
+    if (option.render === FORM_ITEM_RENDER_ENUM.DIVIDER)
+      return [];
+
+    // 支持动态计算 required
+    const required = typeof option.required === "function"
+      ? option.required(form.getFieldsValue())
+      : (option.required || true);
+
+    if (required) {
+      const isBlurTrigger = !option.render || [
+        FORM_ITEM_RENDER_ENUM.INPUT,
+        FORM_ITEM_RENDER_ENUM.TEXTAREA,
+        FORM_ITEM_RENDER_ENUM.INPUT_NUMBER,
+        FORM_ITEM_RENDER_ENUM.NUMBER,
+      ].includes(option.render);
+
+      const rules = [
+        {
+          required: true,
+          message: `${isBlurTrigger ? "请输入" : "请选择"}${option.label}`,
+        },
+      ];
+
+      if (option.rules) {
+        if (Array.isArray(option.rules)) {
+          rules.push(...option.rules);
+        }
+        else {
+          rules.push(option.rules);
+        }
+      }
+      return rules;
+    }
+
+    return option.rules ? (Array.isArray(option.rules) ? option.rules : [option.rules]) : [];
+  };
+
+  // 渲染表单控件
+  const renderFormControl = (option) => {
+    const componentProps = getComponentProps(option);
+    const itemsFieldKey = getItemsFieldKey(option);
+    /** @type {string | Function} */
+    const render = option.render || FORM_ITEM_RENDER_ENUM.INPUT;
+    const placeholder = option.placeholder || `请${render === FORM_ITEM_RENDER_ENUM.SELECT || render === FORM_ITEM_RENDER_ENUM.RADIO || render === FORM_ITEM_RENDER_ENUM.CHECKBOX ? "选择" : "输入"}${option.label}`;
+
+    switch (render) {
+      case FORM_ITEM_RENDER_ENUM.INPUT:
+        return <Input placeholder={placeholder} {...componentProps} />;
+
+      case FORM_ITEM_RENDER_ENUM.TEXTAREA:
+        return <TextArea placeholder={placeholder} rows={3} {...componentProps} />;
+
+      case FORM_ITEM_RENDER_ENUM.INPUT_NUMBER:
+      case FORM_ITEM_RENDER_ENUM.NUMBER:
+        return <InputNumber placeholder={placeholder} style={{ width: "100%" }} {...componentProps} />;
+
+      case FORM_ITEM_RENDER_ENUM.SELECT:
+        return (
+          <Select placeholder={placeholder} {...componentProps}>
+            {(option.items || []).map((item) => {
+              const value = item[itemsFieldKey.valueKey] ?? item.dictionariesId ?? item.id;
+              const label = item[itemsFieldKey.labelKey] ?? item.name;
+              return (
+                <Select.Option key={value} value={value}>
+                  {label}
+                </Select.Option>
+              );
+            })}
+          </Select>
+        );
+
+      case FORM_ITEM_RENDER_ENUM.RADIO:
+        return (
+          <Radio.Group {...componentProps}>
+            {(option.items || []).map((item) => {
+              const value = item[itemsFieldKey.valueKey] ?? item.dictionariesId ?? item.id;
+              const label = item[itemsFieldKey.labelKey] ?? item.name;
+              return (
+                <Radio key={value} value={value}>
+                  {label}
+                </Radio>
+              );
+            })}
+          </Radio.Group>
+        );
+
+      case FORM_ITEM_RENDER_ENUM.CHECKBOX:
+        return (
+          <Checkbox.Group {...componentProps}>
+            {(option.items || []).map((item) => {
+              const value = item[itemsFieldKey.valueKey] ?? item.dictionariesId ?? item.id;
+              const label = item[itemsFieldKey.labelKey] ?? item.name;
+              return (
+                <Checkbox key={value} value={value}>
+                  {label}
+                </Checkbox>
+              );
+            })}
+          </Checkbox.Group>
+        );
+
+      case FORM_ITEM_RENDER_ENUM.DATE:
+        return <DatePicker placeholder={placeholder} format="YYYY-MM-DD" style={{ width: "100%" }} {...componentProps} />;
+
+      case FORM_ITEM_RENDER_ENUM.DATE_MONTH:
+        return <DatePicker picker="month" placeholder={placeholder} format="YYYY-MM" style={{ width: "100%" }} {...componentProps} />;
+
+      case FORM_ITEM_RENDER_ENUM.DATE_YEAR:
+        return <DatePicker picker="year" placeholder={placeholder} format="YYYY" style={{ width: "100%" }} {...componentProps} />;
+
+      case FORM_ITEM_RENDER_ENUM.DATE_WEEK:
+        return <DatePicker picker="week" placeholder={placeholder} format="YYYY-wo" style={{ width: "100%" }} {...componentProps} />;
+
+      case FORM_ITEM_RENDER_ENUM.DATE_RANGE:
+        return (
+          <RangePicker
+            placeholder={[`请选择开始${option.label}`, `请选择结束${option.label}`]}
+            format="YYYY-MM-DD"
+            style={{ width: "100%" }}
+            {...componentProps}
+          />
+        );
+
+      case FORM_ITEM_RENDER_ENUM.DATETIME:
+        return (
+          <DatePicker
+            showTime
+            placeholder={placeholder}
+            format="YYYY-MM-DD HH:mm:ss"
+            style={{ width: "100%" }}
+            {...componentProps}
+          />
+        );
+
+      case FORM_ITEM_RENDER_ENUM.DATETIME_RANGE:
+        return (
+          <RangePicker
+            showTime
+            placeholder={[`请选择开始${option.label}`, `请选择结束${option.label}`]}
+            format="YYYY-MM-DD HH:mm:ss"
+            style={{ width: "100%" }}
+            {...componentProps}
+          />
+        );
+
+      case FORM_ITEM_RENDER_ENUM.DIVIDER:
+        return null;
+
+      default:
+        // 支持传入自定义组件
+        if (typeof render === "function") {
+          const CustomComponent = render;
+          return <CustomComponent {...componentProps} />;
+        }
+        return <Input placeholder={placeholder} {...componentProps} />;
+    }
+  };
+
+  // 渲染 label（带提示）
+  const renderLabel = (option) => {
+    if (!option.tip)
+      return option.label;
+
+    return (
+      <>
+        {option.label}
+        <Tooltip title={option.tip}>
+          <InfoCircleOutlined style={{ marginLeft: 4, fontSize: 12 }} />
+        </Tooltip>
+      </>
+    );
+  };
+
+  return (
+    <>
+      {options.map((option, index) => {
+        const itemSpan = option.render === FORM_ITEM_RENDER_ENUM.DIVIDER ? 24 : option.span ?? span;
+        // 使用 style 控制显示/隐藏
+        const style = collapse && index >= 3 ? { display: "none" } : undefined;
+
+        // 如果是分割线
+        if (option.render === FORM_ITEM_RENDER_ENUM.DIVIDER) {
+          return (
+            <Col key={option.name || index} span={itemSpan} style={style}>
+              <Divider orientation="left">{option.label}</Divider>
+            </Col>
+          );
+        }
+
+        // 如果配置了 shouldUpdate 或 dependencies，使用 Form.Item 的联动机制
+        if (option.shouldUpdate || option.dependencies || option?.componentProps?.shouldUpdate || option?.componentProps?.dependencies) {
+          return (
+            option.customizeRender
+              ? (renderFormControl(option))
+              : (
+                  <Col key={option.name || index} span={itemSpan} style={style}>
+                    <Form.Item
+                      noStyle
+                      shouldUpdate={option.shouldUpdate || option?.componentProps?.shouldUpdate}
+                      dependencies={option.dependencies || option?.componentProps?.dependencies}
+                    >
+                      {(form) => {
+                      // 支持动态计算 hidden
+                        const hidden = typeof option.hidden === "function"
+                          ? option.hidden(form.getFieldsValue())
+                          : (option.hidden || false);
+
+                        if (hidden)
+                          return null;
+
+                        return (
+                          <Form.Item
+                            name={option.name}
+                            label={renderLabel(option)}
+                            rules={getRules(option)}
+                            labelCol={option.labelCol}
+                            wrapperCol={option.wrapperCol}
+                            {...getFormItemProps(option)}
+                          >
+                            {renderFormControl(option)}
+                          </Form.Item>
+                        );
+                      }}
+                    </Form.Item>
+                  </Col>
+                )
+          );
+        }
+
+        // 普通表单项（静态配置）
+        if (option.hidden)
+          return null;
+
+        return (
+          option.customizeRender
+            ? (renderFormControl(option))
+            : (
+                <Col key={option.name || index} span={itemSpan} style={style}>
+                  <Form.Item
+                    name={option.name}
+                    label={renderLabel(option)}
+                    rules={getRules(option)}
+                    labelCol={option.labelCol}
+                    wrapperCol={option.wrapperCol}
+                    {...getFormItemProps(option)}
+                  >
+                    {renderFormControl(option)}
+                  </Form.Item>
+                </Col>
+              )
+        );
+      })}
+    </>
+  );
+};
+
+FormItemsRenderer.displayName = "FormItemsRenderer";
+
+export default FormItemsRenderer;

package/components/FormBuilder/index.d.ts

@@ -0,0 +1,3 @@
+import FormBuilder from "./FormBuilder";
+
+export default FormBuilder;

package/components/FormBuilder/index.js

@@ -0,0 +1,3 @@
+import FormBuilder from "./FormBuilder";
+
+export default FormBuilder;

package/components/PreviewImg/index.d.ts

@@ -0,0 +1,12 @@
+import type { FC } from "react";
+
+export interface PreviewImgProps {
+  /** 图片列表 */
+  files: any[];
+  /** 图片地址的key，默认 filePath */
+  fileUrlKey?: string;
+}
+
+declare const PreviewImg: FC<PreviewImgProps>;
+
+export default PreviewImg;

package/components/PreviewImg/index.js

@@ -0,0 +1,26 @@
+import { Image } from "antd";
+import { getFileUrl } from "../../utils/index";
+
+const PreviewImg = (props) => {
+  const { files = [], fileUrlKey = "filePath" } = props;
+  const fileUrl = getFileUrl();
+
+  return (
+    <Image.PreviewGroup>
+      {
+        files.filter(Boolean).map((item, index) => (
+          <Image
+            key={item[fileUrlKey] || item}
+            src={item[fileUrlKey] ? fileUrl + item[fileUrlKey] : fileUrl + item}
+            style={{ marginLeft: index > 0 ? 10 : 0 }}
+            width={100}
+            height={100}
+            alt=""
+          />
+        ))
+      }
+    </Image.PreviewGroup>
+  );
+};
+
+export default PreviewImg;

package/components/Search/index.d.ts

@@ -0,0 +1,41 @@
+import type { FormInstance, FormProps } from "antd/es/form";
+import type { FC, ReactNode } from "react";
+import type { FormOption } from "../FormBuilder/FormItemsRenderer";
+
+type FormValues = Record<string, any>;
+
+/**
+ * Search 组件属性
+ */
+export interface SearchProps extends Omit<FormProps, "form" | "onFinish"> {
+  /** 表单配置项数组 */
+  options: FormOption[];
+  /** 表单值 */
+  values?: FormValues;
+  /** 搜索和重置都会触发的回调 */
+  onFinish?: (values: FormValues, type: "submit" | "reset") => void;
+  /** 搜索回调 */
+  onSubmit?: (values: FormValues) => void;
+  /** 重置回调 */
+  onReset?: (values: FormValues) => void;
+  /** 搜索按钮文本，默认"搜索" */
+  searchText?: string;
+  /** 重置按钮文本，默认"重置" */
+  resetText?: string;
+  /** 是否显示搜索按钮，默认 true */
+  showSearchButton?: boolean;
+  /** 是否显示重置按钮，默认 true */
+  showResetButton?: boolean;
+  /** 额外的底部按钮组 */
+  extraButtons?: ReactNode;
+  /** 表单实例（通过 Form.useForm() 创建） */
+  form: FormInstance;
+}
+
+/**
+ * 搜索表单组件
+ * 支持自动展开/收起功能，当表单项超过4个时显示展开/收起按钮
+ */
+declare const Search: FC<SearchProps>;
+
+export default Search;