2025 年 10 月 1 日

此版本新增了用于 AI 开发的工具，并更新了 Card 组件的 API，以提升开发者体验。

安装

升级到最新版本：

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

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

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

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

新增功能

MCP 服务器

HeroUI 现已包含一个 MCP 服务器，可让 Cursor、Claude Code、VS Code Copilot 等 AI 助手直接访问 HeroUI v3 的文档与组件信息。

快速配置：

Cursor

Install in Cursor

或在 Cursor Settings → Tools → MCP Servers 中手动添加：

{
  "mcpServers": {
    "heroui-react": {
      "command": "npx",
      "args": ["-y", "@heroui/react-mcp@latest"]
    }
  }
}

Claude Code

在终端中运行以下命令：

claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest

了解更多

Card 组件 API 重新设计

Card 组件已升级到全新的变体系统，使用更加灵活。

破坏性变更：

将 surface prop 替换为新的 variant 系统
移除了 Card.Image、Card.Details 与 Card.CloseButton（请改用组合方式实现）
新增变体：flat、outlined、elevated、filled

之前：

<Card surface="1">
  <Card.Image src="/image.jpg" />
  <Card.Details>
    <Card.Title>Old Card</Card.Title>
  </Card.Details>
</Card>

之后：

<Card variant="outlined">
  <Card.Header>
    <img src="/image.jpg" alt="Card image" />
  </Card.Header>
  <Card.Body>
    <Card.Title>New Card</Card.Title>
  </Card.Body>
</Card>

新功能：

支持水平布局
与 Avatar 集成
支持背景图片
通过语义化 HTML 提升无障碍体验

查看 Card 组件文档

CloseButton 组件

新增 CloseButton 组件，用于关闭对话框、模态框以及其他可关闭的元素。

import {CloseButton} from "@heroui/react";

// Basic usage
<CloseButton onPress={() => console.log("Closed")} />

// With custom icon
<CloseButton>
  <XMarkIcon className="size-4" />
</CloseButton>

文档改进

面向 AI 的 UI

MCP 服务器文档 —— 介绍如何借助 AI 助手进行开发
llms.txt —— 对 LLM 更友好的文档文件
主流 AI 编码工具的配置指南

组件文档

Card：重写了文档，包含 anatomy、变体与更多示例
Switch：新增 anatomy 示意图与更完善的示例
CloseButton：全新文档，附带使用示例

迁移指南

Card 组件迁移

更新 variant prop：
- surface="1" → variant="flat"
- surface="2" → variant="outlined"
- surface="3" → variant="elevated"
- surface="4" → variant="filled"
- 自定义 surface → 改用新的变体系统
更新组件结构：
- 将 Card.Image 替换为放在 Card.Header 中的 <img>
- 将 Card.Details 替换为 Card.Body
- 将 Card.CloseButton 迁移为使用新的 CloseButton 组件

更新导入：

// Add CloseButton if needed
import {Card, CloseButton} from "@heroui/react";

链接

贡献者

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

v3.0.0-alpha.32

安装