快速开始
安装依赖并配置主题宿主后,即可使用组件。以下示例演示亮暗主题的接入。
环境要求
支持矩阵严格来自 package.json#peerDependencies,本仓直接验证的版本是 React Native 0.88.0 + React 19.3.0:
下表列出本仓开发与验证组合。消费端按自己的锁文件核对实际版本;主题、手势和布局仍需在目标设备验收,不能将本仓结果外推到全部 peer 范围。
| 依赖 | 支持范围 | 本仓验证版本 |
|---|---|---|
react-native | >=0.86.0 | 0.88.0 |
react | >=19.2.3 <20.0.0 | 19.3.0 |
react-native-gesture-handler | >=3.0.0 <4.0.0 | 3.1.0 |
react-native-reanimated | >=4.5.2 <4.8.0 | 4.7.1 |
react-native-worklets | >=0.11.0 <0.14.0 | 0.13.0 |
react-native-reanimated-carousel | >=5.0.0 <6.0.0 | 5.0.0 |
react-native-safe-area-context | >=5 | 5.8.0 |
react-native-svg | >=15 | 15.16.0 |
@callstack/liquid-glass | >=0.8.2 <0.9.0 | 0.8.2 |
@unif/react-native-icons | >=0.1.0 | 0.4.1 |
@unif/react-native-logger | ^0.2.0 | 以锁文件为准 |
- RN
0.88.0开发基线要求 Node.js^22.13.0 || ^24.3.0 || >= 26.0.0;本仓.nvmrc固定v24.13.0,使用 Yarn 4。根devEngines与 example/websiteengines声明此范围。 - 公开包的
package.json#engines保留^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0,兼容已有 RN0.86+消费者;消费者还必须满足自己安装的 RN 版本要求。 - TypeScript 6
本库面向 RN 0.86+ 新架构(Fabric + TurboModules),支持 react-native-reanimated@4.5/4.6/4.7 + react-native-worklets@0.11/0.12/0.13。旧架构(Bridge)与 RN 0.85 及更低版本不在支持范围 —— 发布 contract 是 >=0.86.0,不封顶;当前验证基线为 RN 0.88.0。
安装依赖
1. 装本库
yarn add @unif/react-native-design
2. 装 peer dependencies
本库不打包下列依赖,宿主工程必须自行安装并完成原生侧配置。缺任一,Metro 打包或运行时就会报 Unable to resolve module / Cannot find module。
yarn add @unif/react-native-icons @unif/react-native-logger@^0.2.0 react-native-svg \
react-native-gesture-handler \
react-native-reanimated \
react-native-worklets \
react-native-safe-area-context \
react-native-reanimated-carousel \
@callstack/liquid-glass
iOS 装完原生包后,在 ios/ 目录执行 bundle exec pod install 并重新构建。Liquid Glass 需 Xcode 26+;iOS 26+ 且原生支持标记为真、未启用减少透明度时使用原生玻璃;Android、旧 iOS 或原生玻璃不可用时使用主题实色背景。Web 使用 CSS 近似效果,无 CSS 模糊能力且未启用减少透明度时保留主题渐变。Expo Go 不支持此原生模块,Expo 工程需开发构建。组件契约见 GlassLayer。
版本范围见上方环境要求表格,唯一事实来源是
package.json#peerDependencies。
Design 的既有 createLogger、级别与 transport 接口复用 Logger 的同一默认后端,仍接受消息和可变参数。应用需要结构化日志或文件记录时,从 @unif/react-native-logger 初始化一次运行时并使用其结构化 createLogger;库本身不初始化文件存储。仅使用 Design 不需要安装 Logger 文件入口的原生文件依赖。两种 createLogger 签名不同,不能互相替换。
react-native-worklets 的 Babel 插件与 Metro transformer 由宿主工程提供,不随本库分发。宿主必须装上与自身 RN 版本匹配的 @babel/core、@react-native/babel-preset 和 @react-native/metro-config;本仓验证的是 RN 0.88.0 与对应 0.88.0 工具链,否则 worklet 编译会静默降级或直接报错。
本包要求 Gesture Handler 3.x,但 react-native-reanimated-carousel@5.0.0 发布的 peer 范围是 >=2.9.0 <3.0.0,与本包的 >=3.0.0 <4.0.0 没有交集。本仓开发组合使用两者,check:runtime-peers 对这项已知差异进行精确校验;包管理器仍会报告 peer 警告,消费端还需验证实际手势。
只有两种被认可的处理方式:接受这一条警告,或加只作用于 Carousel 的窄 override / filter。
npm:
{
"overrides": {
"react-native-reanimated-carousel": {
"react-native-gesture-handler": "$react-native-gesture-handler"
}
}
}
$react-native-gesture-handler 会复用消费端根依赖中满足 >=3.0.0 <4.0.0 的版本,避免装第二份 Gesture Handler。
pnpm 用 pnpm.peerDependencyRules.allowedVersions 精确到 react-native-reanimated-carousel>react-native-gesture-handler;Yarn 用 scoped logFilters。
禁止全局 peer 忽略、--force、--legacy-peer-deps 或无效的 packageExtensions / metadata patch —— 那会连同真实的 major 漂移一起吞掉。
本仓 .yarnrc.yml 没有配置 logFilters,消费端按自己的包管理器处理这条警告。本仓使用 yarn check:runtime-peers 精确校验包名、请求方 locator、range 和 provider major,任一维度漂移即失败;该检查与日志过滤无关。
3. 配 babel(worklets 插件必须最后)
// babel.config.js —— react-native-worklets/plugin 必须排在 plugins 数组最后
module.exports = {
presets: ['module:@react-native/babel-preset'],
plugins: [
// ... 其它插件
'react-native-worklets/plugin',
],
};
根挂 Provider 与 Host
App 根按 GestureHandlerRootView → SafeAreaProvider → ThemeProvider → App 内容 + Hosts 装配。SafeAreaProvider 必须从 react-native-safe-area-context 这个 peer 包导入;设计系统组件与函数仍只从 @unif/react-native-design 包根导入:
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import {
ConfirmHost,
ThemeProvider,
ToastHost,
} from '@unif/react-native-design';
export function App() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<SafeAreaProvider>
<ThemeProvider>
{/* 你的导航 / 屏幕 */}
<ToastHost />
<ConfirmHost />
</ThemeProvider>
</SafeAreaProvider>
</GestureHandlerRootView>
);
}
ThemeProvider—— 读取useColorScheme(),自动跟随系统亮暗。ToastHost/ConfirmHost—— 都会读取安全区 context;各挂一个,且必须位于SafeAreaProvider内。要在 RNModal里显示 toast / confirm 时,可在 Modal 的内容树里再挂一份:后挂载的接管、卸载自动归还(Modal是独立 native window,根上那份会被它盖住)。
若宿主还使用键盘或导航 Provider,可在不破坏上述相对顺序的前提下加入,例如 GestureHandlerRootView → KeyboardProvider → SafeAreaProvider → ThemeProvider → NavigationContainer + Hosts。ThemeProvider 接受 forceScheme?: 'light' | 'dark' 强制某主题(用于测试 / 设置项接入)。
第一个主题化组件
颜色 / 阴影走 useThemedStyles(maker),自动跟随亮暗。makeStyles 必须定义在模块顶层 —— 内联进组件会让引用每次渲染都变、打穿缓存。
import { StyleSheet, View, Text } from 'react-native';
import {
Button,
useThemedStyles,
type ColorTokens,
} from '@unif/react-native-design';
// ✅ 模块顶层定义 maker:(colors, shadow) => StyleSheet
const makeStyles = (c: ColorTokens) =>
StyleSheet.create({
wrap: { padding: 16, backgroundColor: c.surface },
title: { color: c.foreground, fontSize: 17, fontWeight: '600' },
});
export function Demo() {
const styles = useThemedStyles(makeStyles);
return (
<View style={styles.wrap}>
<Text style={styles.title}>今日待办</Text>
<Button label="保存" variant="primary" onPress={() => {}} />
</View>
);
}
只需 inline 取一两个颜色(状态映射 / prop fallback)时,用 useColors():
import { useColors } from '@unif/react-native-design';
function Banner({ active }: { active: boolean }) {
const c = useColors(); // 跟随亮暗
return (
<View
style={{ backgroundColor: active ? c.primary : c.surfaceContainer }}
/>
);
}
命令式 API
挂好 host 后,任意位置可直接调用:
import { toast } from '@unif/react-native-design';
toast.success('已保存');