八、添加新组件与版本更新
8.1 使用 CLI 添加组件
# 添加单个组件
npx heroui-cli@latest add button
# 添加多个组件
npx heroui-cli@latest add modal dropdown toast
CLI 会自动：
检查组件是否已安装
安装缺失的依赖
更新 tailwind.config.js 的 content 数组（如果需要）
在项目中生成组件文件（如果选择"复制模式"）
8.2 手动安装完整包
npm install @heroui/react framer-motion
8.3 版本更新日志摘要
v3.0.0-beta.2（2025年11月）
新增组件：
AlertDialog - 需要用户确认的重要决策对话框
ComboBox - 带筛选功能的输入框 + 下拉列表
Dropdown - 操作菜单
InputGroup - 组合输入控件
NumberField - 带增减按钮的数字输入
Modal 独立发布
破坏性变更：
Select.Content 重命名为 Select.Popover
Chip 组件的尺寸调整：sm: px-1 py-0 text-xs
v3.0.0-beta.4（2026年1月）
新增组件：
Autocomplete - 带筛选的自动补全
Breadcrumbs - 面包屑导航
Toast - 全局通知
新增功能：
Theme Builder 可视化主题编辑器
Tabs 组件的 secondary 变体
Input/InputGroup 新增 primary 和 secondary 变体
破坏性变更：
移除了 Link 组件的 underline 变体
移除了表单组件的 isInSurface prop
九、无障碍（ARIA）设计准则
9.1 为什么无障碍很重要？
HeroUI 所有组件都基于 React Aria 构建，这意味着无障碍特性是内置的、默认的、不可妥协的。
9.2 键盘导航支持
9.3 屏幕阅读器支持
所有组件都包含完整的 ARIA 标签：
aria-label / aria-labelledby：为元素提供描述
aria-describedby：关联描述文字
aria-invalid：指示验证失败状态
aria-required：指示必填字段
role 属性：定义元素在无障碍树中的角色
9.4 开发中测试无障碍
# 安装 axe-core 扩展（浏览器扩展）
# 然后运行无障碍测试
npx @axe-core/cli http://localhost:3000
9.5 焦点管理
Form 组件在 onInvalid 事件中默认将焦点移动到第一个无效字段：
<Form
onInvalid={(event) => {
// 默认行为是聚焦第一个无效字段
// 使用 preventDefault() 可以禁用此行为
event.preventDefault();
// 自定义焦点逻辑
console.log("表单验证失败");
}}
>
十、Figma 集成：设计到代码的工作流
10.1 设计令牌同步
HeroUI 提供了 Figma Kit，设计师可以在 Figma 中使用与开发者完全相同的设计令牌。
工作流程：
设计师在 Figma 中安装 HeroUI Design Kit
使用 HeroUI 组件库搭建页面设计稿
导出自定义主题的 JSON 文件
开发者将主题 JSON 转换为 Tailwind 配置
10.2 主题转换示例
# 安装转换工具
npm install -g figma-to-tailwind
# 导出 Figma 变量后转换
figma-to-tailwind --input tokens.json --output theme.js --format css-vars
10.3 设计系统维护
通过 Figma + HeroUI 的集成，团队可以实现：
设计变更自动通知开发
视觉一致性的自动化验证
减少 70% 的 UI 沟通成本
十一、常见问题与解决方案
11.1 Next.js App Router 特殊配置
问题：Modal 中的 Link 组件导致整页刷新
解决方案：在 Provider 中配置 navigate 函数
import { useRouter } from "next/navigation";
<HeroUIProvider navigate={useRouter().push}>
{children}
</HeroUIProvider>
11.2 样式不生效/类名冲突
问题：自定义 className 不生效
https://wkmsa.cn/
解决方案：
检查 tailwind.config.js 中的 content 数组是否包含组件路径
确认 postcss.config.js 中包含 Tailwind CSS 插件
检查是否有其他 CSS 框架（如 Bootstrap）的类名冲突
11.3 暗色模式不切换
问题：页面不响应主题切换
解决方案：
// 确保 Provider 包裹了整个应用
// 确保暗色模式类名是 ".dark"
import { HeroUIProvider } from "@heroui/react";
// 手动触发暗色模式
document.documentElement.classList.add("dark");
11.4 TypeScript 类型错误
问题：组件 props 类型不匹配
解决方案：
// 确保安装类型定义
npm install @types/react @types/react-dom
// 导入组件时使用类型
import type { ButtonProps } from "@heroui/react";
11.5 性能问题：Select 渲染卡顿
解决方案：
// 开启虚拟化
<Select isVirtualized items={largeList} />
// 或使用懒加载
<Select items={items.slice(0, 50)} onLoadMore={loadMore} />
11.6 动画在移动设备上卡顿
解决方案：
// 全局禁用动画
<HeroUIProvider disableAnimation>
{children}
</HeroUIProvider>
// 或针对单个组件
<Modal isOpen={isOpen} disableAnimation>
<!-- Modal 内容 -->
</Modal>
对于开发者和团队来说，现在正是深入了解 HeroUI 的最佳时机——它不是一个"另一个 UI 库"，而是一套融合了现代前端最佳实践、无障碍设计、性能优化和 AI 编程支持的全栈设计系统。
