react-native-unistyles-v3

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Native Unistyles v3 Skill

You are assisting with React Native Unistyles v3 styling. v3 is a zero-re-render styling library with a C++ core (Nitro Modules) and Babel plugin that processes StyleSheets at build time. It replaces React Native's

StyleSheet

with a reactive, theme-aware, responsive system.

你正在使用 React Native Unistyles v3 进行样式开发。v3 是一款零重渲染的样式库，核心基于 C++（Nitro Modules），并搭配 Babel 插件在构建时处理 StyleSheet。它取代了 React Native 原生的

StyleSheet

，提供一套响应式、支持主题的样式系统。

Prerequisites

前置条件

React Native 0.78+ with New Architecture mandatory (default from RN 0.83+)
React 19+ (enforced at runtime)
```
react-native-nitro-modules
```
(native bridge dependency)
```
react-native-edge-to-edge
```
(required for Android edge-to-edge insets)
Expo SDK 53+ (if using Expo; not compatible with Expo Go — requires dev client or prebuild)
Xcode 16+ (iOS)

React Native 0.78+，必须启用新架构（RN 0.83+ 默认启用）
React 19+（运行时强制要求）
```
react-native-nitro-modules
```
（原生桥接依赖）
```
react-native-edge-to-edge
```
（Android 端边缘到边缘布局所需）
Expo SDK 53+（若使用 Expo；不兼容 Expo Go —— 需使用开发客户端或预构建）
Xcode 16+（iOS 端）

Workflow

工作流程

Read user's code first — understand current setup, imports, and styling approach
Identify intent — new setup, add theming, responsive design, fix an issue, etc.
Apply v3 patterns — use the correct API from this skill; consult reference files for details
Verify correctness — check for critical rule violations (spreading, barrel re-exports, etc.)

先阅读用户代码 —— 了解当前的配置、导入项和样式实现方式
明确需求意图 —— 是新配置、添加主题、响应式设计、修复问题等
应用 v3 规范 —— 使用本技能中的正确 API；详情可参考参考文件
验证正确性 —— 检查是否违反关键规则（如展开样式、桶文件重导出等）

Quick Reference

快速参考

StyleSheet.create — 3 overloads

StyleSheet.create — 3 种重载形式

tsx

import { StyleSheet } from 'react-native-unistyles'

// 1. Static object compatible with React Native StyleSheet.create
const styles = StyleSheet.create({
  container: { flex: 1, padding: 16 }
})

// 2. Theme function (reactive to theme changes, zero re-renders)
const styles = StyleSheet.create(theme => ({
  container: { backgroundColor: theme.colors.background }
}))

// 3. Theme + miniRuntime function (reactive to theme AND device state)
const styles = StyleSheet.create((theme, rt) => ({
  container: {
    backgroundColor: theme.colors.background,
    paddingTop: rt.insets.top,
    width: rt.screen.width > 768 ? 500 : rt.screen.width - 32
  }
}))

tsx

import { StyleSheet } from 'react-native-unistyles'

// 1. 与 React Native StyleSheet.create 兼容的静态对象
const styles = StyleSheet.create({
  container: { flex: 1, padding: 16 }
})

// 2. 主题函数（响应主题变化，零重渲染）
const styles = StyleSheet.create(theme => ({
  container: { backgroundColor: theme.colors.background }
}))

// 3. 主题 + miniRuntime 函数（响应主题和设备状态变化）
const styles = StyleSheet.create((theme, rt) => ({
  container: {
    backgroundColor: theme.colors.background,
    paddingTop: rt.insets.top,
    width: rt.screen.width > 768 ? 500 : rt.screen.width - 32
  }
}))

StyleSheet.configure — one-time setup

StyleSheet.configure — 一次性配置

tsx

StyleSheet.configure({
  themes: { light: lightTheme, dark: darkTheme },
  breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 },
  settings: {
    initialTheme: 'light',       // or: () => storage.getString('theme') ?? 'light'
    // adaptiveThemes: true,     // auto-switch light/dark based on OS (mutually exclusive with initialTheme)
    // CSSVars: true,            // use CSS custom properties on web
    // nativeBreakpointsMode: 'pixels' | 'points'
  }
})

tsx

