Form 表单

用于表单校验与提交处理的包裹组件

用法

1import { Form } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6, e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e, Apache-2.0.3import { Check } from "@gravity-ui/icons";4import { Button, Description, FieldError, Form, Input, Label, TextField } from "@lenso/ui";5import type { FormEvent } from "react";6import * as stylex from "@stylexjs/stylex";7
8const styles = stylex.create({9  form: { display: "flex", flexDirection: "column", width: 384, maxWidth: "100%", gap: 16 },10  actions: { display: "flex", gap: 8 },11});12
13export function Basic() {14  function onSubmit(event: FormEvent<HTMLFormElement>) {15    event.preventDefault();16    const data = Object.fromEntries(new FormData(event.currentTarget).entries());17    alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`);18  }19  return (20    <Form xstyle={styles.form} onSubmit={onSubmit}>21      <TextField22        name="email"23        validate={(value) =>24          /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(String(value))25            ? null26            : "Please enter a valid email address"27        }28      >29        <Label required>Email</Label>30        <Input required type="email" placeholder="[email protected]" />31        <FieldError />32      </TextField>33      <TextField34        name="password"35        validate={(value) => {36          if (String(value).length < 8) return "Password must be at least 8 characters";37          if (!/[A-Z]/.test(String(value)))38            return "Password must contain at least one uppercase letter";39          if (!/[0-9]/.test(String(value))) return "Password must contain at least one number";40          return null;41        }}42      >43        <Label required>Password</Label>44        <Input required minLength={8} type="password" placeholder="Enter your password" />45        <Description>Must be at least 8 characters with 1 uppercase and 1 number</Description>46        <FieldError />47      </TextField>48      <div {...stylex.props(styles.actions)}>49        <Button type="submit">50          <Check aria-hidden="true" />51          Submit52        </Button>53        <Button type="reset" variant="secondary">54          Reset55        </Button>56      </div>57    </Form>58  );59}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

1import {Form, Button} from '@lenso/ui';2
3export default () => (4  <Form>5    {/* Form fields go here */}6    <Button type="submit"/>7    <Button type="reset"/>8  </Form>9)

示例

渲染函数

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6, e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e, Apache-2.0.3import { Check } from "@gravity-ui/icons";4import { Button, Description, FieldError, Form, Input, Label, TextField } from "@lenso/ui";5import type { FormEvent } from "react";6import * as stylex from "@stylexjs/stylex";7
8const styles = stylex.create({9  form: { display: "flex", width: 384, maxWidth: "100%", flexDirection: "column", gap: 16 },10  actions: { display: "flex", gap: 8 },11});12
13export function RenderFunction() {14  function onSubmit(event: FormEvent<HTMLFormElement>) {15    event.preventDefault();16    const data = Object.fromEntries(new FormData(event.currentTarget).entries());17    alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`);18  }19  return (20    <Form21      xstyle={styles.form}22      render={(props) => <form {...props} data-custom="foo" />}23      onSubmit={onSubmit}24    >25      <TextField26        name="email"27        validate={(value) =>28          /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(String(value))29            ? null30            : "Please enter a valid email address"31        }32      >33        <Label required>Email</Label>34        <Input required type="email" placeholder="[email protected]" />35        <FieldError />36      </TextField>37      <TextField38        name="password"39        validate={(value) => {40          const password = String(value);41          if (password.length < 8) return "Password must be at least 8 characters";42          if (!/[A-Z]/.test(password)) return "Password must contain at least one uppercase letter";43          if (!/[0-9]/.test(password)) return "Password must contain at least one number";44          return null;45        }}46      >47        <Label required>Password</Label>48        <Input required minLength={8} type="password" placeholder="Enter your password" />49        <Description>Must be at least 8 characters with 1 uppercase and 1 number</Description>50        <FieldError />51      </TextField>52      <div {...stylex.props(styles.actions)}>53        <Button type="submit">54          <Check aria-hidden="true" />55          Submit56        </Button>57        <Button type="reset" variant="secondary">58          Reset59        </Button>60      </div>61    </Form>62  );63}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6, e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e, Apache-2.0.3import { Button, Form, Input, Label, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5
6const styles = stylex.create({7  form: {8    display: "flex",9    width: 320,10    maxWidth: "100%",11    flexDirection: "column",12    gap: 12,13    borderRadius: 12,14    borderWidth: 1,15    borderStyle: "solid",16    borderColor: "color-mix(in oklch, var(--border) 80%, transparent)",17    backgroundColor: "var(--surface)",18    padding: 16,19    boxShadow: "0 1px 2px 0 rgb(0 0 0 / 0.05)",20  },21  input: { backgroundColor: "var(--field-background)" },22  button: { width: "100%" },23});24
25export function CustomStyles() {26  return (27    <Form xstyle={styles.form} onSubmit={(event) => event.preventDefault()}>28      <TextField name="email">29        <Label required>Work email</Label>30        <Input required type="email" xstyle={styles.input} placeholder="[email protected]" />31      </TextField>32      <Button xstyle={styles.button} type="submit">33        Continue34      </Button>35    </Form>36  );37}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

要自定义表单布局与间距，可在 <Form> 上使用 className prop，或通过 @layer components 添加项目级类。了解更多。

Form 渲染原生 <form> 元素，聚焦校验与提交。@lenso/tokens 中无专用 BEM 类——从全局 CSS 应用容器样式，控件级自定义请使用字段组件。

1@layer components {2  .form-layout {3    @apply flex flex-col gap-4 rounded-xl border border-border bg-surface p-4 shadow-sm;4  }5}

1<Form className="form-layout" onSubmit={handleSubmit}>2  {/* TextField, Input, Button, etc. */}3</Form>

分组字段与共享布局请使用 Fieldset，并定位 .fieldset、.fieldset__legend 等相关类。单个控件请参阅 TextField、Input、Label、FieldError 的 Global CSS 部分。

样式参考

HeroUI 对在 @lenso/tokens 中提供样式的组件遵循 BEM 方法论。

Form 渲染原生 <form> 元素，无专用 BEM 类。通过 className 应用布局、间距与表面样式。字段外观与校验状态来自 TextField、Input、Label、Description、FieldError 等子组件。结构化多字段布局请与 Fieldset 组合使用。

API 参考

Form

Form 组件是 React Aria Form 原语的包裹层，提供表单校验与提交处理能力。

Prop	类型	默认值	描述
`action`	`string \| FormHTMLAttributes['action']`	-	提交表单数据的 URL
`className`	`string`	-	应用于 form 元素的 Tailwind CSS 类
`children`	`React.ReactNode`	-	表单内容（字段、按钮等）
`encType`	`'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'`	-	表单数据提交的编码类型
`method`	`'get' \| 'post'`	-	提交表单时使用的 HTTP 方法
`onInvalid`	`(event: FormEvent<HTMLFormElement>) => void`	-	表单校验失败时调用。默认聚焦第一个无效字段。使用 `preventDefault()` 可自定义聚焦行为
`onReset`	`(event: FormEvent<HTMLFormElement>) => void`	-	表单重置时调用
`onSubmit`	`(event: FormEvent<HTMLFormElement>) => void`	-	表单提交时调用
`target`	`'_self' \| '_blank' \| '_parent' \| '_top'`	-	提交后显示响应的位置
`validationBehavior`	`'native' \| 'aria'`	`'native'`	使用原生 HTML 校验还是 ARIA 校验。`native` 阻止提交，`aria` 实时显示错误
`validationErrors`	`ValidationErrors`	-	按字段名映射的服务端校验错误。立即显示，用户修改字段时清除
`aria-label`	`string`	-	表单的无障碍标签
`aria-labelledby`	`string`	-	标注表单的元素 ID。提供时创建 form landmark
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>`	-	使用自定义 render 函数覆盖默认 DOM 元素

Form Validation

Form 组件集成 React Aria 校验系统，支持：

使用内置 HTML5 校验属性（required、minLength、pattern 等）
在 TextField 组件上提供自定义校验函数
使用 FieldError 组件展示校验错误
在正确校验后处理表单提交
通过 validationErrors prop 提供服务端校验错误

Validation Behavior

validationBehavior prop 控制校验展示方式：

native（默认）：使用原生 HTML 校验，有错误时阻止提交
aria：使用 ARIA 属性校验，用户输入时实时显示错误，不阻止提交

可在表单级或单个字段级设置此行为。

Form Submission

表单可通过多种方式提交：

传统提交：设置 action prop 提交到 URL
JavaScript 处理：使用 onSubmit 处理表单数据
FormData API：在 submit 处理函数中使用 FormData API 访问表单数据

FormData 示例：

1function handleSubmit(e: FormEvent<HTMLFormElement>) {2  e.preventDefault();3  const formData = new FormData(e.currentTarget);4  const data = Object.fromEntries(formData);5  console.log('Form data:', data);6}

Integration with Form Fields

Form 组件与 HeroUI 表单字段组件无缝协作：

TextField：带标签与校验的文本输入
Checkbox：布尔选择
RadioGroup：多选一
Switch：开关控件
Button：提交与重置操作

所有字段组件放在 Form 内时会自动集成 Form 的校验与提交行为。

Advanced Usage

更高级用法包括：

自定义校验上下文
表单 context provider
与第三方库集成
校验错误时的自定义焦点管理

请参阅 React Aria Form 文档。

无障碍

使用 React Aria 组件时，表单默认可访问。主要特性包括：

原生 <form> 元素语义
使用 aria-label 或 aria-labelledby 创建 form landmark
校验错误时自动焦点管理
使用 validationBehavior="aria" 时的 ARIA 校验属性

Form 表单

用法

组件结构

示例

渲染函数

自定义样式

Tailwind CSS

全局 CSS

样式参考

API 参考

Form

Form Validation

Validation Behavior

Form Submission

Integration with Form Fields

Advanced Usage

无障碍

相关案例

相关组件