字段类型说明

Framework:

概述

Schema FormX 支持多种字段类型，每种类型都有对应的默认组件。本章节将详细介绍所有支持的字段类型及其使用方法。

支持的字段类型

类型	说明	默认组件	默认值	空值判断
string	字符串类型	Input	`''`	`null`, `undefined`, `''`
number	数字类型	InputNumber	`null`	`null`, `undefined`, `''`
boolean	布尔类型	Checkbox	`null`	`null`, `undefined`, `''`
object	对象类型	自定义	`{}`	`null`, `undefined`, `{}`
array	数组类型	自定义	`[]`	`null`, `undefined`, `[]`

说明：空值判断用于 required: true 时的必填验证，满足空值条件时会提示"不能为空"。

数据类型转换：Schema FormX 不会自动进行类型转换。如果字段声明为 type: 'number'，绑定的数据值取决于组件 onChange 回调传出的值（例如，如果组件传出字符串 "123"，数据值将是 "123" 而非 123）。确保自定义组件传出正确类型的值是组件自身的责任。

字段类型示例

String 类型

字符串类型是最常用的字段类型，用于处理文本输入。

基础用法

{
  type: 'string',
  name: 'username',
  label: '用户名',
  required: true,
  props: {
    placeholder: '请输入用户名'
  }
}

常用属性

说明：以下属性是 DefaultControl（默认 Input 组件）的常用属性，通过 schema.props 传递。如果你注册了自定义组件，可用属性取决于该组件自身的 API。

属性	类型	说明
placeholder	string	占位符文本
maxLength	number	最大长度
minLength	number	最小长度
type	string	输入类型（text、email、password 等）

示例

// 邮箱输入
{
  type: 'string',
  name: 'email',
  label: '邮箱',
  props: {
    type: 'email',
    placeholder: '请输入邮箱地址'
  }
}

// 密码输入
{
  type: 'string',
  name: 'password',
  label: '密码',
  props: {
    type: 'password',
    placeholder: '请输入密码'
  }
}

Number 类型

数字类型用于处理数值输入。

基础用法

{
  type: 'number',
  name: 'age',
  label: '年龄',
  props: {
    min: 0,
    max: 120
  }
}

常用属性

说明：以下属性是 DefaultControl（默认 InputNumber 组件）的常用属性，通过 schema.props 传递。

属性	类型	说明
min	number	最小值
max	number	最大值
step	number	步长
precision	number	小数位数

示例

// 价格输入
{
  type: 'number',
  name: 'price',
  label: '价格',
  props: {
    min: 0,
    step: 0.01,
    precision: 2
  }
}

// 数量输入
{
  type: 'number',
  name: 'quantity',
  label: '数量',
  props: {
    min: 1,
    max: 100,
    step: 1
  }
}

Boolean 类型

布尔类型用于处理开关、复选框等二值输入。

基础用法

{
  type: 'boolean',
  name: 'agree',
  label: '同意协议'
}

常用属性

说明：以下属性是 DefaultControl（默认 Checkbox/Switch 组件）的常用属性，通过 schema.props 传递。

属性	类型	说明
checkedText	string	选中时的文本
uncheckedText	string	未选中时的文本

示例

// 协议同意
{
  type: 'boolean',
  name: 'agreeTerms',
  label: '我已阅读并同意用户协议'
}

// 启用状态
{
  type: 'boolean',
  name: 'enabled',
  label: '启用',
  props: {
    checkedText: '启用',
    uncheckedText: '禁用'
  }
}

Object 类型

对象类型用于处理复杂的数据结构，需要配合自定义组件使用。

基础用法

// 自定义地址选择组件
const AddressPicker = ({ value = {}, onChange }) => (
  <div>
    <input 
      placeholder="省份" 
      value={value.province || ''} 
      onChange={(e) => onChange({ ...value, province: e.target.value })} 
    />
    <input 
      placeholder="城市" 
      value={value.city || ''} 
      onChange={(e) => onChange({ ...value, city: e.target.value })} 
    />
  </div>
);

// 注册组件
const components = {
  DefaultControl: MyInput,
  AddressPicker
};

// 使用对象类型
{
  type: 'object',
  name: 'address',
  label: '地址',
  component: 'AddressPicker'
}

使用场景