StyleSheet.configure({
  themes: { light: lightTheme, dark: darkTheme },
  breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 },
  settings: {
    initialTheme: 'light',       // 或: () => storage.getString('theme') ?? 'light'
    // adaptiveThemes: true,     // 根据系统自动切换亮色/暗色主题（与 initialTheme 互斥）
    // CSSVars: true,            // 在 Web 端使用 CSS 自定义属性
    // nativeBreakpointsMode: 'pixels' | 'points'
  }
})

Variants

变体（Variants）

tsx

const styles = StyleSheet.create(theme => ({
  button: {
    variants: {
      size: {
        small: { padding: 4 },
        medium: { padding: 8 },
        large: { padding: 16 },
      },
      color: {
        primary: { backgroundColor: theme.colors.primary },
        secondary: { backgroundColor: theme.colors.secondary },
      }
    },
    compoundVariants: [
      { size: 'large', color: 'primary', styles: { borderWidth: 2 } }
    ],
  }
}))

// In component — call useVariants BEFORE accessing styles
styles.useVariants({ size: 'large', color: 'primary' })
return <View style={styles.button} />

tsx

const styles = StyleSheet.create(theme => ({
  button: {
    variants: {
      size: {
        small: { padding: 4 },
        medium: { padding: 8 },
        large: { padding: 16 },
      },
      color: {
        primary: { backgroundColor: theme.colors.primary },
        secondary: { backgroundColor: theme.colors.secondary },
      }
    },
    compoundVariants: [
      { size: 'large', color: 'primary', styles: { borderWidth: 2 } }
    ],
  }
}))

// 在组件中 —— 访问变体相关样式前必须调用 useVariants
styles.useVariants({ size: 'large', color: 'primary' })
return <View style={styles.button} />

withUnistyles — wrap third-party components (not React Native or Reanimated components)

withUnistyles — 包装第三方组件（非 React Native 或 Reanimated 组件）

tsx

import { withUnistyles } from 'react-native-unistyles'
import { Button } from 'some-library'

const UniButton = withUnistyles(Button, (theme, rt) => ({
  color: theme.colors.primary,
  size: rt.screen.width > 400 ? 'large' : 'small'
}))

// Usage: <UniButton title="Press me" />

tsx

import { withUnistyles } from 'react-native-unistyles'
import { Button } from 'some-library'

const UniButton = withUnistyles(Button, (theme, rt) => ({
  color: theme.colors.primary,
  size: rt.screen.width > 400 ? 'large' : 'small'
}))

// 使用方式: <UniButton title="Press me" />

Critical Rules

关键规则

NEVER spread styles —
```
{...styles.x}
```
breaks C++ proxy binding. ALWAYS use array syntax:
```
[styles.x, styles.y]
```
or
```
[styles.x, { marginTop: 10 }]
```
NEVER re-export StyleSheet from barrel files — the Babel plugin detects
```
StyleSheet.create
```
by import source. Re-exporting breaks detection.
Babel plugin is REQUIRED — add
```
['react-native-unistyles/plugin', { root: 'src' }]
```
to babel.config.js. Without it, styles won't be reactive.

Import StyleSheet from
react-native-unistyles
only — it polyfills all RN StyleSheet APIs (

hairlineWidth

compose

flatten

absoluteFill

). Replace all

import { StyleSheet } from 'react-native'

styles.useVariants()
must be called before accessing variant-dependent styles — treat it like a React hook (top of component).
Prefer
StyleSheet.create(theme => ...)
over
useUnistyles()
— theme functions cause zero re-renders;
```
useUnistyles()
```
re-renders on every theme/runtime change.
StyleSheet.configure()
must be called before any
StyleSheet.create()
— typically in your app entry point, before any component renders.

