UnoCSS Applet

UnoCSS Applet — 小程序原子化 CSS 引擎兼容层#

资源概述#

UnoCSS Applet 是 UnoCSS 在小程序端的官方兼容方案。UnoCSS 是 Anthony Fu 开发的即时原子化 CSS 引擎，以高性能、高可扩展性著称。然而小程序平台对 CSS 有严格限制（不支持 :hover 伪类、不支持 * 通配选择器、不支持某些属性选择器等），直接使用 UnoCSS 会在小程序中产生大量无效样式或编译错误。

unocss-applet 通过预设和转换器解决这些限制：

• preset-applet：包裹 @unocss/preset-wind3（默认）或 @unocss/preset-wind4，自动处理小程序不支持的语法
• preset-rem-rpx：在 rem 和 rpx 之间自动转换，适配小程序的响应式单位
• transformer-attributify：为小程序启用 Attributify 模式（将 class="flex p-4" 简化为属性写法）
• transformer-hover：将 hover: 工具类改写为小程序原生的 hover-class 属性
• reset：小程序适配的 CSS Reset 样式集合

支持 UniApp (Vue3) 和 Taro (React) 两大跨端框架，兼容 Vite 和 Webpack5 构建工具。

设计规范#

• 单位系统：小程序使用 rpx（responsive pixel），unocss-applet 通过 preset-rem-rpx 实现 rem ↔ rpx 自动转换
  • 默认模式：rem → rpx（设计搞 750px 宽度时，1rem = 32rpx）
  • 反向模式：rpx → rem（用于 H5 端）
• 选择器限制：
  • ❌ 不支持 * 通配选择器 → preset-applet 会过滤或改写
  • ❌ 不支持 :hover 伪类 → transformer-hover 转为 hover-class
  • ❌ 不支持复杂属性选择器 → transformer-attributify 做兼容处理
• Attributify 模式：
  code复制

  <!-- 传统写法 -->
  <view class="flex items-center justify-center p-4">
    <text class="text-red-500 font-bold">Hello</text>
  </view>
  
  <!-- Attributify 模式（小程序兼容版） -->
  <view flex items-center justify-center p="4">
    <text text="red-500" font="bold">Hello</text>
  </view>
  

• hover-class 转换：
  code复制

  <!-- 写法（开发时） -->
  <view class="bg-blue-500 hover:bg-blue-600">按钮</view>
  
  <!-- 编译后（小程序运行时） -->
  <view class="bg-blue-500" hover-class="bg-blue-600" hover-stay-time="50">按钮</view>
  

审核规范#

UnoCSS Applet 为开发工具，不涉及平台审核。但需注意：

• 生成的 WXSS 样式需符合小程序包体限制（主包 2MB）
• 过多原子化类名可能增大样式文件体积，建议配合 @unocss/cli 做按需生成
• Attributify 模式在某些小程序平台（如百度）可能不被支持，需测试目标平台兼容性

开发指南#

安装#

npm i unocss-applet -D
# 或
yarn add unocss-applet -D
# 或
pnpm add unocss-applet -D

UnoCSS 配置#

// uno.config.ts
import type { Preset, SourceCodeTransformer } from 'unocss'
import { defineConfig, presetAttributify } from 'unocss'

import {
  presetApplet,
  presetRemRpx,
  transformerAttributify,
  transformerHover,
} from 'unocss-applet'

// UniApp: 检测是否为小程序平台
const isApplet = process.env?.UNI_PLATFORM?.startsWith('mp-') ?? false
// Taro: const isApplet = process.env.TARO_ENV !== 'h5' ?? false

const presets: Preset[] = []
const transformers: SourceCodeTransformer[] = []

if (isApplet) {
  // 小程序环境：使用兼容预设
  presets.push(presetApplet())
  presets.push(presetRemRpx())
  transformers.push(transformerAttributify({ ignoreAttributes: ['block'] }))
  transformers.push(transformerHover())
} else {
  // H5 环境：使用标准预设
  presets.push(presetApplet())
  presets.push(presetRemRpx({ mode: 'rpx2rem' }))
  presets.push(presetAttributify())
}

