SuperAPI AI 工具集

unistyles-v2-to-v3-migration

编程与开发

查看项目

更新于 10-15 23:42

技能介绍

用途:把 React Native 代码库从 react-native-unistyles v2 升级到 v3,按固定工作流逐步执行,每步完成后才进入下一步。

主要能力:安装 v3 并配置 Babel 插件;用 StyleSheet.configure 替换 UnistylesRegistry(themes、breakpoints、settings);替换全部 StyleSheet 导入与 createStyleSheet;移除 useStyles 钩子;用 settings.initialTheme 替换 useInitialTheme;用 withUnistyles 或 useUnistyles 获取主题;用 styles.useVariants 做变体选择;修正样式展开为数组语法;移除插件与 UnistylesProvider;更新 UnistylesRuntime 与系统栏/insets API;更新 TypeScript 声明;更新键盘/IME 处理;配置测试 mock;提供 Expo Router 集成步骤。

必要用法:先满足前置条件——React Native 0.81.0+ 且强制新架构、React 19+、react-native-nitro-modules(3.4.0+ 需 0.37.1+)、Expo SDK 54+(不兼容 Expo Go)、Xcode 16.4+ 与 iOS 15.1+。安装命令:yarn add react-native-unistyles@3 react-native-nitro-modules@0.37.1。Babel 插件须配置 root 选项,且若使用 React Compiler 必须排在其前面;用 Re.Pack 时改用 RepackUnistylePlugin。调用 StyleSheet.configure 必须先于任何 StyleSheet.create 求值。使用 Variants 前须调用 styles.useVariants({})。样式必须用数组语法,禁止展开 styles.x。

适用场景:React Native / Expo 项目中需要从 Unistyles v2 升级到 v3,或排查迁移相关错误。

限制:新架构为强制要求;必须使用 Babel 插件,否则样式不具响应性;初始主题与 adaptiveThemes 互斥;动态函数参数须可序列化;测试 mock 使用首个注册主题并剥离变体,不应断言解析后的样式。更多迁移示例与 API 细节见技能内参考文件。