Semi Design 表单(Form)组件深度解析

Semi Design 表单(Form)组件深度解析

semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design

概述

Semi Design 提供的 Form 表单组件是一个功能强大、性能优异的前端表单解决方案。它通过精心设计的数据流管理和丰富的功能特性，帮助开发者快速构建复杂的企业级表单应用。

核心优势

1. 高性能渲染机制

Form 组件采用按需重绘策略，只更新发生变化的表单项，避免了不必要的全量渲染，显著提升了大型表单的性能表现。

2. 简洁的API设计

通过极简的结构设计，减少了不必要的组件嵌套层级，使代码更加清晰易读。同时提供了多种声明式写法，适应不同开发习惯。

3. 完善的无障碍支持

组件内置了完整的无障碍访问特性，确保所有用户都能顺畅使用表单功能。

4. 灵活的数据管理

• 支持在 Form 外部方便地获取表单状态
• 提供 formApi/fieldApi 进行表单操作
• 支持 Form 和 Field 级别的赋值与校验（同步/异步）

5. 强大的扩展能力

通过 withField HOC 可以轻松将自定义组件封装为表单控件，实现团队内部组件的快速接入。

表单控件(Field)详解

Semi Design 将所有内置输入控件（如 Input、Select、Checkbox 等）都使用 withField 进行了封装，接管了它们的数据流（value & onChange）。使用时需要从 Form 中导出这些控件，它们才具有数据同步功能。

注意事项

1. 不要使用 onChange 同步数据：Form 已自动处理数据同步，但仍可监听 onChange 事件获取最新值
2. 避免直接设置控件值：应通过 Field 的 initValue 或 Form 的 initValues 设置默认值
3. 不要直接修改 FormState：所有数据修改都应通过 formApi/fieldApi 完成

表单声明方式

Semi Form 支持多种声明方式，满足不同场景需求：

1. 基础写法（推荐）

<Form>
  <Form.Input field="username" label="用户名" />
  <Form.Select field="role" label="角色">
    <Option value="admin">管理员</Option>
  </Form.Select>
</Form>

2. Render Props 写法

<Form render={({formState, formApi}) => (
  <Form.Input field="username" />
)} />

3. Children Function 写法

<Form>
  {({formState}) => <Form.Input field="username" />}
</Form>

4. Component Props 写法

const Fields = () => <Form.Input field="username" />;
<Form component={Fields} />

表单布局方案

Semi Form 提供两种主要布局方式：

1. 垂直布局（默认）：表单项上下排列，符合 Semi Design 推荐规范
2. 水平布局：通过设置 layout="horizontal" 实现标签和控件水平排列

字段绑定规则

每个表单控件都需要通过 field 属性绑定字段名称，支持多级嵌套：

• 简单字段：username → formState.values.username
• 数组字段：user[0] → formState.values.user[0]
• 嵌套对象：parents[0].name → formState.values.parents[0].name

最佳实践

1. 合理使用 initValues：在 Form 级别统一设置初始值
2. 优先使用垂直布局：提升表单可读性和易用性
3. 善用 formApi：通过 API 操作表单状态而非直接修改
4. 考虑性能优化：对于大型表单，合理拆分表单区块

通过 Semi Design 的 Form 组件，开发者可以快速构建出高性能、易维护的表单界面，同时保证良好的用户体验和无障碍访问特性。

semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design