SuperAPI AI 工具集

tailwind-setup

前端与建站

查看项目

更新于 10-16 10:56

技能介绍

用途 该技能用于在 Expo 项目中搭建 Tailwind CSS v4 通用样式环境,覆盖 iOS、Android 和 Web 三个平台。其技术组合为:Tailwind CSS v4(CSS 优先的现代配置方式)、react-native-css(React Native 的 CSS 运行时)、NativeWind v5(React Native 中 Tailwind 的 Metro 转换器)以及 @tailwindcss/postcss(Tailwind v4 的 PostCSS 插件)。

主要能力

  • 通过一条安装命令引入所需依赖,并处理 lightningcss 的版本兼容(resolutions 中指定 1.30.1)。
  • 配置 Metro(withNativewind,inlineVariables: false、globalClassNamePolyfill: false)与 PostCSS(postcss.config.mjs 使用 @tailwindcss/postcss)。
  • 通过 src/global.css 引入 Tailwind 的 theme、preflight、utilities,并按平台(android/ios)设置字体族变量。
  • 提供基于 useCssElement 的组件包装器,使 className 在 View、Text、ScrollView、Pressable、TextInput、TouchableHighlight、Image(expo-image,含 objectFit 到 contentFit 的重映射)以及 Animated 组件上生效。
  • 支持通过 @theme 在 CSS 中定义自定义主题变量,例如字体、行高与 leading 比例。
  • 支持平台特定样式(@media ios / @media android)与 Apple 语义系统颜色,可通过 platformColor 获取 iOS 原生颜色,并在 Web/Android 用 light-dark() 回退。
  • 提供 useCSSVariable 钩子,在 JavaScript 中使用 CSS 变量。
  • 说明与 NativeWind v4 / Tailwind v3 的关键差异,并给出常见问题排障指引。

使用方式

  1. 安装依赖:npx expo install tailwindcss@^4 nativewind@5.0.0-preview.2 react-native-css@0.0.0-nightly.5ce6396 @tailwindcss/postcss tailwind-merge clsx,并在 package.json 的 resolutions 中加入 lightningcss: 1.30.1。Expo 使用 lightningcss,因此不需要 autoprefixer;postcss 已默认包含在 expo 中。
  2. 创建 metro.config.js 并应用 withNativewind。
  3. 创建 postcss.config.mjs 并注册 @tailwindcss/postcss。
  4. 创建 src/global.css 并引入 Tailwind 各层。
  5. 在 src/tw 目录创建组件包装器(index.tsx、image.tsx、animated.tsx),从该目录导入 CSS 包装后的组件使用 className。
  6. 如需自定义主题,在 global.css 中使用 @theme 添加变量;如需平台颜色,按示例添加 CSS 变量与 @media 查询。

限制与注意事项

  • Tailwind v4 与 NativeWind v5 不再需要 babel.config.js 中的 NativeWind 配置,应移除相关 babel preset(若该文件仅含 NativeWind 配置)。
  • react-native-css 需要显式包装元素,未使用 useCssElement 包装的组件无法直接支持 className。
  • 平台颜色需在 @media ios 中使用 platformColor(),Web/Android 需回退到 light-dark()。
  • 自定义主题应使用 CSS 中的 @theme,而非 tailwind.config.js。
  • 若出现样式不生效,需检查 CSS 文件是否在应用入口导入、组件是否已包装、Metro 配置是否正确应用。
  • 部分依赖使用了预览版或 nightly 版本号,正式发布情况暂未提供。