zy-react-library/components/FormBuilder/FormItemsRenderer.d.ts

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 interface CustomRenderProps {
  /** 表单当前值 */
  formValues: FormValues;
  /** 字段值 */
  value?: any;
  /** 值变化回调 */
  onChange?: (value: any) => void;
  /** 其他属性 */
  [key: string]: any;
}

/**
 * 表单项渲染类型
 */
export type FormItemRenderType
  = | (typeof FORM_ITEM_RENDER_ENUM)[keyof typeof FORM_ITEM_RENDER_ENUM]
    | ((props: CustomRenderProps) => ReactNode);

/**
 * 选项项数据类型
 */
export interface OptionItem {
  /** ID字段 */
  id?: any;
  /** 名称字段 */
  name?: string;
  [key: string]: any;
}

/**
 * 字段键配置
 */
export interface itemsFieldConfig {
  /** 值字段的键名，默认为 'id' */
  valueKey?: string;
  /** 标签字段的键名，默认为 'name' */
  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，将不生成 Form.Item */
  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，如果 span 等于 24，是外层的 labelCol.span 一半 */
  labelCol?: ColProps;
  /** wrapper 栅格配置，默认为 24 - labelCol.span */
  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;
  /** 初始值，用于在表单未初始化时提供默认值 */
  initialValues?: FormValues;
}

/**
 * 表单项渲染器组件
 */
declare const FormItemsRenderer: FC<FormItemsRendererProps>;

export default FormItemsRenderer;