#指南

欢迎使用 Schema FormX 指南！本指南将帮助您了解和使用 Schema FormX 来构建声明式表单。

#什么是 Schema FormX

Schema FormX 是一个声明式的表单解决方案，通过 Schema 配置快速构建复杂表单界面。它具有以下特点：

• 配置驱动：Schema 定义表单结构，自动渲染对应 UI
• 灵活布局：支持统一配置和按需细化，从整体到单个字段灵活控制样式
• 自由控件：任意 UI 组件均可作为表单控件，不与特定组件库绑定
• 分组表单：支持表单分组，同一 Schema 下多种布局形式
• 依赖联动：声明依赖关系，依赖变化自动触发联动逻辑

#工作流程

渲染流程说明：

1. 将 Schema 配置传入 Form 组件
2. Form 自动识别 Schema 类型（字段数组或分组数组）
3. 每个分组渲染一个 Group 容器
4. 每个字段通过 component 属性查找对应的 UI 组件
5. 组件查找顺序：自定义组件 → DefaultControl → 错误提示

#核心概念

#Schema（表单配置）

Schema 是表单的核心配置，定义了表单的结构和行为。它有两种形式：FieldSchema（字段表单）和 GroupSchema（分组表单）。

FieldSchema — 每个元素代表一个表单字段：

const schema: FieldSchema[] = [
  {
    type: 'string',
    name: 'username',
    label: '用户名',
    required: true
  },
  {
    type: 'string',
    name: 'email',
    label: '邮箱',
    required: true
  }
];

GroupSchema — 将多个字段组合到一个分组中，可为每个分组指定独立的组件和样式：

const schema: GroupSchema[] = [
  {
    key: 'basic',
    props: { title: '基本信息' },
    fields: [
      { name: 'username', label: '用户名', type: 'string', required: true },
      { name: 'email', label: '邮箱', type: 'string' }
    ]
  },
  {
    key: 'extra',
    props: { title: '其他信息' },
    fields: [
      { name: 'bio', label: '简介', type: 'string' }
    ]
  }
];

#Field（字段定义）

每个字段定义包含以下关键属性：

#Layout（布局配置）

Layout 控制表单的整体布局和样式，支持统一配置和按需细化：

const layout: Layout = {
  formClassName: 'my-form',
  formStyle: { maxWidth: '600px' },
  fieldClassName: 'form-field',
  labelClassName: 'field-label',
  controlClassName: 'field-control'
};

#Component（表单控件）

表单控件是实际渲染的 UI 组件，可以通过以下方式自定义：

1. 全局注册：通过 components 属性注册所有自定义组件
2. 字段指定：通过 component 属性为特定字段指定组件

#适用场景

Schema FormX 适用于以下场景：

#复杂表单构建

当表单包含大量字段、复杂的验证规则和联动逻辑时，Schema FormX 可以大大简化开发工作。

#动态表单生成

当表单结构需要根据后端配置动态生成时，Schema FormX 的配置驱动特性非常有用。

#多框架项目统一表单方案

当项目需要支持多种前端框架时，Schema FormX 提供统一的表单解决方案。

#快速开始

如果您想快速体验 Schema FormX，请查看 快速开始 章节。

#文档结构

本指南包含以下章节：

• 快速开始：5 分钟内体验 Schema FormX 的基本功能
• 基础功能：表单配置、字段类型等基础知识
• 高级功能：自定义组件、验证规则、分组表单、依赖联动等
• API 参考：详细的 API 文档和类型定义