绝对不要展开样式 ——
```
{...styles.x}
```
会破坏 C++ 代理绑定。务必使用数组语法：
```
[styles.x, styles.y]
```
或
```
[styles.x, { marginTop: 10 }]
```
绝对不要在桶文件中重导出 StyleSheet —— Babel 插件通过导入源来检测
```
StyleSheet.create
```
。重导出会导致检测失效。
必须启用 Babel 插件 —— 在 babel.config.js 中添加
```
['react-native-unistyles/plugin', { root: 'src' }]
```
。没有该插件，样式将无法响应变化。
仅从
react-native-unistyles
导入 StyleSheet —— 它会兼容所有 RN StyleSheet API（
```
hairlineWidth
```
、
```
compose
```
、
```
flatten
```
、
```
absoluteFill
```
）。替换所有
```
import { StyleSheet } from 'react-native'
```
语句。
styles.useVariants()
必须在访问变体相关样式前调用 —— 请像 React Hook 一样在组件顶部调用。
优先使用
StyleSheet.create(theme => ...)
而非
useUnistyles()
—— 主题函数不会触发重渲染；
```
useUnistyles()
```
会在每次主题/运行时变化时触发重渲染。
StyleSheet.configure()
必须在所有
StyleSheet.create()
之前调用 —— 通常在应用入口文件中调用，在任何组件渲染之前。

Decision Trees

决策树

Choosing a styling approach

选择样式实现方式

Need theme/runtime in styles?
├─ YES → StyleSheet.create((theme, rt) => ...)     [zero re-renders]
└─ NO  → StyleSheet.create({ ... })                [static styles]

Need theme values as non-style props?
├─ YES → withUnistyles(Component, (theme, rt) => ({ propName: theme.value }))
└─ NO  → Pass Unistyles styles via style prop directly

Need theme/runtime in component logic (not just styles)?
├─ YES → useUnistyles() hook                        [causes re-renders]
└─ NO  → Use StyleSheet.create with theme function

需要在样式中使用主题/运行时数据？
├─ 是 → StyleSheet.create((theme, rt) => ...)     [零重渲染]
└─ 否 → StyleSheet.create({ ... })                [静态样式]

需要将主题值作为非样式属性传递？
├─ 是 → withUnistyles(Component, (theme, rt) => ({ propName: theme.value }))
└─ 否 → 直接通过 style 属性传递 Unistyles 样式

需要在组件逻辑中使用主题/运行时数据（而非仅样式）？
├─ 是 → 使用 useUnistyles() Hook                        [会触发重渲染]
└─ 否 → 使用带主题函数的 StyleSheet.create

Third-party component integration

第三方组件集成

Does the component accept a `style` prop?
├─ YES → Pass Unistyles styles directly (Babel auto-processes standard RN views)
│        If it's a custom native view → add to autoProcessPaths in Babel config
├─ NO  → Does it accept theme-derived props (color, size, etc.)?
│        ├─ YES → withUnistyles(Component, (theme, rt) => ({ prop: theme.value }))
│        └─ NO  → useUnistyles() as fallback
└─ Component from node_modules not processed?
   → Add its path to autoProcessPaths or autoProcessImports in Babel plugin config

组件是否支持 `style` 属性？
├─ 是 → 直接传递 Unistyles 样式（Babel 会自动处理标准 RN 视图）
│        如果是自定义原生视图 → 在 Babel 配置中添加到 autoProcessPaths
├─ 否 → 组件是否接受主题衍生属性（如 color、size 等）？
│        ├─ 是 → withUnistyles(Component, (theme, rt) => ({ prop: theme.value }))
│        └─ 否 → 退而使用 useUnistyles()
└─ node_modules 中的组件未被处理？
   → 在 Babel 插件配置中添加其路径到 autoProcessPaths 或 autoProcessImports

Reference Files

参考文件

Setup, installation, Babel plugin, TypeScript, testing, Expo Router: read references/setup-guide.md
Complete API for every export: read references/api-reference.md
Code patterns: themes, variants, breakpoints, web, SSR, Reanimated: read references/styling-patterns.md
withUnistyles, autoProcessPaths, React Compiler, Reanimated, FlatList: read references/third-party-integration.md
Troubleshooting from 150+ GitHub issues with solutions: read references/common-issues.md

安装配置、Babel 插件、TypeScript、测试、Expo Router：查看 references/setup-guide.md
所有导出的完整 API：查看 references/api-reference.md
代码模式：主题、变体、断点、Web、SSR、Reanimated：查看 references/styling-patterns.md
withUnistyles、autoProcessPaths、React Compiler、Reanimated、FlatList：查看 references/third-party-integration.md
问题排查：150+ GitHub 问题及解决方案：查看 references/common-issues.md