# Uniwind — 完整参考 > Uniwind 1.5.0+ / Tailwind CSS v4 / React Native 0.81+ / Expo SDK 54+ 如果用户的版本较低，建议更新到1.5.0+以获得最佳体验。 Uniwind 将 Tailwind CSS v4 引入 React Native。所有核心 React Native 组件都支持开箱即用的“className”属性。样式在构建时编译——没有运行时开销。 ## 关键规则 1. **仅限 Tailwind v4** — 使用 `@import 'tailwindcss'` 而不是 `@tailwind base`。不支持 Tailwind v3。 2. **永远不要动态构造 classNames** - Tailwind 在构建时进行扫描。 `bg-${color}-500` 将不起作用。使用完整的字符串文字、映射对象或三元组。 3. **永远不要使用 `cssInterop` 或 `remapProps`** — 这些是 NativeWind API。 Uniwind 不会覆盖全局组件。 4. **没有 `tailwind.config.js`** — 所有配置都通过 `@theme` 和 `@layer theme` 进入 `global.css`。 5. **不需要 ThemeProvider** — 直接使用 `Uniwind.setTheme()`。 6. **`withUniwindConfig` 必须是最外面的** Metro 配置包装器。 7. **永远不要用`withUniwind`包装`react-native`或`react-native-reanimated`组件** - `View`，`Text`，`Pressable`，`Image`，`TextInput`，`ScrollView`，`FlatList`，`Switch`，`Modal`，`Animated.View`，`Animated.Text`等已经内置了完整的`className`支持。用`withUniwind`包装它们将破坏行为。仅将 `withUniwind` 用于**第三方**组件（例如，`expo-image`、`expo-blur`、`moti`）。 8. **字体系列：仅限单一字体** - React Native 不支持后备。使用 `--font-sans: 'Roboto-Regular'` 而不是 `'Roboto', sans-serif`。 9. **所有主题变体必须定义相同的 CSS 变量集** — 如果 `light` 定义了 `--color-primary`，则 `dark` 和每个自定义主题也必须定义。不匹配的变量会导致运行时错误。 10. **非样式颜色道具需要 `accent-` 前缀** — 这至关重要。像“color”（按钮、ActivityIndicator）、“tintColor”（图像）、“thumbColor”（开关）、“placeholderTextColor”（文本输入）这样的道具不是“style”对象的一部分。您必须将相应的“{propName}ClassName”属性与“accent-”前缀类一起使用。示例：`` 不是 ``。常规 Tailwind 颜色类（如“text-blue-500”）仅适用于“className”（映射到“style”）。对于非样式颜色道具，请始终使用“accent-”。 11. **rem 默认为 16px** — NativeWind 使用 14px。如果要迁移，请在 Metro 配置中设置 `polyfills: { rem: 14 }`。 12. **`cssEntryFile` 必须是相对路径字符串** — 使用 `'./global.css'` 而不是 `path.resolve(__dirname, 'global.css')`。 13. **混合自定义 CSS 类和 Tailwind 时使用`cn()` 进行重复数据删除** — Uniwind 不会自动进行重复数据删除。如果自定义 CSS 类 (`.card { padding: 16px }`) 和 Tailwind 实用程序 (`p-6`) 设置相同的属性，则两者都会产生不可预测的结果。当有重叠时，总是用 `cn('card', 'p-6')` 换行。 ## 设置 ### 安装 # 或其他包管理器包子安装uniwind tailwindcss 需要 **Tailwind CSS v4+**。 ### 全局.css 创建 CSS 入口文件： @import 'tailwindcss'; @import 'uniwind'; 导入您的 **App 组件**（例如，`App.tsx` 或 `app/_layout.tsx`），**不在 `index.ts`/`index.js` 中导入 — 在那里导入会破坏热重载： // app/_layout.tsx 或 App.tsx 导入'./global.css'; 包含“global.css”的目录是应用程序根目录 - Tailwind 从该目录开始扫描类名。 ### 地铁配置 const { getDefaultConfig } = require('expo/metro-config'); // 裸 RN: const { getDefaultConfig } = require('@react-native/metro-config'); const { withUniwindConfig } = require('uniwind/metro'); const config = getDefaultConfig(__dirname); // withUniwindConfig 必须是最外面的包装器 module.exports = withUniwindConfig(config, { cssEntryFile: './global.css', // 必需 — 项目根目录的相对路径 polyfills: { rem: 16 }, // 可选 — 基本 rem 值（默认 16） extraThemes: ['ocean', 'sunset'], // 可选 — 超出亮/暗的自定义主题 dtsFile: './uniwind-types.d.ts', // 可选 — TypeScript 类型输出路径 debug: true, // 可选 — 在 dev 中记录不支持的 CSS isTV: false, // 可选 — 启用电视平台支持 }); 对于大多数流程，保留默认值，仅提供 `cssEntryFile`。包装器顺序 - Uniwind 必须包装其他所有内容： // 正确 module.exports = withUniwindConfig(withOtherConfig(config, opts), { cssEntryFile: './global.css' }); // 错误 — Uniwind 不是最外层 module.exports = withOtherConfig(withUniwindConfig(config, { cssEntryFile: './global.css' }), opts); ### Vite配置（v1.2.0+）如果用户有故事书设置，请添加额外的 vite 配置：从 '@tailwindcss/vite' 导入 tailwindcss；从 'uniwind/vite' 导入 { uniwind }; 从“vite”导入{defineConfig}；导出默认的defineConfig({ 插件：[ 尾风CSS(), 单风（{ cssEntryFile: './src/global.css', dtsFile: './src/uniwind-types.d.ts', }), ], }); ### 打字稿 Uniwind 在运行 Metro 后自动生成一个 `.d.ts` 文件（默认：`./uniwind-types.d.ts`）。将其放在 `src/` 或 `app/` 中以自动包含，或添加到 `tsconfig.json` 中： { "include": ["./uniwind-types.d.ts"] } 如果用户有一些与 classNames 相关的打字稿错误，只需运行 Metro 服务器来构建 d.ts 文件。 ### Expo 路由器放置项目/ ├── app/_layout.tsx ← 在此导入 '../global.css' ├── 组件/ ├── global.css ← 项目根目录（最佳位置） └── Metro.config.js ← cssEntryFile: './global.css' 如果 `global.css` 位于 `app/` 目录中，请为同级目录添加 `@source`： @import 'tailwindcss'; @import 'uniwind'; @source '../组件'; ### Tailwind IntelliSense（VS Code / 光标 / Windsurf） { "tailwindCSS.classAttributes": [ “类”，“类名”，“标题类名”， “contentContainerClassName”，“columnWrapperClassName”， “endFillColorClassName”，“imageClassName”，“tintColorClassName”， “ios_backgroundColorClassName”，“thumbColorClassName”， “trackColorOnClassName”，“trackColorOffClassName”， "selectionColorClassName", "cursorColorClassName", "underlineColorAndroidClassName", "placeholderTextColorClassName", "selectionHandleColorClassName", "colorsClassName", "progressBackgroundColorClassName", "titleColorClassName", “underlayColorClassName”，“colorClassName”， "backdropColorClassName", "backgroundColorClassName", “statusBarBackgroundColorClassName”，“drawerBackgroundColorClassName”， “ListFooterComponentClassName”，“ListHeaderComponentClassName” ], "tailwindCSS.classFunctions": ["useResolveClassNames"] } ### Monorepo 支持在 `global.css` 中为 CSS 条目文件目录之外的包添加 `@source` 指令： @import 'tailwindcss'; @import 'uniwind'; @source“../../packages/ui/src”； @source“../../packages/shared/src”；包含 Uniwind 类（例如共享 UI 库）的 `node_modules` 包也需要。 ## 组件绑定所有核心 React Native 组件都支持开箱即用的“className”。有些具有用于子样式的附加 className 属性（例如 `contentContainerClassName`）和非样式颜色属性（需要 `accent-` 前缀）。 ### 完整参考 **图例**：标有 ⚡ 的道具需要 `accent-` 前缀。括号中的 props 是特定于平台的。 #### 查看道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — #### 文字道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `选择颜色类名称` | `选择颜色` | ⚡ `口音-` #### 可按压道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — 支持 `active:`、`disabled:`、`focus:` 状态选择器。 #### 图片道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `tintColorClassName` | `色调颜色` | ⚡ `口音-` #### 文本输入道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `cursorColorClassName` | `光标颜色` | ⚡ `口音-` `选择颜色类名称` | `选择颜色` | ⚡ `口音-` `placeholderTextColorClassName` | `占位符文本颜色` | ⚡ `口音-` `selectionHandleColorClassName` | `选择句柄颜色` | ⚡ `口音-` `underlineColorAndroidClassName` | `underlineColorAndroid` (Android) | `underlineColorAndroid` ⚡ `口音-` 支持 `focus:`、`active:`、`disabled:` 状态选择器。 #### 滚动视图道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `contentContainerClassName` | `contentContainerStyle` | — `endFillColorClassName` | `结束填充颜色` | ⚡ `口音-` #### 平面列表道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `contentContainerClassName` | `contentContainerStyle` | — `columnWrapperClassName` | `columnWrapperStyle` | — `ListHeaderComponentClassName` | `ListHeaderComponentStyle` | — `ListFooterComponentClassName` | `ListFooterComponentStyle` | — `endFillColorClassName` | `结束填充颜色` | ⚡ `口音-` #### 部分列表道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `contentContainerClassName` | `contentContainerStyle` | — `ListHeaderComponentClassName` | `ListHeaderComponentStyle` | — `ListFooterComponentClassName` | `ListFooterComponentStyle` | — `endFillColorClassName` | `结束填充颜色` | ⚡ `口音-` #### 虚拟化列表道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `contentContainerClassName` | `contentContainerStyle` | — `ListHeaderComponentClassName` | `ListHeaderComponentStyle` | — `ListFooterComponentClassName` | `ListFooterComponentStyle` | — `endFillColorClassName` | `结束填充颜色` | ⚡ `口音-` #### 开关道具|地图到 |前缀 ---|---|--- `thumbColorClassName` | `拇指颜色` | ⚡ `口音-` `trackColorOnClassName` | `trackColor.true`（上）| ⚡ `口音-` `trackColorOffClassName` | `trackColor.false`（关闭）| ⚡ `口音-` `ios_backgroundColorClassName` | `ios_backgroundColor` (iOS) | ⚡ `口音-` 注意：Switch 不支持 `className` （类型中的 `className?: never`）。仅使用上面特定于颜色的 className 属性。支持“已禁用：”状态选择器。 #### 活动指示器道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `颜色类名称` | `颜色` | ⚡ `口音-` #### 按钮道具|地图到 |前缀 ---|---|--- `颜色类名称` | `颜色` | ⚡ `口音-` 注意：Button 不支持 `className`（RN Button 上没有 `style` 属性）。 #### 莫代尔道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `backdropColorClassName` | `背景颜色` | ⚡ `口音-` #### 刷新控件道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `colorsClassName` | `颜色` (Android) | ⚡ `口音-` `tintColorClassName` | `tintColor` (iOS) | ⚡ `口音-` `标题颜色类名称` | `标题颜色` (iOS) | ⚡ `口音-` `progressBackgroundColorClassName` | `progressBackgroundColor` (Android) | `progressBackgroundColor` ⚡ `口音-` #### 图像背景道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `imageClassName` | `图像样式` | — `tintColorClassName` | `色调颜色` | ⚡ `口音-` #### 安全区域视图道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — #### 键盘避免视图道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `contentContainerClassName` | `contentContainerStyle` | — #### 输入附件视图道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `backgroundColorClassName` | `背景颜色` | ⚡ `口音-` #### 可触摸突出显示道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — `underlayColorClassName` | `underlayColor` | | `underlayColor` ⚡ `口音-` 支持 `active:`、`disabled:` 状态选择器。 #### 可触摸不透明度道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — 支持 `active:`、`disabled:` 状态选择器。 #### TouchableNativeFeedback 道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — 支持 `active:`、`disabled:` 状态选择器。 #### 可触摸但无反馈道具|地图到 |前缀 ---|---|--- `类名` | `风格` | — 支持 `active:`、`disabled:` 状态选择器。 ### 用法示例从 'react-native' 导入 { View、Text、Pressable、TextInput、ScrollView、FlatList、Switch、Image、ActivityIndicator、Modal、RefreshControl、Button }； // View——基本布局标题 // 可按下——具有按下/焦点状态请按我 // TextInput — 具有焦点状态和强调色属性 <文本输入 className =“边框边框圆角-lg px-4 py-2文本基文本前景焦点：边框主” placeholderTextColorClassName="重音静音" SelectionColorClassName =“重音主色” 光标颜色类名称=“重音主色” SelectionHandleColorClassName =“重音主” underlineColorAndroidClassName="重音透明" 占位符=“输入文字...” /> // ScrollView — 带有内容容器 {/*内容*/} // FlatList — 包含所有子样式 props <平面列表类名=“flex-1” contentContainerClassName="p-4 间隙-3" columnWrapperClassName="gap-3" ListHeaderComponentClassName =“pb-4” ListFooterComponentClassName="pt-4" endFillColorClassName =“口音-灰色-100” 列数={2} 数据={项目} renderItem={({ item }) => } /> // Switch — 不支持 className，仅使用特定于颜色的 props <开关拇指颜色类名称=“口音-白色” trackColorOnClassName =“重音主” trackColorOffClassName="accent-gray-300 dark:accent-gray-700" ios_backgroundColorClassName="accent-gray-200" /> // 图像 — 色调颜色 // 活动指示器 // 按钮 — 仅 colorClassName（无 className）

优风

包含技能