heroui-native

HeroUI Native 开发指南

HeroUI Native 是一个组件库，基于 Uniwind（React Native 版 Tailwind CSS） 和 React Native 构建，为移动应用提供无障碍、可自定义的 UI 组件。

---

安装

curl -fsSL https://heroui.com/install | bash -s heroui-native

---

重要：仅限 Native，请勿使用 Web 模式

本指南仅适用于 HeroUI Native。 请勿套用 HeroUI React（Web）的模式，因为两者的包、样式引擎和颜色格式都不同：

特性	React（Web）	Native（移动端）
样式	Tailwind CSS v4	Uniwind（React Native 版 Tailwind）
颜色	oklch 格式	HSL 格式
包	@heroui/react	heroui-native
平台	Web 浏览器	iOS 与 Android

// CORRECT — Native pattern
import { Button } from "heroui-native";

<Button variant="primary" onPress={() => console.log("Pressed!")}>
	Click me
</Button>;

实现前务必先获取 Native 文档。

---

核心原则

• 语义化变体（primary、secondary、tertiary），而非视觉描述
• 组合优于配置（复合组件）
• 使用 HSL 颜色格式的主题变量
• 结合 Uniwind 工具类的 React Native StyleSheet 模式

---

获取文档与组件信息

如需组件详情、示例、属性和实现模式，请始终获取文档：

使用脚本

# List all available components
node scripts/list_components.mjs

# Get component documentation (MDX)
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField

# Get theme variables
node scripts/get_theme.mjs

# Get non-component docs (guides, releases)
node scripts/get_docs.mjs /docs/native/getting-started/theming

直接访问 MDX 链接

组件文档：请使用具体的 kebab-case 路径段获取 .mdx 文件。若不确定路径段，请运行 node scripts/list_components.mjs，且不要获取仍包含占位符的链接。

示例：

• Button：https://heroui.com/docs/native/components/button.mdx
• Dialog：https://heroui.com/docs/native/components/dialog.mdx
• TextField：https://heroui.com/docs/native/components/text-field.mdx

入门指南：请使用具体的主题链接，例如 https://heroui.com/docs/native/getting-started/quick-start.mdx。

重要： 实现前务必先获取组件文档。MDX 文档包含完整的示例、属性、结构说明和 API 参考。

---

安装要点

快速安装

npm i heroui-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

框架设置（Expo，推荐）

1. 安装依赖：

npx create-expo-app MyApp
cd MyApp
npm i heroui-native uniwind tailwindcss
npm i react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

2. 创建 global.css：

@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";

@source "./node_modules/heroui-native/lib";

3. 用 Provider 包裹应用：

import { GestureHandlerRootView } from "react-native-gesture-handler";
import { HeroUINativeProvider } from "heroui-native";
import "./global.css";

export default function Layout() {
	return (
		<GestureHandlerRootView style={{ flex: 1 }}>
			<HeroUINativeProvider>
				<App />
			</HeroUINativeProvider>
		</GestureHandlerRootView>
	);
}

关键设置要求

1. 必须使用 Uniwind：HeroUI Native 基于 Uniwind（React Native 版 Tailwind CSS）
2. 必须使用 HeroUINativeProvider：用 HeroUINativeProvider 包裹应用
3. 必须使用 GestureHandlerRootView：用 react-native-gesture-handler 中的 GestureHandlerRootView 进行包裹
4. 使用复合组件：组件采用复合结构（例如 Card.Header、Card.Body）
5. 使用 onPress，而非 onClick：React Native 使用 onPress 事件处理器
6. 平台特定代码：使用 Platform.OS 处理 iOS 与 Android 的差异

---

组件模式

HeroUI Native 采用复合组件模式。每个组件的子组件都通过点号语法访问。

示例 - Card：

<Card>
	<Card.Header>{/* Icons, badges */}</Card.Header>
	<Card.Body>
		<Card.Title>Title</Card.Title>
		<Card.Description>Description</Card.Description>
	</Card.Body>
	<Card.Footer>{/* Actions */}</Card.Footer>
</Card>

要点：

• 始终使用复合结构，不要将其扁平化为属性
• 子组件通过点号访问（例如 Card.Header）
• Native 版 Card 使用 Card.Body（而非 Card.Content）；Title 和 Description 放在 Body 内
• 如需完整的结构说明和示例，请获取组件文档

---

语义化变体

HeroUI 使用语义化命名来传达功能意图：

变体	用途	用法
primary	推动流程前进的主要操作	每个上下文 1 个
secondary	备选操作	可多个
tertiary	否定性操作（取消、跳过）	谨慎使用
danger	破坏性操作	按需使用
danger-soft	柔和的破坏性操作	视觉权重较低
ghost	低强调操作	视觉权重最低
outline	次要操作	带边框样式

请勿使用原始颜色：语义化变体会自动适配主题与无障碍需求。

---

主题

HeroUI Native 通过 Tailwind/Uniwind 使用 CSS 变量进行主题配置。主题颜色定义在 global.css 中：

@theme {
	--color-accent: hsl(260, 100%, 70%);
	--color-accent-foreground: hsl(0, 0%, 100%);
}

获取当前主题变量：

node scripts/get_theme.mjs

以编程方式访问主题颜色：

import { useThemeColor } from "heroui-native";

const accentColor = useThemeColor("accent");

主题切换（浅色/深色模式）：

import { Uniwind, useUniwind } from "uniwind";

const { theme } = useUniwind();
Uniwind.setTheme(theme === "light" ? "dark" : "light");

如需了解更详细的主题配置，请获取：https://heroui.com/docs/native/getting-started/theming.mdx