简介

@skyroc/native-ui 是面向 React Native / Expo 的移动端组件库，使用 Uniwind 和 Tailwind CSS v4 编写。组件与 Web 端共用 @skyroc/tailwind-plugin 里的设计令牌，通过 className、语义色和统一的组件 API 保持一致的开发体验。

核心特性

• Tailwind 写法 — 组件样式用 Uniwind 的 className 表达，静态样式全部走原子类，只有运行时计算值才落到 style。
• 与 Web 同源的令牌 — primary、foreground、muted、border、destructive 等语义色来自 @skyroc/tailwind-plugin，Web 与 Native 共用一套主题定义。
• 无需 dark: 分支 — 主题由宿主应用切换，组件只写语义色，明暗自动跟随。
• 50 个组件 — 覆盖通用、布局、输入、展示、导航、弹层与反馈七大类，表单部分接入 @skyroc/form。
• TypeScript — 组件与类型均从包根路径导出，完整类型推导。

站在巨人的肩膀上

这个库不打算把所有轮子重造一遍。RN 生态里已经有一批打磨多年的库，手势、绘制、弹层这些底层能力交给它们，比自己写一个半成品更靠谱。@skyroc/native-ui 做的是在上面加一层：统一 API 与受控写法、接上设计令牌与暗色主题、把安全区 / 触摸热区 / 按下态这些默认行为补齐。

这层封装的代价是透明的：碰到某个组件的行为边界，答案通常在对应上游库的文档里，而不是这里。完整的依赖与组件对照见 依赖说明。

平台支持

主力目标平台是 Android 与 iOS，组件都在真机与模拟器上验证过。

React Native Web 不是一等公民，能跑但不保证完整：

• 依赖原生模块的组件（Signature 的 Skia、Picker 系的 bottom sheet 与手势、Image 的 expo-image）在 Web 上可能样式错位、交互降级，甚至直接报错。
• 手势驱动的交互（SwipeCell、FloatingButton、IndexBar 的吸附）在鼠标环境下体验不完整，expo-haptics 的触感反馈在 Web 上是空实现。
• 安全区工具类（pt-safe 等）依赖 react-native-safe-area-context，Web 下恒为 0。

需要 Web 端界面时，推荐用同源的 @skyroc/web-ui —— 两边共用 @skyroc/tailwind-plugin 的设计令牌，色板和主题切换是同一套。

上手

import { Button, Text } from '@skyroc/native-ui';
import { View } from 'react-native';

const Panel = () => {
  return (
    <View className="gap-3 rounded-2xl bg-background p-4">
      <Text className="text-lg font-semibold text-foreground">确认提交</Text>
      <Button size="lg">提交</Button>
    </View>
  );
};

组件库依赖 Uniwind 的构建期扫描和几个根节点 Provider，装完包还需要配置 Metro、CSS 入口和根布局才能跑起来：

组件总览

通用

布局容器

输入

数据展示

导航

弹层覆盖

反馈