# v3.0.0-alpha.34 · HeroUI

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

- 页面: https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

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 服务器](/docs/ui-for-agents/mcp-server)。


## 新增功能

### 基于表单的组件

我们引入了一整套基于 React Aria Components 构建的表单类组件，为构建表单提供了无障碍且可组合的基础构件。这些组件包括 [Description](/systems/heroui/docs/components/description)、[FieldError](/systems/heroui/docs/components/field-error)、[Fieldset](/systems/heroui/docs/components/fieldset)、[Form](/systems/heroui/docs/components/form)、[Input](/systems/heroui/docs/components/input)、[Label](/systems/heroui/docs/components/label)、[RadioGroup](/systems/heroui/docs/components/radio-group)、[TextField](/systems/heroui/docs/components/text-field) 与 [TextArea](/systems/heroui/docs/components/textarea)。

#### Description


> 示例 `description-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34


#### FieldError


> 示例 `field-error-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34


#### Fieldset


> 示例 `fieldset-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34


#### Form


> 示例 `form-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34


#### Input


> 示例 `input-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34


#### Label


> 示例 `label-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34


#### RadioGroup


> 示例 `radio-group-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34


#### TextField


> 示例 `text-field-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34


#### TextArea


> 示例 `textarea-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-alpha-34


### 表单字段 token

引入 `--field-*` 表单字段 token，确保各表单组件之间样式保持一致。`--field-*` 变量的具体说明请参阅 [主题](/systems/heroui/docs/getting-started/theming#calculated-variables-tailwind)。

### Storybook 重新组织

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

### Skeleton 动画 token

**🚧 破坏性变更：** 为了与其他组件 token 保持一致，[Skeleton](/systems/heroui/docs/components/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 定位：

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

## 文档改进

### 组件文档
- **[Link](/systems/heroui/docs/components/link)**：新增 anatomy 与带图标的示例，更新了 Link 与 Link.Icon 的 prop 章节。
- **[Description](/systems/heroui/docs/components/description)**、**[FieldError](/systems/heroui/docs/components/field-error)**、**[Fieldset](/systems/heroui/docs/components/fieldset)**、**[Form](/systems/heroui/docs/components/form)**、**[Input](/systems/heroui/docs/components/input)**、**[Label](/systems/heroui/docs/components/label)**、**[RadioGroup](/systems/heroui/docs/components/radio-group)**、**[TextField](/systems/heroui/docs/components/text-field)**，以及 **[TextArea](/systems/heroui/docs/components/textarea)**：附带使用示例的全新文档


## 迁移指南

### Skeleton 组件迁移

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

## 链接

- [GitHub PR #5780](https://github.com/heroui-inc/heroui/pull/5780)
- [Description 组件](/systems/heroui/docs/components/description)
- [FieldError 组件](/systems/heroui/docs/components/field-error)
- [Fieldset 组件](/systems/heroui/docs/components/fieldset)
- [Form 组件](/systems/heroui/docs/components/form)
- [Input 组件](/systems/heroui/docs/components/input)
- [Label 组件](/systems/heroui/docs/components/label)
- [RadioGroup 组件](/systems/heroui/docs/components/radio-group)
- [TextField 组件](/systems/heroui/docs/components/text-field)
- [TextArea 组件](/systems/heroui/docs/components/textarea)
- [Skeleton 组件](/systems/heroui/docs/components/skeleton)

## 贡献者

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

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt