v3.0.4

全新 Text 组件、文档主题选择器、采用 min() 上限约束的圆角设计令牌、Table 聚焦环重构，以及多项 bug 修复。

2026 年 5 月

补丁版本：从 HeroUI Pro 移植的全新 Text 复合组件；文档站新增主题选择器，可在不同主题下预览各组件；在约 45 个组件 CSS 文件中将圆角设计令牌改为使用 min() 上限约束；重做 Table 的聚焦环；并修复 Checkbox、Autocomplete、Tooltip 与表单字段内边距等问题。

安装

升级到最新版本：

npm

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

pnpm

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

yarn

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

bun

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

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

新增功能

Text 组件

用于结构化排版的新复合组件，从 HeroUI Pro 移植 (#6479)。会根据子组件或 type prop 自动渲染正确的 HTML 元素——<h1> 至 <h6>、`` 或 <code>。

HeroUI 示例

子组件：Text.Heading、Text.Paragraph、Text.Code、Text.Prose。

各子组件支持的 prop：align、color、weight、truncate。Text.Heading 支持 level（1–6）。Text.Paragraph 支持 size（"base"、"sm"、"xs"）。

使用 Text.Prose 包裹混合内容以获得自动的文章体间距：

<Text.Prose>
  <Text.Heading level={3}>快速开始</Text.Heading>
  <Text.Paragraph>安装依赖包并引入组件。</Text.Paragraph>
</Text.Prose>

文档主题选择器

文档站现内置主题选择器，可在浅色、深色、粗野主义等多种主题下预览每个组件。你的选择会保存到 localStorage，在会话之间保持 (#6471)。

圆角设计令牌

约 45 个组件 CSS 文件中的 rounded-full 与硬编码 border-radius 现均通过 min() 限制计算后的半径 (#6465)。当用户设置过大的自定义圆角主题时，组件外观不再失真——半径在即将超过元素尺寸时停止增大。

Table 聚焦环重构

表格行的聚焦指示改为在每个单元格上使用内阴影分别绘制，而非在整行使用单一 box-shadow。聚焦环在所有单元格之间视觉上保持连续，并在虚拟化表格包装器中正常工作。

Bug 修复

Checkbox：移除选中/半选指示态中硬编码的 accent-hover 背景 (#6487)
Autocomplete：isDisabled 现通过 context 从根节点传递到 Trigger 与 ClearButton (#6443)
Description：移除表单字段中说明文字的多余水平内边距（textfield、color-field、date-field、number-field、search-field、time-field） (#6484)
Tooltip：内边距由 px-2 py-1 调整为 p-2，圆角改为使用设计令牌 (#6481)
Theme Builder：修复 accent-foreground 取值被对调的问题 (#6401)
柔和色对比度：浅色强调主题（Sky、Lavender、Mint）下，accent-soft-foreground 现使用更深一级的色阶，修复次要按钮、Chip 与 Badge 上文字几乎不可见的问题。共享主题现从 --accent-soft-foreground 读取，并回退到 --accent

链接

贡献者

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

安装

npm