Form 表单 #

一组处理表单数据的组件和模型。

获取组件 #

• 基础组件:
  • Form 用于定义支持数据校验的表单。
  • Form.Label 表单字段对应的标题。
  • Form.Control 定义表单字段的控件。默认为 Input 组件。 可以通过 accepter 属性自定义组件。
• 布局相关组件:
  • Form.Stack 用于布局一组表单控件。
  • Form.Group 用于布局单个表单控件。
• 字段状态组件:
  • Form.Text 提供表单字段的帮助信息。
  • Form.ErrorMessage 显示表单字段的错误提示信息。
• Hooks
  • useFormControl: 为自定义表单组件提供表单控制功能的 Hook，使其能够与 Form 组件无缝集成。

布局 #

垂直布局 #

撑满容器 #

fluid 属性可以让表单中的 Input 100% 撑满容器，只在垂直布局中有效。

水平排列布局 #

行内排列布局 #

模态框中布局 #

状态 #

帮助说明 #

<Form.Text> 可以在表单组件下面定义一个帮助说明信息，如果设置 tooltip 属性，就会在表单组件显示一个图标，以 <Tooltip> 的方式显示帮助说明信息。

错误消息 #

错误消息提醒可以通过 2 种方式设定：

• <Form.Control> 组件上传递一个 errorMessage 属性设置错误信息，通过 errorPlacement设置错误信息显示的位置 。
• 自定义一个提示信息。

禁用与只读 #

可访问性 #

ARIA 属性 #

• 您应该为每个表单设置 aria-label 或 aria-labelledby 属性，以便屏幕阅读器可以正确地读取表单的目的。
• 通过 <Form.Group> 的 controlId 属性，可以在 <Form.Control> 上设置 id 同时在 <Form.Label> 上设置 htmlFor。另外会为 <Form.Control> 生成aria-labelledby 和 aria-describedby， 对应到 <Form.Label> 与 <Form.Text> 的 id。

<Form.Group controlId="name">
  <Form.Label>Username</Form.Label>
  <Form.Control />
  <Form.Text>Username is required</Form.Text>
</Form.Group>

生成为:

<div class="rs-form-group" role="group">
  <label id="name-control-label" for="name" class="rs-form-control-label">Username</label>
  <div class="rs-form-control rs-form-control-wrapper">
    <input
      id="name"
      class="rs-input"
      aria-labelledby="name-control-label"
      aria-describedby="name-help-text"
    />
  </div>
  <span id="name-help-text" class="rs-form-help-text">Username is required</span>
</div>

必需的 JavaScript 功能 #

• 在 Form 内点击 type='submit' 的按钮，会自动触发表单的 submit 事件。

Props #

<Form> #

<Form.Stack> #

<Form.Control> #

<Form.Group> #

<Form.Label> #

<Form.Text> #

<Form.ErrorMessage> #

Form ref #

Schema #

Schema 依赖于 schema-typed 库，用于定义数据模型。

Placement #

/**
 * Placement options for error messages in form controls.
 * The `static` option is supported from v6.0.0 onwards.
 */
type ErrorMessagePlacement =
  | 'static'
  | 'bottomStart'
  | 'bottomEnd'
  | 'topStart'
  | 'topEnd'
  | 'leftStart'
  | 'leftEnd'
  | 'rightStart'
  | 'rightEnd';

Hooks #

useFormControl #

useFormControl hook 为自定义表单组件提供表单控制功能。必须在 <Form> 组件内使用。

const {
  value, // 当前字段值
  error, // 字段错误信息
  plaintext, // 字段是否为纯文本模式
  readOnly, // 字段是否为只读
  disabled, // 字段是否禁用
  onChange, // 字段值变化处理函数
  onBlur, // 字段失焦事件处理函数
  onCheck, // 手动触发字段验证的处理函数
  setValue // 直接设置字段值
} = useFormControl(props);

属性 #

返回值 #

示例 #

import { useFormControl } from 'rsuite';

function CustomField({ name, label }) {
  const { value, error, onChange, onBlur } = useFormControl({ name });

  return (
    <div className="custom-field">
      <label>{label}</label>
      <input value={value || ''} onChange={e => onChange(e.target.value, e)} onBlur={onBlur} />
      {error && <div className="error-message">{error}</div>}
    </div>
  );
}

// 使用方式
<Form>
  <CustomField name="email" label="邮箱" />
</Form>;