介绍
指南
API 文档
常见问题
介绍
指南
API 文档
常见问题

XinForm 表单

XinAdmin 提供了一系列增强型表单组件，基于 Ant Design 的 ProComponents 构建，旨在简化复杂表单的开发过程。这些组件不仅具有良好的用户体验，还集成了常见的业务逻辑和验证功能。

概述

XinAdmin 的表单系统主要包含两大部分：

  1. ProComponents 基础组件：基于 Ant Design ProComponents 的增强型表单组件
  2. XinFormField 自定义组件：针对特定业务场景封装的高级表单字段组件

XinFormField 组件

XinFormField 是 XinAdmin 提供的一系列高级表单字段组件，专为解决常见业务场景而设计。

图标选择器 (IconSelector)

图标选择器提供了一个可视化的图标选择界面，用户可以从多个分类中选择合适的图标。

使用示例：

import IconSelector from '@/components/XinFormField/IconSelector';

function MyComponent() {
  const [icon, setIcon] = useState('');

  return (
    <IconSelector
      value={icon}
      onChange={setIcon}
      placeholder="请选择图标"
    />
  );
}

属性说明：

属性 类型 说明 默认值
value string 当前选中的图标名称 -
onChange (value: string | null) => void 图标选择变化时的回调函数 -
placeholder string 选择框的占位符文本 "请选择图标"
disabled boolean 是否禁用 false
readonly boolean 是否只读 false

图片上传器 (ImageUploader)

图片上传器组件提供了一个易于使用的图片上传界面，支持单张或多张图片上传，并具备图片格式、大小和尺寸验证功能。

使用示例：

import ImageUploader from '@/components/XinFormField/ImageUploader';

function MyComponent() {
  const [images, setImages] = useState([]);

  return (
    <ImageUploader
      value={images}
      onChange={setImages}
      action="/api/upload/image"
      mode="multiple"
      maxCount={9}
      maxSize={5} // 5MB
      maxWidth={1920}
      maxHeight={1080}
    />
  );
}

属性说明：

属性 类型 说明 默认值
value ISysFileInfo[] 当前上传的图片列表 -
onChange (value: ISysFileInfo[]) => void 图片列表变化时的回调函数 -
action string 上传地址 -
mode 'single' | 'multiple' 上传模式 'single'
maxCount number 最大上传数量 mode为single时为1，multiple时为9
maxWidth number 图片最大宽度 1920
maxHeight number 图片最大高度 1080
maxSize number 单张图片最大大小(MB) 5
croppable boolean 是否可裁剪 false
disabled boolean 是否禁用 false

用户选择器 (UserSelector)

用户选择器提供了一个用户选择界面，通过表格展示用户列表，支持单选和多选模式。

使用示例：

import UserSelector from '@/components/XinFormField/UserSelector';

function MyComponent() {
  const [userId, setUserId] = useState<number | null>(null);

  return (
    <UserSelector
      value={userId}
      onChange={setUserId}
      mode="single"
      placeholder="请选择用户"
    />
  );
}

属性说明：

属性 类型 说明 默认值
value number | number[] | ISysUser | ISysUser[] | null 当前选中的用户ID或用户对象 -
onChange (value: number | number[] | null) => void 用户选择变化时的回调函数 -
mode 'single' | 'multiple' 选择模式 'single'
placeholder string 选择框的占位符文本 "请选择用户"
disabled boolean 是否禁用 false
readonly boolean 是否只读 false
showDept boolean 是否显示部门信息 true
maxTagCount number 多选时标签最大显示数量 2

与 ProForm 集成

XinFormField 组件可以无缝集成到 ProForm 中使用：

import { ProForm, ProFormText } from '@ant-design/pro-components';
import IconSelector from '@/components/XinFormField/IconSelector';

<ProForm
  onFinish={async (values) => {
    console.log(values);
  }}
>
  <ProFormText
    name="title"
    label="标题"
    rules={[{ required: true }]}
  />
  <ProForm.Item
    name="icon"
    label="图标"
  >
    <IconSelector />
  </ProForm.Item>
</ProForm>

自定义表单组件开发

如需开发自定义表单组件，建议遵循以下模式：

  1. 组件应接受 value 和 onChange 属性，以兼容表单控件
  2. 组件应支持 disabled 属性以控制禁用状态
  3. 组件应正确处理值的变化并通过 onChange 回调传递给父组件
  4. 如需要国际化支持，使用 useTranslation Hook

基本结构示例：

import React from 'react';
import { Input } from 'antd';
import { useTranslation } from 'react-i18next';

interface CustomInputProps {
  value?: string;
  onChange?: (value: string) => void;
  disabled?: boolean;
  placeholder?: string;
}

const CustomInput: React.FC<CustomInputProps> = ({
  value,
  onChange,
  disabled,
  placeholder,
}) => {
  const { t } = useTranslation();

  return (
    <Input
      value={value}
      onChange={(e) => onChange?.(e.target.value)}
      disabled={disabled}
      placeholder={placeholder || t('customInput.placeholder')}
    />
  );
};

export default CustomInput;

最佳实践

  • 在使用 XinFormField 组件时，确保正确处理值的双向绑定
  • 对于复杂的表单验证，可以在父组件中使用 ProForm 的验证规则
  • 合理利用 XinFormField 组件的内置验证功能，如图片上传器的尺寸验证
  • 在表单提交前，确保对所有输入进行适当的验证和清理

XinForm 系统使开发者能够快速构建功能丰富且用户友好的表单界面。

ON THIS PAGE