表单

使用验证规则收集用户的信息。

import React from 'react';
import * as Form from '@radix-ui/react-form';
import './styles.css';

const FormDemo = () => (
  <Form.Root className="FormRoot">
    <Form.Field className="FormField" name="email">
      <div style={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between' }}>
        <Form.Label className="FormLabel">Email</Form.Label>
        <Form.Message className="FormMessage" match="valueMissing">
          Please enter your email
        </Form.Message>
        <Form.Message className="FormMessage" match="typeMismatch">
          Please provide a valid email
        </Form.Message>
      </div>
      <Form.Control asChild>
        <input className="Input" type="email" required />
      </Form.Control>
    </Form.Field>
    <Form.Field className="FormField" name="question">
      <div style={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between' }}>
        <Form.Label className="FormLabel">Question</Form.Label>
        <Form.Message className="FormMessage" match="valueMissing">
          Please enter a question
        </Form.Message>
      </div>
      <Form.Control asChild>
        <textarea className="Textarea" required />
      </Form.Control>
    </Form.Field>
    <Form.Submit asChild>
      <button className="Button" style={{ marginTop: 10 }}>
        Post question
      </button>
    </Form.Submit>
  </Form.Root>
);

export default FormDemo;

特性

构建在原生浏览器之上约束验证 API。

支持内置验证。

支持自定义验证。

完全自定义验证消息。

可访问的验证消息。

支持客户端和服务器端场景。

焦点完全受控。

安装

从命令行安装组件。

npm install @radix-ui/react-form

结构

导入所有部分并将其组合在一起。

import * as Form from '@radix-ui/react-form';

export default () => (
  <Form.Root>
    <Form.Field>
      <Form.Label />
      <Form.Control />
      <Form.Message />
      <Form.ValidityState />
    </Form.Field>

    <Form.Message />
    <Form.ValidityState />

    <Form.Submit />
  </Form.Root>
);

API 参考

根

包含表单的所有部分。

属性	类型	默认值
`asChild`	`布尔值`	`false`
`onClearServerErrors`	`函数`	无默认值

字段

字段的包装器。它自动处理 id/name 和标签的可访问性。

属性	类型	默认值
`asChild`	`布尔值`	`false`
`name*`	`字符串`	无默认值
`serverInvalid`	`布尔值`	无默认值

数据属性	值
`[data-invalid]`	当字段无效时出现
`[data-valid]`	当字段有效时出现

控件

控件元素（默认情况下为 input），当嵌套在 Field 部分内部时，自动连接。

属性	类型	默认值
`asChild`	`布尔值`	`false`

数据属性	值
`[data-invalid]`	当字段无效时出现
`[data-valid]`	当字段有效时出现

消息

验证消息，当嵌套在 Field 部分内部时，会自动连接到给定的控件（功能和可访问性）。它可用于内置和自定义客户端验证，以及服务器端验证。当在 Field 外部使用时，必须传递与字段匹配的 name 属性。

Form.Message 接收一个 match 属性，用于确定何时显示消息。它匹配原生 HTML 的有效性状态（ValidityState，参见 MDN）。它根据诸如 required、min、max 等属性进行验证。如果控件的有效性状态中给定的 match 为 true，则会显示消息。

您还可以将函数传递给 match 以提供自定义验证规则。

属性	类型	默认值
`asChild`	`布尔值`	`false`
`match`	`匹配器`	无默认值
`forceMatch`	`布尔值`	`false`
`name`	`字符串`	无默认值

ValidityState

使用此 render-prop 组件在渲染时访问给定字段的有效性状态（参见 ValidityState，参见 MDN）。当嵌套在 Field 部分内部时，字段的有效性会自动可用，否则您必须传递 name 属性进行关联。

属性	类型	默认值
`children`	`函数`	无默认值
`name`	`字符串`	无默认值

Submit

提交按钮。

属性	类型	默认值
`asChild`	`布尔值`	`false`

示例

与您自己的组件组合

使用 asChild，您可以将 Form 原语部分与您自己的组件组合。

<Form.Field name="name">
  <Form.Label>Full name</Form.Label>
  <Form.Control asChild>
    <TextField.Input variant="primary" />
  </Form.Control>
</Form.Field>

它还可以用于组合其他类型的控件，例如 select。

<Form.Field name="country">
  <Form.Label>Country</Form.Label>
  <Form.Control asChild>
    <select>
      <option value="uk">United Kingdom</option>…
    </select>
  </Form.Control>
</Form.Field>

注意：目前，无法将 Form 与 Radix 的其他表单原语（如 Checkbox、Select 等）组合。我们正在努力寻找解决方案。

提供您自己的验证消息

当未提供 children 时，Form.Message 将为给定的 match 渲染默认错误消息。

// will yield "This value is missing"
<Form.Message match="missingValue" />

您可以通过传递您自己的 children 提供更有意义的消息。这对于国际化也很有用。

// will yield "Please provide a name"
<Form.Message match="missingValue">Please provide a name</Form.Message>

自定义验证

除了上面描述的所有内置客户端验证匹配之外，您还可以提供自己的自定义验证，同时仍然利用平台的验证功能。它使用 customError 类型，该类型存在于约束验证 API中。

您可以将您自己的验证函数传递到 Form.Message 上的 match 属性中。这是一个示例

<Form.Field name="name">
  <Form.Label>Full name</Form.Label>
  <Form.Control />
  <Form.Message match={(value, formData) => value !== 'John'}>
    Only John is allowed.
  </Form.Message>
</Form.Field>

match 将使用控件的当前值作为第一个参数，以及整个 FormData 作为第二个参数被调用。 match 也可以是 async 函数（或返回一个 promise）以执行异步验证。

基于有效性的样式

我们在相关部分添加了 data-valid 和 data-invalid 属性。使用它来相应地设置组件的样式。以下是如何为 Label 部分设置样式的示例。

//index.jsx
import * as React from 'react';
import Form from '@radix-ui/react-form';

export default () => (
  <Form.Root>
    <Form.Field name="email">
      <Form.Label className="FormLabel">Email</Form.Label>
      <Form.Control type="email" />
    </Form.Field>
  </Form.Root>
);

/* styles.css */
.FormLabel[data-invalid] {
  color: red;
}
.FormLabel[data-valid] {
  color: green;
}

访问有效性状态以获得更多控制

您可能需要访问字段的原始有效性状态，以便显示您自己的图标或通过其定义的 props 与组件库交互。您可以使用 Form.ValidityState 部分来实现。

<Form.Field name="name">
  <Form.Label>Full name</Form.Label>
  <Form.ValidityState>
    {(validity) => (
      <Form.Control asChild>
        <TextField.Input
          variant="primary"
          state={getTextFieldInputState(validity)}
        />
      </Form.Control>
    )}
  </Form.ValidityState>
</Form.Field>

服务器端验证

该组件还支持使用相同的 Form.Message 组件进行服务器端验证。您可以通过传递 forceMatch 属性来重复使用为客户端错误定义的相同消息，该属性将强制显示消息，而不管客户端匹配逻辑如何。

如果客户端不存在该消息，您也可以在没有 match 的情况下渲染 Form.Message。通过将 serverInvalid 布尔属性传递给 Form.Field 部分来将字段标记为无效。

以下是一个带有服务器端错误处理的示例

import * as React from 'react';
import * as Form from '@radix-ui/react-form';

function Page() {
  const [serverErrors, setServerErrors] = React.useState({
    email: false,
    password: false,
  });

  return (
    <Form.Root
      // `onSubmit` only triggered if it passes client-side validation
      onSubmit={(event) => {
        const data = Object.fromEntries(new FormData(event.currentTarget));

        // Submit form data and catch errors in the response
        submitForm(data)
          .then(() => {})
          /**
           * Map errors from your server response into a structure you'd like to work with.
           * In this case resulting in this object: `{ email: false, password: true }`
           */
          .catch((errors) => setServerErrors(mapServerErrors(errors)));

        // prevent default form submission
        event.preventDefault();
      }}
      onClearServerErrors={() =>
        setServerErrors({ email: false, password: false })
      }
    >
      <Form.Field name="email" serverInvalid={serverErrors.email}>
        <Form.Label>Email address</Form.Label>
        <Form.Control type="email" required />
        <Form.Message match="valueMissing">
          Please enter your email.
        </Form.Message>
        <Form.Message match="typeMismatch" forceMatch={serverErrors.email}>
          Please provide a valid email.
        </Form.Message>
      </Form.Field>

      <Form.Field name="password" serverInvalid={serverErrors.password}>
        <Form.Label>Password</Form.Label>
        <Form.Control type="password" required />
        <Form.Message match="valueMissing">
          Please enter a password.
        </Form.Message>
        {serverErrors.password && (
          <Form.Message>
            Please provide a valid password. It should contain at least 1 number
            and 1 special character.
          </Form.Message>
        )}
      </Form.Field>

      <Form.Submit>Submit</Form.Submit>
    </Form.Root>
  );
}

您应该使用 Form.Root 部分上的 onClearServerErrors 回调属性清除服务器错误。它将在表单重新提交之前以及重置表单时清除服务器错误。

此外，这提供了控制何时重置单个服务器错误的功能。例如，您可以尽快在用户编辑电子邮件时重置电子邮件服务器错误。

<Form.Field name="email" serverInvalid={serverErrors.email}>
  <Form.Label>Email address</Form.Label>
  <Form.Control
    type="email"
    onChange={() => setServerErrors((prev) => ({ ...prev, email: false }))}
  />
  <Form.Message match="missingValue">Please enter your email.</Form.Message>
  <Form.Message match="typeMismatch" forceMatch={serverErrors.email}>
    Please provide a valid email.
  </Form.Message>
</Form.Field>

可访问性

该组件遵循验证的“内联错误”模式。

标签和控件使用 Form.Field 上提供的 name 进行关联。
当显示一个或多个客户端错误消息时，它们会自动与其匹配的控件关联并相应地宣布。
焦点将移动到第一个无效控件。

上一页下拉菜单

下一页悬停卡片

在 GitHub 上编辑此页面。

概述

指南

组件

实用程序

表单

特性

安装

结构