地址选择（省/市/区）
坐标选择（经度/纬度）
复杂对象的结构化输入

默认值

对象类型的默认值为 {}，空对象 {} 在必填验证时会被判定为空。

Array 类型

数组类型用于处理列表数据，需要配合自定义组件使用。

基础用法

// 自定义标签输入组件
const TagInput = ({ value = [], onChange }) => {
  const [input, setInput] = useState('');

  const addTag = () => {
    if (input.trim()) {
      onChange([...value, input.trim()]);
      setInput('');
    }
  };

  const removeTag = (index) => {
    onChange(value.filter((_, i) => i !== index));
  };

  return (
    <div>
      <div>
        {value.map((tag, index) => (
          <span key={index}>
            {tag}
            <button onClick={() => removeTag(index)}>×</button>
          </span>
        ))}
      </div>
      <input value={input} onChange={(e) => setInput(e.target.value)} />
      <button onClick={addTag}>添加</button>
    </div>
  );
};

// 注册组件
const components = {
  DefaultControl: MyInput,
  TagInput
};

// 使用数组类型
{
  type: 'array',
  name: 'tags',
  label: '标签',
  component: 'TagInput'
}

使用场景

标签输入
文件上传列表
多选选择器

默认值

数组类型的默认值为 []，空数组 [] 在必填验证时会被判定为空。

自定义类型

除了内置类型，还可以通过自定义组件来处理特殊类型。

自定义组件

// 自定义日期选择器
const DatePickerComponent = ({ value, onChange, ...props }: any) => (
  <input 
    type="date"
    value={value || ''}
    onChange={(e) => onChange(e.target.value)}
    {...props}
  />
);

// 默认输入组件
const InputComponent = ({ value = '', onChange, ...props }: any) => (
  <input
    value={value}
    onChange={(e) => onChange(e.target.value)}
    {...props}
  />
);

// 注册自定义组件
const components = {
  DefaultControl: InputComponent,
  DatePicker: DatePickerComponent
};

// 使用自定义组件
{
  type: 'string',
  name: 'birthday',
  label: '生日',
  component: 'DatePicker'
}

类型验证

Schema FormX 会根据字段类型进行基础验证：

必填验证

当 required: true 时，会根据字段类型判断空值：

{
  type: 'string',
  name: 'username',
  label: '用户名',
  required: true  // 不能为空
}

空值判断规则：

类型	空值
string	`null`, `undefined`, `''`
number	`null`, `undefined`, `''`
boolean	`null`, `undefined`, `''`
object	`null`, `undefined`, `{}`
array	`null`, `undefined`, `[]`

类型验证

{
  type: 'number',
  name: 'age',
  label: '年龄',
  props: {
    min: 0,
    max: 120
  }
}

自定义验证

{
  type: 'string',
  name: 'email',
  label: '邮箱',
  validator: ({ value, label }) => {
    if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      return `${label}格式不正确`;
    }
    return undefined;
  }
}

最佳实践

选择合适的类型：根据数据特点选择最合适的字段类型
使用默认组件：优先使用默认组件，减少自定义代码
类型与验证配合：结合类型和验证规则确保数据质量
考虑用户体验：为不同类型的字段提供合适的交互方式
合理使用默认值：通过 defaultData 设置合理的初始值，避免空值问题
object/array 自定义：object 和 array 类型需要配合自定义组件使用

#字段类型说明

#概述

#支持的字段类型

#字段类型示例

#String 类型

#基础用法

#常用属性

#示例

#Number 类型

#基础用法

#常用属性

#示例

#Boolean 类型

#基础用法

#常用属性

#示例

#Object 类型

#基础用法

#使用场景

#默认值

#Array 类型

#基础用法

#使用场景

#默认值

#自定义类型

#自定义组件

#类型验证

#必填验证

#类型验证

#自定义验证

#最佳实践

字段类型说明

概述

支持的字段类型

字段类型示例

String 类型

基础用法

常用属性

示例

Number 类型

基础用法

常用属性

示例

Boolean 类型

基础用法

常用属性

示例

Object 类型

基础用法

使用场景

默认值

Array 类型

基础用法

使用场景

默认值

自定义类型

自定义组件

类型验证

必填验证

类型验证

自定义验证

最佳实践