# Unistyles v2 到 v3 迁移技巧您正在将 React Native 代码库从react-native-unistyles v2 迁移到v3。严格遵循此工作流程。 v3 是使用 C++ 核心（Nitro 模块）的完全重写，无需重新渲染，并且有一个在构建时处理样式表的 Babel 插件。 ## 先决条件 * 采用新架构的 React Native 0.78.0+ **强制**（从 RN 0.83+ 开始默认启用） * React 19+（由 Unistyles 在运行时强制执行） * `react-native-nitro-modules` （原生桥依赖） * `react-native-edge-to-edge`（Android 边到边插入所需） * Expo SDK 53+（如果使用 Expo；与 Expo Go 不兼容 — 需要开发客户端或预构建） * Xcode 16+ (iOS) ## 迁移工作流程请按顺序执行以下步骤。每个步骤必须先完成，然后才能进行下一步。 ### 第 1 步：安装 v3 并配置 Babel 插件安装 `react-native-unistyles@3` 并添加 Babel 插件： // babel.config.js 模块. 导出 = { 插件：[ ['react-native-unistyles/plugin', { root: 'src' }] // 你的应用源根目录 ] } “root”选项是必需的。它告诉插件哪个目录包含您的应用程序代码。该目录之外的文件（您明确配置的node_modules路径除外）将不会被处理。如果使用 React Compiler，Unistyles 插件必须位于插件数组中的 React Compiler 之前。 ### 步骤 2：用 StyleSheet.configure 替换 UnistylesRegistry - 从'react-native-unistyles'导入{UnistylesRegistry} +从'react-native-unistyles'导入{StyleSheet} - Unistyles注册表 - .addThemes({ light: lightTheme, dark: darkTheme }) - .addBreakpoints({ sm: 0, md: 768, lg: 1200 }) - .addConfig({ - 自适应主题：true， - 初始主题：'黑暗'， - 插件：[myPlugin]， - 实验CSSMediaQueries：true， - windowResizeDebounceTimeMs：100， - 禁用动画插入：true - }) + 样式表.configure({ + 主题：{ 浅色：lightTheme，深色：darkTheme }， + 断点: { sm: 0, md: 768, lg: 1200 }, + 设置：{ + 自适应主题：true， + 初始主题：“黑暗” + } + }) **删除的设置：** `plugins`、`experimentalCSSMediaQueries`（现在始终打开）、`windowResizeDebounceTimeMs`（无反跳）、`disableAnimatedInsets`（插图不再重新渲染）。 ### 步骤 3：替换所有 StyleSheet 导入并 createStyleSheet Unistyles `StyleSheet` 是 React Native 的 `StyleSheet` 的完整填充 - 它包括 `hairlineWidth`、`compose`、`flatten`、`absoluteFill` 和 `absoluteFillObject`。您应该将 **all** `import { StyleSheet } from 'react-native'` 替换为 `import { StyleSheet } from 'react-native-unistyles'`，这样您就可以进行一次导入。 - 从'react-native'导入{StyleSheet} - 从“react-native-unistyles”导入{createStyleSheet} +从'react-native-unistyles'导入{StyleSheet} - const stylesheet = createStyleSheet(主题 => ({ + const styles = StyleSheet.create(主题 => ({ 容器：{ 背景颜色：主题.颜色.背景 } }）） ### 步骤 4：删除所有 useStyles 挂钩 - 从'react-native-unistyles'导入{useStyles} const MyComponent = () => { - const { 样式，主题 } = useStyles(样式表) 返回 } 使用“StyleSheet.create”创建的样式可直接使用 - 无需挂钩。 Babel 插件在构建时处理反应性。 ### 步骤 5：将 useInitialTheme 替换为 settings.initialTheme - 从'react-native-unistyles'导入{useInitialTheme} - - 常量应用程序 = () => { - useInitialTheme(storage.getString('preferredTheme') ?? 'light') - 返回<堆栈/> - } + // 在您的配置调用中： + 样式表.configure({ + 设置：{ + 初始主题: () => storage.getString('preferredTheme') ?? ‘光’ + } + }) `initialTheme` 接受字符串或同步函数。 ### 步骤 6：替换 useStyles() 以进行主题访问对于使用“useStyles()”（没有样式表）只是为了获取主题/运行时的组件： **选项 A - withUnistyles（首选用于传递主题派生的道具）：** 从 'react-native-unistyles' 导入 { withUnistyles } const UniButton = withUnistyles(按钮, (主题, rt) => ({ 颜色：主题.颜色.主色，尺寸：rt.screen.width > 400 ？ “大”：“小” }）） // 用法： **选项 B - useUnistyles 挂钩（快速迁移路径）：** 从 'react-native-unistyles' 导入 { useUnistyles } const MyComponent = () => { const { 主题, rt } = useUnistyles() 返回 {rt.screen.width} } **警告：** 当主题/运行时更改时，`useUnistyles` 会导致重新渲染。出于性能考虑，首选 `withUnistyles` 或 `StyleSheet.create(theme => ...)`。 ### 第 7 步：更新变体选择 - const { styles } = useStyles(stylesheet, { size: 'large', color: 'primary' }) + styles.useVariants({ size: 'large', color: 'primary' }) 在组件顶部调用“styles.useVariants()”（就像一个钩子）。必须在访问使用变体的样式之前调用它。 ### 步骤 8：修复风格传播（关键） v3 样式是 C++ 代理对象。传播打破了束缚。 - + - + 切勿使用“{...styles.x}”。始终使用“[styles.x, styles.y]”数组语法。 ### 步骤 9：删除插件（使用主题中的静态函数代替）插件系统已被删除。将插件替换为主题或样式表中的静态函数： - // 插件方法 (v2) - const fontPlugin: UnistylesPlugin = { - 名称：'字体插件'， - onParsedStyle: (_key, styles) => { - if ('fontWeight' in styles) { - styles.fontFamily = styles.fontWeight === '粗体' ？ 'Roboto-Bold' : 'Roboto-Regular' - } - 返回样式 - } - } + // v3：在主题中使用辅助函数或直接使用 + const styles = StyleSheet.create(主题 => ({ + 文字：{ + fontFamily: theme.utils.getFontFamily('bold') + } + })) ### 第 10 步：删除 UnistylesProvider `UnistylesProvider` 不再存在。只需将其从组件树中删除即可。 ### 步骤 11：更新 UnistylesRuntime 使用情况 **重命名/更改方法：** * `UnistylesRuntime.setImmersiveMode(bool)` 替换单独的状态栏/导航栏隐藏 * `UnistylesRuntime.setRootViewBackgroundColor(color)` \- 不再有 alpha 参数 * `StyleSheet.hairlineWidth` 而不是 `UnistylesRuntime.hairlineWidth` **删除的方法：** * `addPlugin(插件)`, `removePlugin(插件)`, `enabledPlugins` * `statusBar.setColor(color)`, `navigationBar.setColor(color)` **UnistylesRuntime 上的新属性：** * `statusBar`对象带有`setHidden(hidden,animation)`和`setStyle(style)` *带有“setHidden(hidden)”的“navigationBar”对象 * `insets.ime` 用于键盘插入 ### 第 12 步：更新 TypeScript 声明 - type AppThemes = { light: typeof lightTheme, dark: typeof darkTheme } + type AppThemes = typeof主题 // 其中主题 = { light: lightTheme, dark: darkTheme } 声明模块'react-native-unistyles'{ 导出接口 UnistylesThemes 扩展 AppThemes {} + 导出接口 UnistylesBreakpoints 扩展 typeof 断点 {} } ### 步骤 13：更新键盘/IME 处理 - 从“react-native-reanimated”导入{useAnimatedKeyboard} - 常量键盘 = useAnimatedKeyboard() + // 在样式表中使用 ime 插入 + const 样式 = StyleSheet.create((主题, rt) => ({ + 容器：{ + paddingBottom: rt.insets.ime + } + })) ### 第 14 步：设置测试模拟 // jest.setup.js 需要（'react-native-unistyles/mocks'） require('./unistyles.config') // 您的 StyleSheet.configure 调用 Babel 插件在测试环境中自动禁用（`NODE_ENV=test`）。 ## Expo 路由器集成如果项目使用 Expo Router，则需要额外的步骤，因为 Expo Router 在 Unistyles 初始化之前解析路由。 **1\.更改 `package.json` 中的主入口点**： {“主”：“index.ts”} **2\.创建在路由器之前导入 Unistyles 配置的`index.ts`**：导入 'expo-router/entry' import './unistyles' // 你的 StyleSheet.configure() 文件 **3\.对于静态渲染（Expo SDK 52+）：** 还要在 `+html.tsx` 中导入 Unistyles 配置： import '../unistyles' // 确保 Unistyles 为每个静态页面进行初始化从 'expo-router/html' 导入 { ScrollViewStyleReset }；从 'react' 导入 { type PropsWithChildren }; // 该文件仅适用于 Web，用于配置每个文件的根 HTML // 静态渲染期间的网页。 // 该函数的内容仅在 Node.js 环境中运行并且 // 无权访问 DOM 或浏览器 API。导出默认函数 Root({ Children }: PropsWithChildren) { 返回（ <头> {/* 在网络上禁用正文滚动。这使得 ScrollView 组件的工作方式更接近它们在本机上的工作方式。然而，对于移动网络来说，身体滚动通常是很好的选择。如果您想启用它，请删除此行。 */} {/* 添加您希望在网络上全局可用的任何其他元素... */} {孩子} ）； } 有关完整详细信息，请参阅。 ## 快速参考：v2 API 到 v3 v2 | v3 ---|--- `创建样式表` | `样式表.create` `useStyles(样式表)` |直接使用`styles`（无钩子）主题的`useStyles()` `useUnistyles()` 或 `withUnistyles` `useStyles(ss, 变体)` | `styles.useVariants(变体)` `useInitialTheme(名称)` |配置中的“settings.initialTheme” `UnistylesRegistry.addThemes()` | `StyleSheet.configure({ 主题 })` `UnistylesRegistry.addBreakpoints()` | `StyleSheet.configure({ 断点})` `UnistylesRegistry.addConfig()` | `StyleSheet.configure({ 设置})` `UnistylesProvider` |已删除（不需要） `UnistylesPlugin` |删除（使用主题功能） `{...styles.x, ...styles.y}` | `[样式.x, 样式.y]` `UnistylesRuntime.hairlineWidth` | `样式表.hairlineWidth` `statusBar.setColor()` |已删除 `navigationBar.setColor()` |已删除 `从'react-native'导入{StyleSheet}` | `从'react-native-unistyles'导入{StyleSheet}`（完整的polyfill） ## 决策树：第三方组件当第三方组件需要主题值或 Unistyles 样式时： 1. **它接受`style`属性吗？** -> 直接传递 Unistyles 样式（Babel 插件为标准 RN 组件处理它） 2. **是否需要主题衍生的非样式道具（例如`color`）？** -> 用`withUnistyles`包裹 3. **是否来自具有自定义原生视图的库？** -> 在 Babel 插件中配置 `autoProcessPaths` 4. **以上都不起作用？** -> 使用 `useUnistyles()` 钩子作为后备 ## 关键规则 1. **新架构是强制性的** \- 显式启用它（RN 0.83+ 中默认） 2. **切勿传播样式** \- 始终使用数组语法 `[styles.a, styles.b]` 3. **Babel 插件是必需的** \- 没有它，样式将不会响应 4. **仅从 `react-native-unistyles` 导入`StyleSheet` ** \- 它填充了所有 RN StyleSheet API（`hairlineWidth`、`compose`、`flatten`、`absoluteFill` 等），因此请删除任何 `import { StyleSheet } from 'react-native'` 5. **永远不要从桶文件中重新导出`StyleSheet`** - Babel插件不会检测到它 6. **`styles.useVariants()` 必须在组件渲染中访问样式之前调用** 7. **需要React 19+** \- v3使用新的React架构 ## 参考文件 * 有关详尽的前后代码示例：请阅读 [references/migration-patterns.md]() * 对于包含所有重载和选项的完整 v3 API：阅读 [references/v3-api-reference.md]() * 对于错误和已知问题的故障排除：阅读 [references/common-pitfalls.md]()

Unistyles V2 到 V3 迁移

包含技能