表单 (Forms)

HeroUI 提供了内置验证和样式的表单组件，以帮助用户有效地输入和提交数据。(HeroUI provides form components with built-in validation and styling to help users input and submit data effectively.)

标签和帮助文本 (Labels and help text)

可访问的表单从每个字段的清晰、描述性的标签开始。所有 HeroUI 表单组件都支持使用 Label 组件进行标签，该组件代表您通过 id 和 for 属性自动与字段关联。(Accessible forms start with clear, descriptive labels for each field. All HeroUI form components support labeling using the Label component, which is automatically associated with the field via the id and for attributes on your behalf.)

此外，HeroUI 组件支持帮助文本，帮助文本将附加的上下文与字段关联，例如描述或错误消息。当用户聚焦字段时，屏幕阅读器等辅助技术会播报标签和帮助文本。(In addition, HeroUI components support help text, which associates additional context with a field such as a description or error message. The label and help text are announced by assistive technology such as screen readers when the user focuses the field.)

大多数字段应具有可见标签。在极少数情况下，必须提供 aria-label 或 aria-labelledby 属性来代替，以向屏幕阅读器标识元素。(Most fields should have a visible label. In rare exceptions, the aria-label or aria-labelledby attribute must be provided instead to identify the element to screen readers.)

提交数据 (Submitting data)

您如何提交表单数据取决于您的框架、应用程序和服务器。默认情况下，HTML 表单通过浏览器中的完整页面刷新提交。您可以在 onSubmit 事件中调用 preventDefault，以通过 API 处理表单数据提交。(How you submit form data depends on your framework, application, and server. By default, HTML forms are submitted via a full-page refresh in the browser. You can call preventDefault in the onSubmit event to handle form data submission via an API.)

诸如 Next.js、Remix 和 React Router 等框架提供了自己处理表单提交的方式。(Frameworks like Next.js, Remix, and React Router provide their own ways to handle form submission.)

非受控表单 (Uncontrolled forms)

获取表单数据的一种简单方法是在 onSubmit 事件期间使用浏览器的 FormData API。您可以将此数据发送到后端 API，或使用 Object.fromEntries 将其转换为 JavaScript 对象。每个字段都应具有 name 属性以标识它，并且值将由浏览器序列化为字符串。(A simple way to get form data is to use the browser's FormData API during the onSubmit event. You can send this data to a backend API or convert it into a JavaScript object using Object.fromEntries. Each field should have a name prop to identify it, and the values will be serialized as strings by the browser.)

受控表单 (Controlled forms)

HeroUI 表单组件默认情况下是非受控的，但是如果您需要实时管理状态，则可以使用 useState Hook 使组件受控。(HeroUI form components are uncontrolled by default, but if you need to manage state in real-time, you can use the useState hook to make the component controlled.)

自定义错误消息 (Customizing error messages)

默认情况下，错误消息由浏览器提供。您可以通过向 errorMessage 属性提供函数来自定义这些消息。(By default, error messages are provided by the browser. You can customize these messages by providing a function to the errorMessage prop.)

注意：默认错误消息由浏览器根据浏览器/操作系统语言设置进行本地化。HeroUI Provider 中的 locale 设置不影响验证错误。(Note: The default error messages are localized by the browser based on the browser/operating system language settings. The locale setting in HeroUI Provider does not affect validation errors.)

验证 (Validation)

表单验证对于确保用户输入正确的数据至关重要。HeroUI 支持原生 HTML 约束验证，并允许自定义验证和实时验证。(Form validation is crucial for ensuring that users enter the correct data. HeroUI supports native HTML constraint validation and allows for custom validation and real-time validation.)

内置验证 (Built-in validation)

HeroUI 表单组件支持原生 HTML 验证属性，例如 isRequired 和 minLength。当用户提交更改（例如，在 blur 上）或提交表单时，浏览器会检查这些约束。您可以显示带有自定义样式的验证错误，而不是浏览器的默认 UI。(HeroUI form components support native HTML validation attributes like isRequired and minLength. These constraints are checked by the browser when the user commits changes (e.g., on blur) or submits the form. You can display validation errors with custom styles instead of the browser's default UI.)

要启用原生验证，请设置 validationBehavior="native"。默认情况下，设置了 validationBehavior="aria"，它仅将字段标记为辅助技术的必填或无效字段，而不会阻止表单提交。您可以使用 HeroUI Provider 更改整个应用程序的表单默认设置。(To enable native validation, set validationBehavior="native". By default, validationBehavior="aria" is set, which only marks the field as required or invalid for assistive technologies, without preventing form submission. You can change the form defaults for your entire app using HeroUI Provider.)

支持的约束包括 (Supported constraints include)

isRequired 表示字段在可以提交表单之前必须具有值。(isRequired indicates that a field must have a value before the form can be submitted.)
minValue 和 maxValue 指定日期选择器或数字字段中的最小值和最大值。(minValue and maxValue specify the minimum and maximum value in a date picker or number field.)
minLength 和 maxLength 指定文本输入的最小和最大长度。(minLength and maxLength specify the minimum and length of text input.)
pattern 提供自定义正则表达式，文本输入必须符合该表达式。(pattern provides a custom regular expression that a text input must conform to.)
type="email" 和 type="url" 为电子邮件地址和 URL 提供内置验证。(type="email" and type="url" provide built-in validation for email addresses and URLs.)

有关支持的验证属性的更多详细信息，请参阅每个组件的文档。(See each component's documentation for more details on the supported validation props.)

自定义验证 (Custom validation)

除了内置约束之外，您还可以向 validate 属性提供函数以支持自定义验证。(In addition to built-in constraints, you can provide a function to the validate prop to support custom validation.)

实时验证 (Realtime validation)

如果您想在用户键入时显示验证错误，则可以控制字段值，并结合 errorMessage 属性使用 isInvalid 属性。(If you want to display validation errors while the user is typing, you can control the field value and use the isInvalid prop along with the errorMessage prop.)

使用 validationBehavior="aria" 即使在字段无效时也允许表单提交，同时保持可访问性。(Use validationBehavior="aria" to allow form submission even when fields are invalid, while maintaining accessibility.)

服务器端验证 (Server validation)

客户端验证提供即时反馈，但您还应在服务器上验证数据，以确保准确性和安全性。HeroUI 允许您通过在 Form 组件中使用 validationErrors 属性来显示服务器端验证错误。此属性应是一个对象，其中每个键是字段 name，值是错误消息。(Client-side validation provides immediate feedback, but you should also validate data on the server to ensure accuracy and security. HeroUI allows you to display server-side validation errors by using the validationErrors prop in the Form component. This prop should be an object where each key is the field name and the value is the error message.)

架构验证 (Schema validation)

HeroUI 支持来自架构验证库（如 Zod）的错误。您可以使用 Zod 的 flatten 方法来获取每个字段的错误消息，并将它们作为服务器响应的一部分返回。(HeroUI supports errors from schema validation libraries like Zod. You can use Zod's flatten method to get error messages for each field and return them as part of the server response.)

有关 HeroUI 中表单的更多信息，请访问 React Aria Forms 指南。