illegalCreed

中文

English

中文

English

Appearance

参考：UnoCSS 速查与对照表 ​

基于 UnoCSS v66.7.4 · 核于 2026-07

速查 ​

  • 定位：即时按需的原子化 CSS 引擎，no core utilities，一切来自 preset；同构引擎（非 PostCSS 插件）。
  • 接入：unocss/vite 插件 + 入口 import 'virtual:uno.css'；配置 uno.config.ts + defineConfig()。
  • 工具类来源：presetWind3（TW3/Windi）/ presetWind4（TW4）/ presetMini（精简）；presetUno 已弃用更名 Wind3。
  • 可编程：rules（静态 ['flex',{...}] / 动态 [/^m-.../,fn]）、shortcuts、variants、变体分组 hover:(...)。
  • 指令（transformerDirectives）：@apply / --at-apply / theme() / @screen。
  • 属性化（presetAttributify）：bg="blue-500"、无值 <div flex>、~、un- 前缀。
  • 图标（presetIcons）：i-carbon-sun，@iconify-json/*，模式 mask/bg/auto。
  • 踩坑：pnpm 严格隔离下图标自动发现失效 → 显式传 collections；动态类名 → safelist。
  • 性能：无解析/AST/扫描，约 5x 于 Windi/TW JIT；零依赖，内核约 6kb。

一、配置字段速查 ​

字段作用
presets预设数组，工具类的来源（后者优先）
rules自定义原子规则：静态 [str, CSSObj] / 动态 [regex, fn]
shortcuts工具类组合别名：静态对象 / 动态正则
variants前缀 → 选择器改写（hover:/dark: 等）
theme设计令牌（颜色/间距/断点/字体）
transformers源码转换器（directives / variant-group / attributify-jsx）
extractors如何从源码切出候选类名 token
layers各类别工具类的层叠/输出顺序
safelist强制生成（动态类兜底）
blocklist禁止生成（收窄设计系统）
preflights注入全局原始 CSS（reset/变量）
content扫描范围：filesystem/inline/pipeline
outputToCssLayers / cssLayerName输出映射到原生 CSS @layer
autocomplete编辑器/Inspector 补全模板

二、官方预设速查 ​

预设一句话
presetMini最小但必要的规则与变体，Wind 系基础子集
presetWind3对标 Tailwind 3 / Windi 的完整工具类
presetWind4对标 Tailwind 4：主题 CSS 变量化 + 内建 reset + oklch
presetUno已弃用，更名为 presetWind3
presetAttributify属性化模式（bg="blue-500"）
presetIcons纯 CSS 图标（i-carbon-sun），数据来自 Iconify
presetTypographyprose 富文本排版
presetWebFonts集成 Google Fonts 等网络字体
presetTagify标签化模式（工具类当标签名）
presetRemToPxrem → px（Wind4 已内建）

三、rules / shortcuts 写法速查 ​

ts
rules: [
  ['flex', { display: 'flex' }],                          // 静态
  [/^m-([\.\d]+)$/, ([, n]) => ({ margin: `${n}px` })],   // 动态
]
shortcuts: {
  btn: 'py-2 px-4 rounded bg-blue-500 text-white',        // 静态
}
shortcuts: [
  [/^btn-(\w+)$/, ([, c]) => `bg-${c}-500 text-white py-2 px-4 rounded`], // 动态
]
  • 动态规则第一参是正则匹配数组（[全匹配, 组1, ...]），第二参含 theme。
  • 函数返回 undefined = 本规则不处理，交后续规则。
  • 优先级：rules 后定义者优先；静态优先于动态；跨类别看 layers。

四、指令速查（transformerDirectives） ​

指令用途示例
@applyCSS 里复用工具类@apply text-center font-medium;
--at-apply纯 CSS 兼容的 @apply--at-apply: text-center my-2;
theme()内联主题令牌值color: theme('colors.blue.500');
@screen断点 → 媒体查询@screen sm { ... }、lt-sm、at-xl

applyVariable 默认识别 --at-apply/--uno-apply/--uno。变体分组 hover:(...) 需 transformerVariantGroup。

五、属性化速查（presetAttributify） ​

写法含义
bg="blue-500"= bg-blue-500
text="sm white"= text-sm text-white
<div flex>无值属性 = class="flex"
border="~ red"~ 引用属性名本身 = border border-red
un-text="red"un- 前缀防与 prop 冲突（prefixedOnly 更严格）

⚠️ JSX 无值属性 <div grid> 会被编译成 grid={true} 破坏匹配 → 需 @unocss/transformer-attributify-jsx。

六、图标速查（presetIcons） ​

项说明
类名i-[集合]-[图标]，如 i-carbon-sun、i-mdi-account
安装按需装 @iconify-json/[集合]
模式mask（单色可变色）/ bg（多色不可变色）/ auto（默认）
Node自动发现已装的 @iconify-json/*
浏览器无扫描，须 collections 显式提供（动态 import / CDN）

七、UnoCSS vs Tailwind CSS 对照 ​

维度UnoCSSTailwind CSS
本质引擎（内核无工具类）框架（内建约定与工具类）
工作形态同构引擎（Vite/CLI/CDN 运行时）主要是 PostCSS 插件
工具类来源preset（可自定义/封装复用）框架内建 + 插件
独有能力纯 CSS 图标、属性化、变体分组、CDN 运行时成熟插件生态、海量社区模板
插件系统不支持 Tailwind 插件有官方/社区插件体系
性能无 AST/扫描，约 5x（官方）现代版本 JIT 按需

八、Wind3 → Wind4 迁移速查 ​

项Wind3Wind4
fontFamilyfontFamilyfont
fontSize/lineHeight各自归入 text
borderRadiusborderRadiusradius
easingeasingease
尺寸键width/height 等spacing
主题输出常规值CSS 变量（默认 on-demand）
reset自引 @unocss/reset内建
色彩常规oklch
presetRemToPx引入内建，移除
presetLegacyCompat可用与 oklch 冲突，移除

九、常见错误对照 ​

现象根因解法
工具类完全不生效没引任何 preset，或漏 import 'virtual:uno.css'引 presetWind4() + 入口导入虚拟模块
@apply 报错/残留没启用 transformerDirectivestransformers: [transformerDirectives()]
生产 build failed to load icon "carbon-*"pnpm 严格隔离下图标自动发现失效显式 collections: { carbon: () => carbonIcons }
动态拼接的类/图标不显示扫描不到字面量加进 safelist
变体分组 hover:(...) 不展开没启用 transformerVariantGroup加该 transformer
JSX 无值属性 <div grid> 不生效被编译成 grid={true}加 transformer-attributify-jsx
shortcut 被工具类覆盖/覆盖不了layer 顺序调 layers / outputToCssLayers
用 presetUno 收到弃用提示旧别名改用 presetWind3
Wind4 主题定制失效用了旧主题键名改新键名（font/radius/ease 等）

十、权威链接 ​