v3.0.0-alpha.34

2025 年 10 月 15 日

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

安装

升级到最新版本：

npm

```bash
npm i @heroui/styles@alpha @heroui/react@alpha
```

pnpm

```bash
pnpm add @heroui/styles@alpha @heroui/react@alpha
```

yarn

```bash
yarn add @heroui/styles@alpha @heroui/react@alpha
```

bun

```bash
bun add @heroui/styles@alpha @heroui/react@alpha
```

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

新增功能

基于表单的组件

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

Description

FieldError

Fieldset

Form

Input

Label

RadioGroup

TextField

TextArea

表单字段 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 定位：

.radio {
  [data-slot="label"] {
    /* Styles apply to radio labels */
  }
}

文档改进

组件文档

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

迁移指南

Skeleton 组件迁移

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

链接

• GitHub PR #5780
• Description 组件
• FieldError 组件
• Fieldset 组件
• Form 组件
• Input 组件
• Label 组件
• RadioGroup 组件
• TextField 组件
• TextArea 组件
• Skeleton 组件

贡献者

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