v3.0.0-alpha.34

用 Form、TextField、RadioGroup、Label、Input、Fieldset 等简洁 API 构建表单的核心组件。

2025 年 10 月 15 日

此版本引入了一系列基于表单的组件、表单字段 token，重新组织了 Storybook，并对各组件之间的 data-slot 标识做了统一对齐。

安装

升级到最新版本：

1npm i @lenso/tokens@alpha @lenso/ui@alpha

正在使用 AI 助手？ 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 HeroUI MCP 服务器。

新增功能

基于表单的组件

我们引入了一整套基于 React Aria Components 构建的表单类组件，为构建表单提供了无障碍且可组合的基础构件。这些组件包括 Description、FieldError、Fieldset、Form、Input、Label、RadioGroup、TextField 与 TextArea。

Description

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

1"use client";2// Adapted from HeroUI v3.2.6, Apache-2.0.3import { Description, Input, Label } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { useId } from "react";6import { demoStyles } from "../../demo.stylex";7
8export function Basic() {9  const id = useId();10  return (11    <div {...stylex.props(demoStyles.column)}>12      <Label htmlFor={id}>Email</Label>13      <Input14        aria-describedby={`${id}-description`}15        xstyle={demoStyles.field}16        id={id}17        placeholder="[email protected]"18        type="email"19      />20      <Description id={`${id}-description`}>21        We'll never share your email with anyone else.22      </Description>23    </div>24  );25}

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

FieldError

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

1"use client";2// Adapted from HeroUI v3.2.6, Apache-2.0.3import { FieldError, Input, Label, TextField } from "@lenso/ui";4import { useState } from "react";5import { demoStyles } from "../../demo.stylex";6
7export function Basic() {8  const [value, setValue] = useState("jr");9  const invalid = value.length > 0 && value.length < 3;10  return (11    <TextField xstyle={demoStyles.field} invalid={invalid}>12      <Label>Username</Label>13      <Input placeholder="Enter username" value={value} onValueChange={setValue} />14      {invalid && <FieldError match>Username must be at least 3 characters</FieldError>}15    </TextField>16  );17}

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

Fieldset

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

1"use client";2// Adapted from HeroUI v3.2.6, Apache-2.0.3import { FloppyDisk } from "@gravity-ui/icons";4import {5  Button,6  Description,7  FieldError,8  FieldGroup,9  Fieldset,10  Form,11  Input,12  Label,13  TextArea,14  TextField,15} from "@lenso/ui";16import { useId, type FormEvent } from "react";17import { demoStyles } from "../../demo.stylex";18
19export function Basic() {20  const descriptionId = useId();21  function onSubmit(event: FormEvent<HTMLFormElement>) {22    event.preventDefault();23    alert("Form submitted successfully!");24  }25  return (26    <Form xstyle={demoStyles.wideColumn} onSubmit={onSubmit}>27      <Fieldset aria-describedby={descriptionId}>28        <Fieldset.Legend>Profile Settings</Fieldset.Legend>29        <Description id={descriptionId}>Update your profile information.</Description>30        <FieldGroup>31          <TextField32            name="name"33            validate={(value) =>34              String(value).length < 3 ? "Name must be at least 3 characters" : null35            }36          >37            <Label required>Name</Label>38            <Input required placeholder="John Doe" />39            <FieldError />40          </TextField>41          <TextField name="email">42            <Label required>Email</Label>43            <Input required type="email" placeholder="[email protected]" />44            <FieldError />45          </TextField>46          <TextField47            name="bio"48            validate={(value) =>49              String(value).length < 10 ? "Bio must be at least 10 characters" : null50            }51          >52            <Label required>Bio</Label>53            <TextArea required placeholder="Tell us about yourself..." />54            <Description>Minimum 10 characters</Description>55            <FieldError />56          </TextField>57        </FieldGroup>58        <Fieldset.Actions>59          <Button type="submit">60            <FloppyDisk aria-hidden="true" />61            Save changes62          </Button>63          <Button type="reset" variant="secondary">64            Cancel65          </Button>66        </Fieldset.Actions>67      </Fieldset>68    </Form>69  );70}

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

Form

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

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.

Input

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

1"use client";2
3import { Input } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5
6// HeroUI v3.2.6, e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e, Apache-2.0.7const styles = stylex.create({ field: { width: 256 } });8export function Basic() {9  return <Input aria-label="Name" xstyle={styles.field} placeholder="Enter your name" />;10}

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

Label

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

1"use client";2// Adapted from HeroUI v3.2.6, Apache-2.0.3import { Input, Label } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { useId } from "react";6import { demoStyles } from "../../demo.stylex";7
8export function Basic() {9  const id = useId();10  return (11    <div {...stylex.props(demoStyles.column)}>12      <Label htmlFor={id}>Name</Label>13      <Input xstyle={demoStyles.field} id={id} placeholder="Enter your name" type="text" />14    </div>15  );16}

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

RadioGroup

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

1export { Basic } from "./examples";

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

TextField

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

1"use client";2
3// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.4import { Input, Label, TextField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({ field: { width: "100%", maxWidth: 256 } });7
8export function Basic() {9  return (10    <TextField name="email" xstyle={styles.field}>11      <Label>Email</Label>12      <Input type="email" placeholder="Enter your email" />13    </TextField>14  );15}

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

TextArea

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

1"use client";2
3// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.4import { TextArea } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6
7const styles = stylex.create({ field: { width: 384, height: 128 } });8export function Basic() {9  return (10    <TextArea11      aria-label="Quick project update"12      xstyle={styles.field}13      placeholder="Share a quick project update..."14    />15  );16}

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

表单字段 token

引入 --field-* 表单字段 token，确保各表单组件之间样式保持一致。--field-* 变量的具体说明请参阅主题。

Storybook 重新组织

按类别重新组织了 Storybook，方便导航与组件查找。

Skeleton 动画 token

🚧 破坏性变更： 为了与其他组件 token 保持一致，Skeleton 中的 --skeleton-default-animation-type 已重命名为 --skeleton-animation。

data-slot 对齐

我们统一了各组件的 data-slot 标识，使样式与定制更加一致。这项标准化让通过 CSS 选择器定位特定组件部件变得更容易，整体上也优化了自定义组件样式时的开发体验。

组件现在使用一致的 data-slot 属性，例如：

data-slot="base" —— 用于根元素
data-slot="label" —— 用于标签文本
data-slot="description" —— 用于描述文本
data-slot="error" —— 用于错误信息

这样在所有表单组件中都能用可预期的方式进行 CSS 定位：

1.radio {2  [data-slot="label"] {3    /* Styles apply to radio labels */4  }5}

文档改进

组件文档

Link：新增 anatomy 与带图标的示例，更新了 Link 与 Link.Icon 的 prop 章节。
Description、FieldError、Fieldset、Form、Input、Label、RadioGroup、TextField，以及 TextArea：附带使用示例的全新文档

迁移指南

Skeleton 组件迁移

更新动画 token：
- 将 --skeleton-default-animation-type 替换为 --skeleton-animation

链接

贡献者

感谢每一位为本次发布做出贡献的开发者！