uniwind

Uniwind 最佳实践

全面的 Uniwind 性能优化与最佳实践指南。Uniwind 是适用于 React Native 的最快 Tailwind CSS 绑定。本指南包含 8 个类别中的 45+ 条规则，并按影响程度排序，以指导自动重构和代码生成。

适用场景

在以下情况下参考这些指南：

• 在新的 React Native 项目中设置 Uniwind
• 配置 Metro 插件和 CSS 入口点
• 使用 CSS 变量构建主题系统
• 集成支持 className 的第三方组件
• 为手机和平板电脑创建响应式布局
• 优化样式性能
• 从 NativeWind 迁移到 Uniwind

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	构建时配置	严重	build-
2	主题架构	严重	theme-
3	组件集成	高	comp-
4	响应式设计	高	resp-
5	性能优化	中高	perf-
6	平台模式	中	plat-
7	状态与交互	中	state-
8	迁移与兼容性	中低	compat-

快速参考

1. 构建时配置（严重）

• build-metro-config - 使用必需选项配置 Metro 插件
• build-css-entry - 将 CSS 入口文件放在应用根目录中
• build-typescript-types - 配置 TypeScript 定义文件的位置
• build-restart-metro - 配置变更后重启 Metro
• build-debug-mode - 在开发期间启用调试模式
• build-rem-polyfill - 配置 rem 基准值，确保设计系统一致性

2. 主题架构（严重）

• theme-css-variables - 使用 @theme 指令定义主题变量
• theme-variant-blocks - 使用 @variant 块定义主题
• theme-consistent-variables - 在所有主题中定义相同的变量
• theme-custom-registration - 在 Metro 配置中注册自定义主题
• theme-oklch-colors - 使用 OKLCH 颜色空间实现感知均匀性
• theme-light-dark-function - 使用 light-dark() 函数实现自适应颜色
• theme-no-provider - 从应用中移除 ThemeProvider 包装器

3. 组件集成（高）

• comp-with-uniwind - 使用 withUniwind 处理第三方组件
• comp-module-level - 在模块级别定义包装后的组件
• comp-prop-mapping - 为非样式属性使用自定义属性映射
• comp-accent-colors - 使用 accent-* 类提取颜色属性
• comp-reanimated - Reanimated 组件无需 withUniwind 即可使用
• comp-custom-css - 使用自定义 CSS 类编写复杂且可复用的样式

4. 响应式设计（高）

• resp-mobile-first - 采用移动优先设计并逐步增强
• resp-limit-breakpoints - 将断点限制为 3-5 个，以便于维护
• resp-visibility-toggle - 使用 hidden/flex 控制响应式可见性
• resp-custom-breakpoints - 使用语义化名称定义自定义断点
• resp-responsive-spacing - 根据屏幕尺寸调整间距和排版

5. 性能优化（中高）

• perf-static-classnames - 使用完整的静态类名进行构建时解析
• perf-use-resolve-sparingly - 谨慎使用 useResolveClassNames
• perf-memoize-variants - 对变体样式对象进行记忆化
• perf-tailwind-merge - 使用 tailwind-merge 去重类名
• perf-avoid-inline-styles - 优先使用 className，而非内联 style 属性
• perf-combine-styles - 正确组合 className 和 style 属性

6. 平台模式（中）

• plat-ios-android-selectors - 使用平台选择器处理 iOS/Android 差异
• plat-safe-area-context - 使用 react-native-safe-area-context 处理安全区域
• plat-yoga-layout - 了解 Yoga 布局引擎的差异
• plat-web-selector - 在跨平台应用中使用 web: 选择器
• plat-font-families - 配置字体系列且不使用回退字体

7. 状态与交互（中）

• state-pressable-states - 使用 Pressable 及 active:/focus:/disabled: 状态
• state-data-selectors - 使用数据选择器设置组件状态样式
• state-no-hover - 在原生平台上避免使用 hover:，改用 active:
• state-group-variants - 使用组变体设置父子样式（WIP）
• state-dark-mode - 使用 dark: 变体设置深色模式样式

8. 迁移与兼容性（低至中）

• compat-nativewind-migration - 遵循 NativeWind 迁移检查清单
• compat-tailwind-4-syntax - 使用 Tailwind 4 的 CSS 优先配置
• compat-rem-default - 考虑 rem 默认值的差异
• compat-cssinterop-replacement - 将 cssInterop 替换为 withUniwind
• compat-safe-area-changes - 将 *-safe 类替换为 Safe Area Context

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	说明
AGENTS.md	包含所有规则的完整汇编指南
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息