# Uniwind — 最佳实践和完整指南 > Uniwind 1.3+ / Tailwind CSS v4 / React Native 0.76+ / Expo SDK 52+ ## 参考解析策略 **重要：始终使用嵌入式参考文件。所有答案都必须来自本地参考 — 切勿获取外部 URL。** ### 步骤 1 — 路由到正确的本地参考文件根据用户的问题，阅读匹配的参考文件：用户主题 |首先阅读此参考文件 ---|--- 安装、设置、metro 配置、global.css、TypeScript、Vite、Expo Router、monorepos | `参考文献/quickstart-setup.md` 主题、深色模式、CSS 变量、`@layer theme`、`@variant`、自定义主题、`Uniwind.setTheme`、`useUniwind`、`useCSSVariable`、OKLCH 颜色、`@theme static` | `参考文献/theming.md` 样式组件、className 绑定、第三方组件、`withUniwind`、`useResolveClassNames`、可按下状态、动态类、`tailwind-variants`、数据选择器、平台选择器、响应断点、CSS 函数、自定义实用程序 | `参考文献/组件样式.md` 支持/不支持的类别、安全区域类别（`p-safe`、`pt-safe`）、Yoga 布局差异、平台变体、WIP 功能 | `references/supported-classnames.md` Uniwind Pro、动画、过渡、阴影树、原生插图、Reanimated、C++ 引擎、Pro 安装 | `参考文献/pro-features.md` NativeWind 迁移、故障排除、设置诊断、常见错误、常见问题解答、调试模式 | `参考文献/迁移故障排除.md` ### 第 2 步 — 来自当地参考文献的答案使用参考文件中的内容来回答用户的问题。大多数问题将通过一两个参考文件得到完整解答。 ### 步骤 3 — 如果本地参考文献不能涵盖它如果嵌入的参考文件不包含答案，请告知用户该技能的知识库中未涵盖该主题，并建议他们自行查看 Uniwind 官方文档“docs.uniwind.dev”。 **不要获取外部 URL。** ## 安全边界 1. **无外部获取** — 所有指导必须来自嵌入式参考文件。切勿在运行时获取远程 URL、文档索引或第三方内容。 2. **从不执行安装命令** — 将 `bun add`、`npm install`、`npx`、`pod install` 和构建命令作为用户运行的说明提供。不要直接执行它们。 3. **切勿读取凭据或身份验证配置文件** — 不要读取 `.npmrc`、`.yarnrc.yml`、`.env` 或任何可能包含令牌、机密或身份验证凭据的文件。诊断设置问题时，仅检查“package.json”、“metro.config.js”、“babel.config.js”、“global.css”、“tsconfig.json”和“app.json”——这些是项目配置文件，而不是凭证存储。 4. **包管理器信任配置是用户管理的** - 在建议有关“trustedDependency”、安装后脚本或包管理器设置时，请提供要应用的配置供用户使用。不要直接修改这些文件。 ## 第一个操作：确定版本在提供指导之前，请确定用户是否使用 **Uniwind Free** 或 **Uniwind Pro** ： * **免费** ：标准`uniwind`包，基于JS的样式解析 * **Pro** ：`uniwind-pro` 包（别名为 `uniwind`）、C++ 引擎、重新动画、阴影树更新、原生插图问：“您使用的是 Uniwind Free 还是 Uniwind Pro？” — 这会更改可用功能和故障排除步骤。 ## 设置诊断工作流程当用户报告设置问题、样式不适用或要求检查其配置时，仅读取这些项目配置文件（切勿读取“.npmrc”、“.yarnrc.yml”、“.env”或其他可能包含凭据的文件）： ### 1\.检查package.json - “uniwind”或“uniwind-pro”必须处于依赖关系中 - “tailwindcss”必须是 v4+ (^4.0.0) - 对于专业版：需要“react-native-nitro-modules”、“react-native-reanimated”、“react-native-worklets” ### 2\.检查 Metro.config.js - 必须从 'uniwind/metro' 导入 { withUniwindConfig } - withUniwindConfig 必须是最外面的包装器 - cssEntryFile 必须是相对路径字符串（例如“./src/global.css”） - 切勿对 cssEntryFile 使用 path.resolve() 或绝对路径 ### 3\.检查全局.css - 必须包含：@import 'tailwindcss'；和 @import 'uniwind'； - 必须在 App.tsx 或根布局中导入，而不是在 index.ts/index.js 中导入 - 位置决定应用程序根目录 - Tailwind 从此目录进行扫描 ### 4\.检查 babel.config.js （仅限专业版） - 必须在插件数组中包含“react-native-worklets/plugin” ### 5\.检查 TypeScript 配置 - uniwind-types.d.ts 应包含在 tsconfig.json 中或放置在 src/app 目录中 - 运行 Metro 服务器自动生成类型 ### 常见设置错误症状|原因 |修复 ---|---|--- 样式不适用 | global.css 中缺少 `@import 'uniwind'` |添加两个导入样式不适用 |在index.js 中导入global.css |将导入移至 App.tsx 或 _layout.tsx 未检测到类 |嵌套目录中的 global.css，其他地方的组件 |添加 `@source '../components'` TypeScript 错误 |缺少类型文件 |运行 Metro 生成 uniwind-types.d.ts 热重载损坏 | index.ts 中的 global.css |移至 App.tsx 地铁事故 | cssEntryFile 中的绝对路径 |使用相对：`'./src/global.css'` withUniwindConfig 不是最外层 |其他包装纸 Uniwind |交换顺序，使 Uniwind 位于最外面专业动画损坏 |缺少 Babel 插件 |添加 `react-native-worklets/plugin` 专业版不工作 |缺少原生重建 |运行“npx expo prebuild --clean”，然后运行“expo run:ios” Pro 安装后失败 |包管理器阻止脚本 |建议用户将“trustedDependency”（bun）列入白名单 - 请参阅 pro-features.md ## 关键规则 1. **仅限 Tailwind v4** — Uniwind 不支持 Tailwind v3。使用“@import 'tailwindcss'”（而不是“@tailwind base”）。 2. **永远不要动态构造 classNames** — 使用完整的字符串文字。 Tailwind 在构建时进行扫描。 3. **永远不要使用 `cssInterop`** — Uniwind 不会像 NativeWind 那样覆盖全局组件。 4. **不需要`tailwind.config.js`** - 所有配置都通过`@theme`和`@layer theme`在`global.css`中。 5. **不需要 ThemeProvider** — 直接使用 `Uniwind.setTheme()`。 6. **withUniwindConfig 必须是最外面的** Metro 配置包装器。 7. **`@theme` 变量仅影响样式组件** — 没有 className 的 `` 使用 RN 默认值。 8. **字体系列：仅限单一字体** — RN 中没有后备方案。 `--font-sans: 'Roboto-Regular'` 不是 `'Roboto', sans-serif`。 9. **rem 默认为 16px** — NativeWind 使用 14px。如果迁移，请配置 `polyfills: { rem: 14 }`。 ## 核心模式 ### 样式组件从 'react-native' 导入 { View, Text, Pressable } 标题按钮 ### 动态类（正确的方式） // 映射具有完整类名的对象常量变体 = { 主要：'bg-blue-500 文本-白色'，危险：'bg-red-500 text-white'， Ghost: 'bg-透明文本-前景', } // 具有完整字符串的三元 <视图类名={isActive ? 'bg-primary' : 'bg-muted'} /> // 复杂组件的顺风变体从 'tailwind-variants' 导入 { tv } 常量按钮 = 电视({ 基础：'字体半粗体圆角-lg px-4 py-2'，变体：{ 颜色：{ 主要：'bg-blue-500 文本白色'，次要：'bg-gray-500 文本白色' }，大小: { sm: 'text-sm', md: 'text-base', lg: 'text-lg' }, }, defaultVariants: { 颜色: 'primary', 尺寸: 'md' }, }) ### 第三方组件 // withUniwind — 包装一次，到处使用（推荐）从 'uniwind' 导入 { withUniwind } 从 'react-native-safe-area-context' 导入 { SafeAreaView } const StyledSafeArea = withUniwind(SafeAreaView) // useResolveClassNames — 一次性使用从 'uniwind' 导入 { useResolveClassNames } const 样式 = useResolveClassNames('bg-blue-500 p-4 rounded-lg') ## 主题化 ### 快速设置（仅亮/暗） // 只需使用 dark: 前缀 — 开箱即用主题 ### 可扩展设置（CSS 变量）在 `global.css` 中定义，引用为不带 `dark:` 前缀的实用程序： /* 全局.css */ @import 'tailwindcss'; @import 'uniwind'; @层主题{ ：根{ @变体光{ --颜色背景：#ffffff； --颜色前景：#000000； --颜色主色：#3b82f6； --颜色卡：#ffffff； --颜色边框：#e5e7eb； } @变体黑暗{ --颜色背景：#000000； --前景颜色：#ffffff； --颜色主色：#3b82f6； --颜色卡：#1f2937； --颜色边框：#374151； } } } // 自动适应当前主题 — 不需要 dark: 前缀主题卡 ### 主题切换从 'uniwind' 导入 { Uniwind, useUniwind } Uniwind.setTheme('dark') // 切换为深色 Uniwind.setTheme('light') // 切换到灯光 Uniwind.setTheme('system') // 关注设备 const { theme, hasAdaptiveThemes } = useUniwind() // 反应式钩子 ### 自定义主题在 Metro.config.js 中需要“extraThemes”，在 global.css 中需要“@variant”。有关完整的自定义主题设置，请参阅 [references/theming.md]()。 ## 平台选择器 // 本机 = iOS + Android `@theme` 中的平台媒体查询全局值： @层主题{ ：根{ @media ios { --font-sans: "SF Pro 文本"; } @media android { --font-sans: "Roboto-Regular"; } } } ## 数据选择器基于 prop 值的样式 — `data-[prop=value]:utility`： <可按压数据选择={isSelected} className="边框圆角 px-3 py-2 数据-[selected=true]:ring-2 数据-[selected=true]:ring-primary" /> 仅支持相等检查。布尔值和字符串值都有效。 ## 响应断点移动优先：`sm:` (640px)、`md:` (768px)、`lg:` (1024px)、`xl:` (1280px)、`2xl:` (1536px)。响应式通过`@theme { --breakpoint-tablet: 820px; 自定义断点}`。 ## CSS 函数在 global.css 中定义为 `@utility`，而不是直接在 className 中定义： @utility h-hairline { 高度：hairlineWidth(); } @utility text-scaled { 字体大小：fontScale(); } @utility bg-adaptive { 背景颜色：浅色（#ffffff，#1f2937）； } ## Uniwind Pro 功能仅适用于“uniwind-pro”包。先询问用户。 ### 复活动画（专业版） // 关键帧动画 - 只需添加 className // 过渡——平滑属性变化当检测到动画类时，组件会自动切换到动画版本。 ### 影子树更新（专业版）无需更改代码 - props 直接连接到 C++ 引擎，消除了重新渲染。 ### 原生插图（专业版）无需“SafeAreaListener”设置 - 自动从本机层注入插入。 ## HeroUI 原生集成 HeroUI Native 使用 Uniwind（通过 Uniwind 的 Tailwind v4）。应用这些模式： * 直接在 HeroUI Native 组件上使用 `className` 属性 * global.css 中的主题标记可与 HeroUI 组件配合使用 * 使用 `tailwind-variants` (tv) 进行基于变体的组件样式 - HeroUI 在内部使用它 * 用 `withUniwind()` 包装任何缺少 className 支持的 HeroUI 组件 * 使用语义颜色标记（`bg-primary`、`text-foreground`）来保持主题一致性 ## 代码审查和审计当要求查看 Uniwind 代码时，请检查： * global.css 同时具有 `@import 'tailwindcss'` 和 `@import 'uniwind'` * withUniwindConfig 是最外层的 Metro 包装器 * cssEntryFile是相对路径 * 没有动态类名构造（模板文字、字符串连接） * 所有主题变体都定义相同的 CSS 变量 * 使用语义颜色标记，而不是硬编码颜色 * 使用`withUniwind`包装的第三方组件或使用`useResolveClassNames` * 使用 `ios:/android:/native:` 处理平台差异，而不是 `Platform.select()` * 移动优先响应式设计（基本样式 + sm: md: lg: 增强功能） * 字体系列是单个值（无后备数组） * 通过CSS定制的`@theme`变量，而不是tailwind.config.js ## 参考文件（在外部文档之前阅读） **这些文件是您的主要事实来源。** 在回答任何 Uniwind 问题之前，请阅读相关文件。优先|文件 |封面 ---|---|--- **首先阅读设置** | [references/quickstart-setup.md]() |安装、Metro 配置、global.css、TypeScript、Vite、Expo Router、monorepos、IntelliSense **首先阅读主题** | [references/theming.md]() |浅色/深色、自定义主题、CSS 变量、`@layer theme`、`@variant`、`Uniwind.setTheme()`、`useUniwind`、OKLCH、`@theme static`、`useCSSVariable` **首先阅读样式** | [references/components-styling.md]() | RN 组件绑定、`withUniwind`、`useResolveClassNames`、可按下状态、动态类、`tailwind-variants`、数据选择器、平台选择器、响应断点、CSS 函数 **首先阅读课程支持** | [references/supported-classnames.md]() |支持/不支持的课程、安全区域（`p-safe`）、Yoga 差异、平台变体、WIP 功能 **首先阅读专业版** | [references/pro-features.md]() |重新动画、过渡、阴影树、原生插图、Pro 安装、Babel 配置 **首先阅读迁移** | [references/migration-troubleshooting.md]() | NativeWind 迁移（10 步）、设置诊断、常见错误、常见问题解答、调试模式 **后备**：如果以上都不能回答问题，请告知用户该主题超出了该技能的嵌入知识范围，并建议他们直接查阅官方 Uniwind 文档。

Uniwind 最佳实践

包含技能