跳到主要内容

gluestack-ui v2 核心指南

gluestack-ui v2 是一个高性能、跨平台的 UI 组件库，旨在为 Web (React/Next.js) 和 Mobile (React Native) 提供统一的开发体验。它是 NativeBase 的官方继承者，但在性能和开发范式上有了质的飞跃。

1. 核心设计理念​

  • 模块化与“复制粘贴”：不再是传统的全量安装库。v2 采用类似 shadcn/ui 的模式，你可以通过 CLI 只将需要的组件源码下载到项目中，从而实现极致的包体积控制。
  • NativeWind (Tailwind CSS)：底层采用 NativeWind 引擎，支持在 React Native 中使用熟悉的 Tailwind className 语法。
  • RSC 支持：完美支持 React Server Components，提升首屏渲染性能和 SEO。
  • 跨平台一致性：一套组件库，同时兼容 PC Web、移动端 Web、iOS 和 Android。

2. 快速集成 (以 Expo 为例)​

初始化项目​

npx gluestack-ui@latest init

安装 NativeWind 相关依赖​

npx expo install nativewind@^4.0.1 react-native-reanimated tailwindcss

添加组件​

你可以一次性添加所有组件，或者按需添加：

# 添加所有组件
npx gluestack-ui@latest add --all

# 仅添加 Button 和 Box
npx gluestack-ui@latest add button box

3. 基础用法案例​

布局与样式​

利用 Tailwind className 进行快速布局。

import { Box } from "@/components/ui/box";
import { Text } from "@/components/ui/text";
import { VStack } from "@/components/ui/vstack";

export default function Home() {
  return (
    <Box className="flex-1 bg-white p-4">
      <VStack space="md">
        <Text className="text-2xl font-bold text-blue-600">
          Hello gluestack-ui v2
        </Text>
        <Box className="h-20 w-full bg-gray-100 rounded-lg justify-center items-center">
          <Text className="text-gray-500">这是一套通用的 UI 框架</Text>
        </Box>
      </VStack>
    </Box>
  );
}

响应式设计​

gluestack-ui 支持 Tailwind 自带的断点，方便实现 Web 端的多端适配。

<Box className="w-full bg-red-500 md:bg-blue-500 lg:bg-green-500">
  <Text>背景色在不同屏幕尺寸下会发生变化</Text>
</Box>

4. 核心用法与进阶技巧​

1. 组合组件模式 (Compound Components)​

gluestack-ui v2 广泛采用原子化的组合模式，让你对组件的每一部分都有完全的控制权。

import {
  Button,
  ButtonText,
  ButtonIcon,
  ButtonSpinner,
} from "@/components/ui/button";
import { AddIcon } from "@/components/ui/icon";

export function CustomButton({ isLoading }) {
  return (
    <Button
      size="lg"
      variant="solid"
      action="primary"
      isDisabled={isLoading}
      className="rounded-full active:opacity-80"
    >
      {isLoading ? <ButtonSpinner /> : <ButtonIcon as={AddIcon} />}
      <ButtonText className="ml-2">提交订单</ButtonText>
    </Button>
  );
}

2. 源码级定制 (Source Customization)​

由于组件是直接下载到你的项目目录（默认 components/ui）下的，你拥有 100% 的修改权限。

  • 自定义基础样式：直接在 components/ui/button/index.tsx 中修改 Tailwind 常量。
  • 添加新变体 (Variants)：你可以在组件源码中直接扩展新的 variants 配置，而不需要通过包装层，这保持了性能的纯净。

3. 深色模式 (Dark Mode)​

通过 dark: 前缀轻松实现跨平台深色模式。

<Box className="bg-white dark:bg-slate-900 p-4">
  <Text className="text-slate-900 dark:text-white">自动适配系统主题</Text>
</Box>

4. 动画集成 (Reanimated)​

gluestack-ui 完美兼容 react-native-reanimated。你可以直接将组件包裹在 Animated 中，或者使用 Moti。

import Animated, { FadeInUp } from "react-native-reanimated";
import { Box } from "@/components/ui/box";

const AnimatedBox = Animated.createAnimatedComponent(Box);

export function AnimatedItem() {
  return (
    <AnimatedBox entering={FadeInUp.delay(200)} className="bg-blue-500 p-4" />
  );
}

5. 开发建议与避坑​

1. 优先使用 className 而非行内样式​

虽然组件支持原生的 style 属性，但为了利用 NativeWind 的编译优化，应尽可能将所有样式写在 className 中。

2. 处理 Web 端的特殊样式​

如果你需要只在 Web 端生效的样式，可以使用 Tailwind 的 web: 前缀（由 NativeWind 提供支持）：

<Box className="w-full web:cursor-pointer mb-4" />

3. 性能优化：避免过度嵌套​

虽然 VStack 和 HStack 非常方便，但在 React Native 环境下，过深的组件树会导致布局计算压力。对于简单的布局，可以直接使用 Box 配合熟悉的 Flexbox 样式名。

4. 类型安全 (TypeScript)​

gluestack-ui v2 对 TS 的支持非常友好。你可以利用生成的组件类型来增强自己的包装组件：

import { ComponentProps } from "react";
import { Button } from "@/components/ui/button";

type CustomButtonProps = ComponentProps<typeof Button> & {
  customProp: string;
};

6. 什么时候选择 gluestack-ui？​

  1. 多端共用代码：如果你正在开发一个需要同时运行在浏览器和移动 App 上的项目。
  2. Tailwind 爱好者：习惯了 Tailwind 命令式开发，且不想为 React Native 学习另一套样式系统。
  3. 对性能有严格要求：需要替代性能较差的 NativeBase 或其他重量级组件库。

7. 性能对比：为什么它比 NativeBase 快？​

特性NativeBasegluestack-ui v2
样式计算运行时 (Runtime)预编译 + 极小运行时 (AOT)
包体积全量打包，难以 Tree-shaking模块化按需下载 (Copy-Paste)
底层引擎自研解析引擎NativeWind (Tailwind CLI)
SEO 友好度较差 (客户端渲染样式)优 (完全兼容 RSC)

相关资源：