export default defineConfig({
  presets: [...presets],
  transformers: [...transformers],
})

UniApp + Vue3 + Vite 配置#

// vite.config.ts
import Uni from '@uni-helper/plugin-uni'
import UnoCSS from '@unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [Uni(), UnoCSS()],
})

// main.ts
import 'uno.css'

Taro + React + Webpack5 配置#

// config/index.js (UnoCSS v0.59+)
import { createSwcRegister, getModuleDefaultExport } from '@tarojs/helper'

export default async () => {
  createSwcRegister({ only: [filePath => filePath.includes('@unocss')] })
  const UnoCSS = getModuleDefaultExport(await import('@unocss/webpack'))
  return {
    mini: {
      webpackChain(chain) {
        chain.plugin('unocss').use(UnoCSS())
      }
    },
    h5: {
      webpackChain(chain) {
        chain.plugin('unocss').use(UnoCSS())
      }
    }
  }
}

// app.ts
import 'uno.css'

常见陷阱#

1. Taro H5 构建失败：@unocss/webpack 在 Taro H5 端有 ModuleParseError 问题，建议 H5 端改用 @unocss/cli 预生成 uno.css 再 import
2. UnoCSS 版本锁定：unocss-applet 的 peerDependencies 锁定了 UnoCSS 版本（当前 ~66.7.5），升级 UnoCSS 时需同步检查兼容性
3. Attributify 冲突：某些 HTML 属性名可能与 UnoCSS 工具类冲突（如 block），使用 ignoreAttributes 排除
4. 小程序不支持 : 伪类：所有 hover: / focus: / active: 类必须通过 transformer-hover 转换为 hover-class
5. 包体积控制：UnoCSS 默认按需生成，但 icons 预设（@unocss/preset-icons）可能引入大量图标字体，需按需配置
6. 设计稿宽度：preset-rem-rpx 默认基于 750px 设计稿（小程序标准），如果使用 375px 设计稿需调整配置

生态资源#

上游项目#

• UnoCSS：unocss/unocss — 即时原子化 CSS 引擎（Anthony Fu 开发）
• @unocss/preset-wind3/4：Tailwind CSS 兼容预设

社区集成示例#

• vitesse-uni-app：uni-helper/vitesse-uni-app — UniApp + UnoCSS 起步模板
• wot-starter：wot-ui/wot-starter — Wot Design Uni + UnoCSS 模板
• unibest：feige996/unibest — UniApp 最佳实践模板

相关工具#

• weapp-tailwindcss：Tailwind CSS 小程序兼容方案（另一种原子化 CSS 选择）
• unocss-preset-weapp：MellowCo/unocss-preset-weapp — 另一款 UnoCSS 小程序预设（unocss-applet 的前身之一）

版本更新#

• 当前版本：unocss-applet v0.13.8（npm，2026-07）
• 兼容性：UnoCSS ~66.7.5（peerDependencies 锁定）
• 支持矩阵：
  • UniApp Vue3 + Vite ✅
  • Taro 3.6 + React + Webpack5 ✅（小程序端）
  • Taro 4.2 + React + Webpack5 ✅（小程序端）
  • Taro H5 ⚠️（需使用 @unocss/cli 方案）
• 仓库 packages：
  • unocss-applet（主包，含所有预设和插件）
  • @unocss-applet/preset-applet（默认预设）
  • @unocss-applet/preset-rem-rpx（rem ↔ rpx 转换）
  • @unocss-applet/transformer-attributify（Attributify 模式）
  • @unocss-applet/transformer-hover（hover-class 转换）
  • @unocss-applet/reset（CSS Reset 集合）
• 核实记录：2026-07-21 核实 npm v0.13.8 为最新版本；GitHub 253⭐/13 forks；MIT 协议；仓库 2026-07-09 活跃推送