表单

HeroUI 提供了带有内置验证和样式的表单组件，帮助用户有效地输入和提交数据。

标签和帮助文本

可访问性的表单首先为每个字段提供清晰、描述性的标签。所有 HeroUI 表单组件支持使用 Label 组件进行标注，Label 组件会自动通过 id 和 for 属性与字段关联。

此外，HeroUI 组件支持帮助文本，帮助文本会为字段关联额外的上下文，例如描述或 错误信息。当用户聚焦字段时，标签和帮助文本会由辅助技术（如屏幕阅读器）朗读。

大多数字段应有可见标签。在少数例外情况下，必须提供 aria-label 或 aria-labelledby 属性来识别该元素以供屏幕阅读器使用。

表单数据的提交方式取决于您的框架、应用程序和服务器。默认情况下，HTML 表单会在浏览器中通过完整页面刷新来提交。您可以在 onSubmit 事件中调用 preventDefault，以通过 API 处理表单数据提交。

像 Next.js, Remix 和 React Router 等框架提供了自己的表单提交处理方式。

在 onSubmit 事件中使用浏览器的 FormData API 是获取表单数据的简单方法。您可以将这些数据发送到后端 API，或者使用 Object.fromEntries 将其转换为 JavaScript 对象。每个字段应有 name 属性来标识，浏览器将把值序列化为字符串。

HeroUI 表单组件默认是未受控的，但如果您需要实时管理状态，可以使用 useState 钩子将组件变为受控。

默认情况下，错误信息由浏览器提供。您可以通过为 errorMessage 属性提供一个函数来自定义这些消息。

注意：默认错误信息会根据浏览器/操作系统的语言设置本地化。HeroUI Provider 中的 locale 设置不会影响验证错误。

表单验证对于确保用户输入正确的数据至关重要。HeroUI 支持原生 HTML 约束验证，并允许自定义验证与实时验证。

HeroUI 表单组件支持原生 HTML 验证属性，如 isRequired 和 minLength。这些约束会在用户提交表单（或失去焦点）时由浏览器检查。您可以自定义样式来显示验证错误，而非使用浏览器默认 UI。

要启用 ARIA 验证，设置 validationBehavior="aria"。当 validationBehavior="aria" 时，字段仅在屏幕阅读器等辅助技术中被标记为必填或无效，而不会阻止表单提交。您可以使用 HeroUI Provider 在整个应用中更改表单默认值。

支持的约束包括：

有关所支持验证属性的更多信息，请参阅每个组件的文档。

除了内置约束，您可以为 validate 属性提供一个函数来支持自定义验证。

如果您想在用户输入时就显示验证错误，可以控制字段值并使用 isInvalid 与 errorMessage 属性。

使用 validationBehavior="aria" 以允许表单提交，即使字段无效，也保持可访问性。

客户端验证可以即时反馈，但您也应在服务器端验证以确保准确性和安全性。HeroUI 允许通过 validationErrors 属性在 Form 组件中显示服务器端验证错误。该属性应是一个对象，每个键是字段 name，对应的值为错误消息。

HeroUI 支持来自架构验证库（如 Zod）的错误。您可以使用 Zod 的 flatten 方法获取每个字段的错误信息，并将它们作为服务器响应的一部分返回。

Server Actions 允许无缝地将表单提交到服务器并获取结果。useActionState 钩子可用于在提交表单后获取服务器操作（如错误）返回的结果。

Remix actions 处理服务器端表单提交。您可以使用 useSubmit 钩子将表单数据提交到服务器，使用 useActionData 钩子检索服务器返回的验证错误。

在大多数情况下，HeroUI 的内置验证功能已足够。但如果您正在构建更复杂的表单或将 HeroUI 组件整合到现有表单中，可以使用诸如 React Hook Form 或 Formik 的表单库。

您可以使用 Controller 将 HeroUI 组件与 React Hook Form 集成。Controller 允许您管理字段值和验证错误，并将验证结果映射到 HeroUI 组件。

更多关于 HeroUI 表单的信息，请参阅 React Aria Forms 指南。