# 将 NativeWind 迁移到 Uniwind Uniwind 取代了 NativeWind，具有更好的性能和稳定性。它需要 **Tailwind CSS 4** 并使用基于 CSS 的主题而不是 JS 配置。 ## 迁移前检查表在开始之前，请阅读项目的现有配置文件以了解当前设置： * `package.json`（NativeWind 版本，依赖项） * `tailwind.config.js` / `tailwind.config.ts` * `metro.config.js` * `babel.config.js` * `global.css` 或等效的 CSS 入口文件 * `nativewind-env.d.ts` 或 `nativewind.d.ts` * 任何使用 `nativewind` 中的 `cssInterop` 或 `remapProps` 的文件 * 从 `react-native-css-interop` 导入的任何文件 * 来自 NativeWind 的任何 ThemeProvider（`vars()` 用法） ## 第 1 步：删除 NativeWind 及相关软件包卸载所有这些软件包（如果存在）： npm 卸载 nativewind react-native-css-interop # 或纱线删除nativewind react-native-css-interop # 或包子删除nativewind react-native-css-interop **关键**：`react-native-css-interop` 是必须删除的 NativeWind 依赖项。在迁移过程中经常会错过它。搜索整个代码库以查找从中导入的任何内容： rg“react-native-css-interop”-g“*。{ts，tsx，js，jsx}” 删除找到的所有导入和使用。 ## 步骤 2：安装 Uniwind 和 Tailwind 4 npm 安装 uniwind tailwindcss@latest # 或纱线添加 uniwind tailwindcss@latest # 或包子添加uniwind tailwindcss@latest 确保 `tailwindcss` 版本为 4+。 ## 第三步：更新 babel.config.js 删除 NativeWind babel 预设： // 从预设数组中删除这一行： // 'nativewind/babel' 不需要 Uniwind babel 预设。 ## 步骤4：更新metro.config.js 将 NativeWind 的 Metro 配置替换为 Uniwind 的配置。 `withUniwindConfig` 必须是 **最外层包装**。 **之前（NativeWind）：** const { withNativeWind } = require('nativewind/metro'); module.exports = withNativeWind(config, { input: './global.css' }); **之后（Uniwind）：** const { getDefaultConfig } = require('expo/metro-config'); // 对于裸 RN： const { getDefaultConfig } = require('@react-native/metro-config'); const { withUniwindConfig } = require('uniwind/metro'); const config = getDefaultConfig(__dirname); module.exports = withUniwindConfig(config, { cssEntryFile: './global.css', 填充: { rem: 14 }, }); `cssEntryFile` 必须是项目根目录的**相对路径字符串**（例如 `./global.css` 或 `./app/global.css`）。 **不要**为此选项使用绝对路径或 `path.resolve(...)` / `path.join(...)`。 // ❌ 破损 cssEntryFile: path.resolve(__dirname, 'app', 'global.css') // ✅ 正确 cssEntryFile: './app/global.css' **始终将`polyfills.rem` 设置为 14** 以匹配 NativeWind 的默认 rem 值并防止迁移后的间距/大小差异。如果项目使用“light”/“dark”之外的自定义主题（例如通过 NativeWind 的“vars()”或自定义 ThemeProvider 定义），请将它们注册到“extraThemes”。不要包含“light”或“dark”——它们是自动添加的： module.exports = withUniwindConfig(config, { cssEntryFile: './global.css', 填充: { rem: 14 }, extraThemes: ['海洋', '日落', '高级'], }); 选项： * `cssEntryFile`（必需）：CSS 条目文件的相对路径字符串（来自项目根目录） * `polyfills.rem` （迁移所需）：设置为 `14` 以匹配 NativeWind 的 rem 基础 * `extraThemes` （如果项目有自定义主题则需要）：自定义主题名称数组 - 不包括 `light`/`dark` * `dtsFile` （可选）：生成的 TypeScript 类型的路径，默认为 `./uniwind-types.d.ts` * `debug`（可选）：在开发期间记录不支持的 CSS 属性 ## 步骤 5：更新 global.css 将 NativeWind 的 Tailwind 3 指令替换为 Tailwind 4 导入： **之前：** @tailwind基地； @tailwind组件； @tailwind实用程序； **之后：** @import 'tailwindcss'; @import 'uniwind'; ## 步骤 6：更新 CSS 条目导入确保“global.css”导入到您的主应用程序组件（例如“App.tsx”）中，而不是导入到注册应用程序的根“index.ts”/“index.js”中 - 在那里导入会破坏热重载。 ## 步骤 7：删除 NativeWind 类型定义删除 `nativewind-env.d.ts` 或 `nativewind.d.ts`。 Uniwind 在“dtsFile”指定的路径自动生成自己的类型。 ## 步骤8：删除tailwind.config.js 完全删除 `tailwind.config.js` / `tailwind.config.ts`。所有主题配置都使用 Tailwind 4 的“@theme”指令转移到 CSS。将自定义主题值迁移到“global.css”： **之前（tailwind.config.js）：** 模块. 导出 = { 主题：{ 扩展：{ 颜色：{ 主要：'#00a8ff'，次要：'#273c75'， }, 字体系列：{ 正常：['Roboto-Regular']，粗体：['Roboto-Bold']， }, }, }, }; **（global.css）之后：** @import 'tailwindcss'; @import 'uniwind'; @主题{ --颜色主色：#00a8ff； --颜色次要：#273c75； --font-normal: 'Roboto-Regular'; --font-bold: '机器人粗体'; } 字体系列必须指定**单一字体** - React Native 不支持字体后备。 ## 步骤 9：删除所有 cssInterop 和 remapProps 用法 **这是最常被忽略的步骤。** 搜索整个代码库： rg "cssInterop|remapProps" -g "*.{ts,tsx,js,jsx}" 将每个 `cssInterop()` / `remapProps()` 调用替换为 Uniwind 的 `withUniwind()`： **之前（NativeWind）：** 从'react-native-css-interop'导入{cssInterop}；从'expo-image'导入{图像}； cssInterop(Image, { className: 'style' }); **之后（Uniwind）：** 从 'uniwind' 导入 { withUniwind }; 从“expo-image”导入{图像作为ExpoImage}；导出 const Image = withUniwind(ExpoImage); `withUniwind` 自动映射 `className` → `style` 和其他常见的 props。对于自定义道具映射： const StyledProgressBar = withUniwind(ProgressBar, { 宽度：{ fromClassName: '宽度ClassName', style属性: '宽度', }, }); 在**模块级别**定义包装组件（不在渲染函数内）。每个组件只能包装一次： * **仅在一个文件中使用** — 在同一文件中定义包装组件： // 屏幕/ProfileScreen.tsx 从 'uniwind' 导入 { withUniwind }; 从 '@react-native-community/blur' 导入 { BlurView as RNBlurView } ； const BlurView = withUniwind(RNBlurView); 导出函数 ProfileScreen() { 返回 ; } * **跨多个文件使用** - 在共享模块中包装一次并重新导出： // 组件/styled.ts 从 'uniwind' 导入 { withUniwind }; 从“expo-image”导入{图像作为ExpoImage}；从“expo-线性梯度”导入{LinearGradient as RNLinearGradient}；导出 const Image = withUniwind(ExpoImage); 导出 const LinearGradient = withUniwind(RNLinearGradient); 然后从各处的共享模块导入：从 '@/components/styled' 导入 { Image, LinearGradient }; 切勿在多个文件中的同一组件上调用“withUniwind”——包装一次，到处导入。 **重要**：不要用 `withUniwind` 包装来自 `react-native` 或 `react-native-reanimated` 的组件 - 它们已经支持开箱即用的 `className`。这包括“View”、“Text”、“Image”、“ScrollView”、“FlatList”、“Pressable”、“TextInput”、“Animated.View”等。仅将“withUniwind”用于**第三方**组件（例如“expo-image”、“expo-linear-gradient”、“@react-native-community/blur”）。 **重要 — 非样式颜色属性的重音前缀**：React Native 组件具有诸如“color”、“tintColor”、“backgroundColor”之类的属性，这些属性不属于“style”对象。要通过 Tailwind 类设置这些，请使用 `accent-` 前缀和相应的 `*ClassName` 属性： // color prop → colorClassName 带有accent-前缀 <活动指示器类名=“m-4” 尺寸=“大” colorClassName="accent-blue-500 暗:accent-blue-400" /> // Button 上的颜色属性 <按钮 colorClassName="强调背景" 标题=“按我” /> //tintColor 属性→tintColorClassName 带有accent-前缀 <图片类名=“w-6 h-6” TintColorClassName =“口音-红色-500” 来源={图标} /> 规则：“className”接受任何基于样式的 props 的 Tailwind 实用程序。对于非样式属性（颜色、tintColor 等），请使用带有“accent-”前缀的“{propName}ClassName”。这适用于所有内置的 React Native 组件。 ## 步骤 10：迁移 NativeWind 主题变量 **之前（带有 `vars()` 的 NativeWind JS 主题）：** 从'nativewind'导入{vars}；导出常量主题= { 光：变量（{ '--颜色主色': '#00a8ff', '--颜色排版': '#000', }), 黑暗：变量（{ '--颜色主色': '#273c75', '--颜色排版': '#fff', }), }; // 在 JSX 中： <视图样式={主题[colorScheme]}> **之后（Uniwind CSS 主题）：** @层主题{ ：根{ @变体光{ --颜色主色：#00a8ff； --颜色排版：#000； } @变体黑暗{ --颜色主色：#273c75； --颜色排版：#fff； } } } **重要**：所有主题变体必须定义完全相同的 CSS 变量集。如果“light”定义了“--color-primary”和“--color-typography”，那么“dark”（以及任何自定义主题）也必须定义两者。不匹配的变量将导致 Uniwind 运行时错误。不需要 ThemeProvider 包装器。从 JSX 中删除 NativeWind `` 或 `vars()` 包装器。保留 React Navigation 的 ``（如果使用）。如果项目使用嵌套主题包装器来预览或强制特定子树的主题（例如演示卡、设置预览或并排主题比较），请使用 Uniwind Pro 的“ScopedTheme”而不是更改全局主题：从 'uniwind' 导入 { ScopedTheme }; <预览卡/> 如果项目具有**超出亮/暗**的自定义主题（例如“海洋”、“高级”），您必须： 1. 使用 `@variant` 在 CSS 中定义它们： @层主题{ ：根{ @variant海洋{ --颜色主色：#0ea5e9； --颜色背景：#0c4a6e； } } } 2.通过`extraThemes`在metro.config.js中注册它们（跳过`light`/`dark` - 它们是自动添加的）： module.exports = withUniwindConfig(config, { cssEntryFile: './global.css', 填充: { rem: 14 }, extraThemes: ['海洋', '高级'], }); ## 步骤 11：迁移安全区域实用程序 NativeWind 的安全区域类需要在 Uniwind 中显式设置：从“react-native-safe-area-context”导入{ SafeAreaProvider，SafeAreaListener }；从 'uniwind' 导入 { Uniwind }；导出默认函数 App() { 返回（ <安全区域提供者> <安全区域监听器 onChange={({ 插入}) => { Uniwind.updateInsets(insets); }} > {/*内容*/} ）； } ## 步骤 12：验证 rem 值 NativeWind使用14px作为基准rem，Uniwind默认为16px。步骤 4 已在 Metro 配置中设置了 `polyfills: { rem: 14 }` 以保留 NativeWind 的间距。如果用户明确想要 Uniwind 的默认值 (16px)，他们可以删除填充 - 但警告他们所有间距/大小都会发生变化。 ## 步骤 13：处理 className 重复数据删除 Uniwind 不会自动删除重复的冲突类名（NativeWind 会这样做）。如果您的代码库依赖于诸如“className={`p-4 ${overrideClass}`}”之类的覆盖模式，请设置“cn”实用程序。首先，检查项目是否已经有一个 `cn` 帮助器（常见于 shadcn/ui 项目）： rg "导出函数 cn|导出 const cn" -g "*.{ts,tsx,js}" 如果存在，请保持原样。如果没有，请安装依赖项并创建它： npm 安装 tailwind-merge clsx 创建 `lib/cn.ts` （或项目中 utils 所在的任何位置）：从 'clsx' 导入 { type ClassValue, clsx }; 从 'tailwind-merge' 导入 { twMerge }；导出函数 cn(...输入: ClassValue[]) { 返回 twMerge(clsx(输入)); } 用途：从 '@/lib/cn' 导入 { cn }；使用“cn”而不是原始的“twMerge”——它在使用“tailwind-merge”进行重复数据删除之前通过“clsx”处理条件类、数组和虚假值。 ## 步骤 14：更新动画类名称如果项目使用 NativeWind `animated-*` / 转换类模式，请将它们迁移到显式的 `react-native-reanimated` 用法。 Uniwind OSS 不提供 NativeWind 风格的动画类行为。使用此迁移指南部分作为事实来源： * ## 步骤 15：清理剩余的 NativeWind 引用最终扫描 - 搜索并删除任何剩余的引用： rg "nativewind|NativeWind|native-wind" -g "*.{ts,tsx,js,jsx,json,css}" 检查： * NativeWind 在任何文件中导入 * `package.json` 中的 `nativewind` （还有 devDependency） * `package.json` 中的 `react-native-css-interop` * NativeWind babel 预设在 `babel.config.js` 中 * `metro.config.js` 中的 NativeWind Metro 包装器 * `nativewind-env.d.ts` 或 `nativewind.d.ts` 文件 * 任何 `cssInterop()` 或 `remapProps()` 调用 * 任何从 `nativewind` 导入的 `vars()` ## Uniwind API 和模式 ### useUniwind — 主题访问（更改时重新渲染）文档：从 'uniwind' 导入 { useUniwind }; const { 主题, hasAdaptiveThemes } = useUniwind(); // theme: 当前主题名称 - “light”、“dark”、“system”或自定义 // hasAdaptiveThemes：如果应用程序遵循系统配色方案，则为 true 用于：在 UI 中显示主题名称、按主题进行条件渲染、主题更改的副作用。 ### Uniwind Static API — 主题访问（无需重新渲染）访问主题信息而不导致重新渲染：从 'uniwind' 导入 { Uniwind }； Uniwind.currentTheme // “浅色”、“深色”、“系统”或自定义 Uniwind.hasAdaptiveThemes // 如果遵循系统配色方案则为 true 用于：日志记录、分析、渲染之外的命令式逻辑。 ### useResolveClassNames — 将类名转换为样式对象文档：将 Tailwind 类转换为 React Native 样式对象。当使用不支持 `className` 且无法用 `withUniwind` 包装的组件时使用（例如，react-navigation 主题配置）：从 'uniwind' 导入 { useResolveClassNames }； const headerStyle = useResolveClassNames('bg-blue-500'); const cardStyle = useResolveClassNames('bg-white dark:bg-gray-900'); <堆栈导航器屏幕选项={{ headerStyle: headerStyle, 卡样式：卡样式， }} /> ### useCSSVariable — 在 JS 中访问 CSS 变量文档：以编程方式检索 CSS 变量值。变量必须以“--”为前缀，并与“global.css”中定义的变量匹配：从 'uniwind' 导入 { useCSSVariable }; const PrimaryColor = useCSSVariable('--color-primary'); const 间距 = useCSSVariable('--spacing-4'); 用于：动画、第三方库配置、使用设计令牌的计算。 ### CSS 函数 — 自定义实用程序文档：使用设备感知 CSS 函数定义自定义实用程序，例如“hairlineWidth()”、“fontScale()”、“pixelRatio()”。这些可以在任何地方使用（自定义 CSS 类、`@utility` 等），但不能在 `@theme {}` 内使用（它只接受静态值）。使用 `@utility` 创建可重用的 Tailwind 风格的类： @utility w-hairline { 宽度：hairlineWidth(); } @utility h-hairline { 高度：hairlineWidth(); } @utility border-hairline { 边框宽度：hairlineWidth(); } @utility text-scaled { 字体大小：fontScale(); } 然后使用：`` ### 平台选择器文档：使用 `ios:`、`android:`、`web:`、`native:` 前缀有条件地应用样式：特定于平台的样式 ### 主题切换文档：默认情况下，Uniwind 遵循系统配色方案（自适应主题）。以编程方式切换主题：从 'uniwind' 导入 { Uniwind }； Uniwind.setTheme('黑暗'); // 强制黑暗 Uniwind.setTheme('光'); // 强制点亮 Uniwind.setTheme('系统'); // 跟随系统（默认） Uniwind.setTheme('海洋'); // 自定义主题（必须位于 extraThemes 中） ### ScopedTheme — 仅主题子树文档：当项目仅需要部分 UI（组件预览、主题部分、嵌套演示）使用不同的主题而不更改应用程序范围的主题时，请使用“ScopedTheme”：从 'uniwind' 导入 { ScopedTheme }; <查看类名=“gap-3”> <预览卡/> <预览卡/> <预览卡/> 重要行为： * 最近的 `ScopedTheme` 获胜（支持嵌套范围） * 像 `useUniwind`、`useResolveClassNames` 和 `useCSSVariable` 这样的钩子根据最近的范围主题进行解析 * 范围内的“withUniwind”包装的第三方组件也解析该范围内的主题值 * 自定义主题名称可以在`ScopedTheme`中使用（必须在`extraThemes`中定义） ### 基于主题的样式 - 首选 CSS 变量文档： **更喜欢使用基于 CSS 变量的类，而不是显式的 dark:/light: 变体。** 而不是： // 避免这种模式定义一个CSS变量并直接使用它： @层主题{ ：根{ @variant light { --color-background: #ffffff; } @variant dark { --color-background: #000000; } } } // Preferred — 自动适应主题这更干净，更容易维护，并且也可以自动与自定义主题一起使用。 ### 运行时 CSS 变量更新文档：在运行时更新主题变量，例如基于用户偏好或 API 响应：从 'uniwind' 导入 { Uniwind }； // 根据用户输入或 API 响应预配置主题 Uniwind.updateCSSVariables('光', { '--颜色主色': '#ff6600', '--颜色背景': '#1a1a2e', }); 仅当应用程序具有真正的运行时主题需求（例如，用户选择的品牌颜色或 API 驱动的主题）时，才应使用此模式。 ### 具有顺风变体的变体文档：对于组件变体和复合变体，请使用 `tailwind-variants` 库：从 'tailwind-variants' 导入 { tv } ；常量按钮 = 电视({ 基数：'px-4 py-2 rounded-lg'，变体：{ 颜色：{ 主要：'bg-主要文本-白色'， secondary: '背景-辅助文本-白色', }, 尺寸：{ sm: '文本-sm', lg: '文本-lg px-6 py-3', }, }, }); ### Monorepo 支持文档：如果项目是 monorepo，请在 `global.css` 中添加 `@source` 指令，以便 Tailwind 扫描 CSS 条目文件目录之外的包（仅当该目录包含具有 Tailwind 类的组件时）： @import 'tailwindcss'; @import 'uniwind'; @source“../../packages/ui/src”； @source“../../packages/shared/src”； ### 常见问题解答文档： **自定义字体**：Uniwind 仅将 className 映射到 font-family - 字体文件必须单独加载（`app.json` 中的 expo-font 插件或裸 RN 的 `react-native-asset`）。 `@theme` 中的字体系列名称必须与文件名完全匹配（不带扩展名）。对每个平台的字体使用“@variant”（必须位于“@layer theme { :root { } }”内）： @层主题{ ：根{ @variant ios { --font-sans: 'SF Pro Text'; } @variant android { --font-sans: 'Roboto-Regular'; } @variant web { --font-sans: 'system-ui'; } } } **数据选择器** ：使用 `data-[prop=value]:utility` 进行基于 prop 的样式。仅支持相等检查： <查看数据状态={isOpen ? '开放' : '封闭'} className="data-[state=open]:bg-muted/50" /> **global.css 在 Expo Router 中的位置**：放置在项目根目录并导入根布局 (`app/_layout.tsx`)。如果放置在 `app/` 中，外部组件需要 `@source` 指令。 Tailwind 从“global.css”位置扫描。 **CSS 更改时完整应用程序重新加载**：Metro 无法通过许多提供商热重新加载文件。将“global.css”导入移至组件树的更深处（例如导航根或主屏幕）以进行修复。 **渐变**：内置支持，无需额外的依赖。使用“bg-gradient-to-r from-red-500 via-yellow-500 to-green-500”。对于“expo-linear-gradient”，使用“useCSSVariable”来获取颜色——“withUniwind”不起作用，因为渐变道具是数组。 **样式特异性**：内联`style`总是覆盖`className`。对静态样式使用“className”，仅对真正的动态值使用内联。避免将两者混合以获得相同的属性。 **序列化错误**（`无法序列化 javascript 对象`）：清除缓存：`watchman watch-del-all 2>/dev/null; rm -rf node_modules/.cache && npx expo start --clear`。常见原因：复杂的“@theme”配置、循环 CSS 变量引用。 **Metro不稳定_enablePackageExports冲突**：某些应用程序（加密等）禁用此功能，从而破坏了Uniwind。使用选择性解析器： config.resolver.unstable_enablePackageExports = false; config.resolver.resolveRequest = (上下文, 模块名称, 平台) => { if (['uniwind', 'culori'].some((prefix) => moduleName.startsWith(prefix))) { return context.resolveRequest({ ...context, stable_enablePackageExports: true }, moduleName, platform); } return context.resolveRequest(context, moduleName, platform); }; **安全区域类**：`p-safe`、`pt-safe`、`pb-safe`、`px-safe`、`py-safe`、`m-safe`、`mt-safe`等。还支持`-or-{value}`（最小间距）和`-offset-{value}`（额外间距）变体。 **Next.js** ：不受官方支持。 Uniwind 适用于 Metro 和 Vite。社区插件：`uniwind-plugin-next`。对于 Next.js，使用标准 Tailwind CSS 并共享设计令牌。 **Vite** ：从 v1.2.0 开始支持。将 `uniwind/vite` 插件与 `@tailwindcss/vite` 一起使用。 **UI 套件**：HeroUI Native、react-native-reusables 和 Gluestack 4.1+ 与 Uniwind 配合得很好 ## 已知问题和陷阱 1. __data-_attributes_*：Uniwind 支持条件样式的 `data-[prop=value]:utility` 语法，类似于 NativeWind。 2. **动画样式** ：将 NativeWind 动画类直接迁移到“react-native-reanimated”。 Uniwind Pro 具有内置的 Reanimated 支持。 ## 验证迁移后，验证： 1. `npx react-native start --reset-cache` （清除 Metro 缓存）或使用 expo `npx expo start -c` 2. 所有屏幕在 iOS 和 Android 上都能正确渲染 3.主题切换工作（亮/暗） 4.自定义字体正确加载 5. 正确应用安全区域插图 6. 控制台没有关于缺少样式的警告 7. 没有来自 `nativewind` 或 `react-native-css-interop` 的剩余导入 **重要**：不要猜测 Uniwind API。如果您不确定任何 Uniwind API、挂钩、组件或配置选项，请获取并对照官方文档进行验证：

将 Nativewind 迁移到 Uniwind

包含技能