asset-homepage/HEROUI-GUIDE.md

HeroUI 使用指南

已完成的配置

✅ 安装了 HeroUI 核心包：

• @heroui/react - React 组件库
• @heroui/theme - 主题系统
• framer-motion - 动画库

✅ 升级到 Tailwind CSS 4

✅ 更新配置文件：

• tailwind.config.ts - 添加了 HeroUI 插件和内容路径
• postcss.config.mjs - 更新为使用 @tailwindcss/postcss
• components/Providers.tsx - 添加了 HeroUIProvider

如何使用 HeroUI 组件

1. 导入组件

import { Button, Card, CardBody, Input, Navbar, NavbarBrand } from '@heroui/react';

2. 常用组件示例

Button（按钮）

<Button color="primary">点击我</Button>
<Button color="secondary" variant="bordered">边框按钮</Button>
<Button isLoading>加载中...</Button>

Card（卡片）

<Card>
  <CardBody>
    <p>这是卡片内容</p>
  </CardBody>
</Card>

Input（输入框）

<Input
  type="email"
  label="Email"
  placeholder="输入你的邮箱"
/>

Navbar（导航栏）

<Navbar>
  <NavbarBrand>
    <p className="font-bold text-inherit">ACME</p>
  </NavbarBrand>
</Navbar>

3. 主题定制

在 tailwind.config.ts 中自定义主题：

import { heroui } from "@heroui/theme";

export default {
  plugins: [
    heroui({
      themes: {
        light: {
          colors: {
            primary: {
              DEFAULT: "#0070f3",
              foreground: "#ffffff",
            },
          },
        },
        dark: {
          colors: {
            primary: {
              DEFAULT: "#0070f3",
              foreground: "#ffffff",
            },
          },
        },
      },
    }),
  ],
}

4. 使用暗色模式

HeroUI 自动支持暗色模式，已配置 darkMode: "class"：

// 在你的 ThemeContext 中已经实现
const { theme, toggleTheme } = useTheme();

HTML 元素会自动添加/移除 dark class。

可用的组件

HeroUI 提供了丰富的组件：

布局组件

• Navbar - 导航栏
• Card - 卡片
• Divider - 分隔线
• Spacer - 间距

表单组件

• Button - 按钮
• Input - 输入框
• Textarea - 多行文本框
• Select - 下拉选择
• Checkbox - 复选框
• Radio - 单选框
• Switch - 开关

数据展示

• Table - 表格
• Avatar - 头像
• Badge - 徽章
• Chip - 标签
• Progress - 进度条

反馈组件

• Modal - 模态框
• Tooltip - 提示框
• Popover - 弹出框
• Dropdown - 下拉菜单

导航组件

• Tabs - 标签页
• Breadcrumbs - 面包屑
• Pagination - 分页
• Link - 链接

示例：重构现有组件

重构前（原生 HTML）

<button className="bg-[#111827] rounded-lg px-5 py-2.5 hover:opacity-90">
  <span className="text-white font-bold">Launch App</span>
</button>

重构后（HeroUI）

<Button
  color="default"
  variant="solid"
  className="font-bold"
>
  Launch App
</Button>

文档链接

• HeroUI 官网
• 组件文档
• 主题定制
• 暗色模式

下一步

1. 逐步将现有组件重构为使用 HeroUI
2. 利用 HeroUI 的主题系统统一样式
3. 使用 HeroUI 的内置暗色模式支持
4. 享受更好的可访问性和响应式设计