• 简体中文

      • 快速参考卡片

      一页纸速查表，涵盖最常用的 API 和模式。

      组件导入

      import { Form } from '@schema-formx/react';
import type {
  FieldSchema,
  GroupSchema,
  FormInstance,
  Layout,
  Components
} from '@schema-formx/react';

      核心模式

      非受控模式（推荐）

      <Form
  schema={schema}
  defaultData={{ name: '张三', age: 25 }}
  onChange={({ data }) => console.log(data)}
/>

      受控模式

      const [formData, setFormData] = useState({ name: '', age: 0 });

<Form
  schema={schema}
  data={formData}
  onChange={({ data }) => setFormData(data)}
/>

      表单实例方法

      const formRef = useRef<FormInstance>(null);

// 获取数据
const data = formRef.current.getData();

// 设置数据
formRef.current.setData({ name: '新值' });

// 验证表单
const { data, errors } = await formRef.current.validate();

// 重置表单
formRef.current.reset();

// 检查是否修改过
const isDirty = formRef.current.isDirty();

      字段配置速查

      FieldSchema

      type FieldSchema = {
  type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
  name: string;          // 字段名
  label: string;         // 显示名称
  required?: boolean;    // 是否必填
  component?: string;    // 自定义组件名
  props?: object;        // 组件属性
  hidden?: boolean;      // 是否隐藏
  deps?: string[];       // 依赖字段
  onDepsChange?: Function; // 联动回调
  validator?: Function;  // 验证器
};

      字段类型与默认值

      类型默认值空值条件
      string''null, undefined, ''
      numbernullnull, undefined, ''
      booleannullnull, undefined, ''
      object{}null, undefined, {}
      array[]null, undefined, []

      分组配置速查

      GroupSchema

      type GroupSchema = {
  key: string;           // 分组唯一标识
  fields: FieldSchema[]; // 分组内字段
  component?: string;    // 自定义分组容器
  props?: object;        // 容器属性
};

      使用示例

      const schema: GroupSchema[] = [
  {
    key: 'basic',
    props: { title: '基本信息' },
    fields: [
      { type: 'string', name: 'name', label: '姓名', required: true },
      { type: 'string', name: 'email', label: '邮箱', required: true }
    ]
  }
];

      布局配置速查

      Layout

      type Layout = {
  // 表单级
  formClassName?: string;
  formStyle?: CSSProperties;
  // 分组级
  groupClassName?: string;
  groupStyle?: CSSProperties;
  // 字段级
  fieldClassName?: string;
  fieldStyle?: CSSProperties;
  // 标签级
  labelClassName?: string;
  labelStyle?: CSSProperties;
  // 提示级
  tipClassName?: string;
  tipStyle?: CSSProperties;
  // 控件级
  controlClassName?: string;
  controlStyle?: CSSProperties;
  // 指定分组
  groups?: Record<string, { groupClassName?: string; groupStyle?: CSSProperties }>;
  // 指定字段
  fields?: Record<string, {
    fieldClassName?: string; fieldStyle?: CSSProperties;
    labelClassName?: string; labelStyle?: CSSProperties;
    controlClassName?: string; controlStyle?: CSSProperties;
    tipClassName?: string; tipStyle?: CSSProperties;
  }>;
};

      使用示例

      const layout: Layout = {
  formStyle: { maxWidth: '600px', margin: '0 auto' },
  fieldStyle: { marginBottom: '16px' },
  labelStyle: { fontWeight: '500' },
  fields: {
    username: { controlStyle: { width: '300px' } }
  }
};

      验证规则速查

      内置验证

      { type: 'string', name: 'email', label: '邮箱', required: true }

      自定义验证

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

      异步验证

      {
  type: 'string',
  name: 'username',
  label: '用户名',
  validator: async ({ value, label }) => {
    const exists = await checkUsername(value);
    return exists ? `${label}已存在` : undefined;
  }
}

      依赖联动速查

      基础联动

      {
  type: 'string',
  name: 'city',
  label: '城市',
  deps: ['province'],
  onDepsChange: async ({ deps, schema }) => {
    const cities = await getCities(deps[0]);
    return {
      patch: { city: '' },  // 清空城市
      schema: { ...schema, props: { options: cities } }
    };
  }
}

      返回值说明

      返回值作用说明
      patch更新表单数据浅合并到当前数据
      schema更新字段配置完整替换当前字段 schema

      组件注册速查

      const components: Components = {
  DefaultControl: MyInput,    // 默认控件（必填）
  DefaultGroup: MyGroup,      // 默认分组容器（可选）
  ColorPicker: ColorPicker,   // 自定义组件
};

<Form schema={schema} components={components} />

      组件查找顺序

      1. components[component] → 自定义注册的组件
      2. components['DefaultControl'] → 默认控件
      3. 报错 "error component"

      分组容器查找顺序

      1. GroupSchema.component → 分组指定的组件
      2. components['DefaultGroup'] → 默认分组容器
      3. 内置 Group 组件