Wind4 预设

UnoCSS 的 Tailwind4 CSS 紧凑预设。它完全兼容 PresetWind3 的所有功能，并进一步增强。

源代码

TIP

建议花一点时间阅读本文档以了解变化

安装

pnpm

pnpm add -D @unocss/preset-wind4

yarn

yarn add -D @unocss/preset-wind4

npm

npm install -D @unocss/preset-wind4

bun

bun add -D @unocss/preset-wind4

import presetWind4 from '@unocss/preset-wind4'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4(),
    //  ^?
  ],
})

兼容性

请参考 Tailwind 兼容性 了解浏览器支持和兼容性。

主题

PresetWind4 的主题几乎与 PresetWind3 的主题相同，但一些主题键已经调整。

WARNING

切换到 PresetWind4 时，请注意查看下表，检查您的主题键配置并进行适当的调整。

PresetWind3	PresetWind4
fontFamily	font
fontSize	移动到 text 的 fontSize 属性
lineHeight	移动到 text 的 lineHeight 属性或使用 leading
letterSpacing	移动到 text 的 letterSpacing 属性或使用 tracking
borderRadius	radius
easing	ease
breakpoints	breakpoint
verticalBreakpoints	verticalBreakpoint
boxShadow	shadow
-	insetShadow
尺寸属性如 width、height、maxWidth、maxHeight、minWidth、minHeight	统一使用 spacing
transitionProperty	property
gridAutoColumn、gridAutoRow、gridColumn、gridRow、gridTemplateColumn、gridTemplateRow	-
container.maxWidth	containers.maxWidth
-	defaults

Theme.defaults

Theme.defaults 是一个全局默认主题配置，将应用于 reset 样式或用作某些规则的默认值。

以下是 Theme.defaults 的默认值，您可以在主题配置中覆盖它们。

点击查看默认值

import type { Theme } from '@unocss/preset-wind4/theme'

export const defaults: Theme['defaults'] = {
  transition: {
    duration: '150ms',
    timingFunction: 'cubic-bezier(0.4, 0, 0.2, 1)',
  },
  font: {
    family: 'var(--font-sans)',
    featureSettings: 'var(--font-sans--font-feature-settings)',
    variationSettings: 'var(--font-sans--font-variation-settings)',
  },
  monoFont: {
    family: 'var(--font-mono)',
    featureSettings: 'var(--font-mono--font-feature-settings)',
    variationSettings: 'var(--font-mono--font-variation-settings)',
  },
}

选项

PresetWind4 的基本配置类似于 PresetWind3，但有以下重要变化。

重置样式

在 PresetWind4 中，我们将重置样式与 tailwind4 对齐并在内部集成。您不需要安装任何额外的 CSS 重置包，如 @unocss/reset 或 normalize.css。

import '@unocss/reset/tailwind.css'
import '@unocss/reset/tailwind-compact.css'

您只需要通过开关控制是否启用重置样式：

import presetWind4 from '@unocss/preset-wind4'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      reset: true, 
      // ^?
    }),
  ],
})

实用工具解析器

在 PresetWind4 中，我们升级了 postProcess 钩子以提供更简洁的 API。现在您可以直接在预设中自定义 utilities。

例如，如果您想使用 presetRemToPx 预设将 rem 转换为 px，您不再需要单独导入此预设，因为 presetWind4 内部已经提供了这一功能。

import { createRemToPxResolver } from '@unocss/preset-wind4/utils'
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      utilityResolver: createRemToPxResolver() 
    }),
  ],
})

您可以自定义更多解析器集来处理 utilities 并输出您想要的 CSS。

关于具体实现方法，请参考 postProcess 或 presetWind4 测试用例

主题预处理

选择如何生成主题 CSS 变量。

安装了 presetWind4 的 UnoCSS 引擎在解析实用工具时会自动收集主题依赖，并在最后生成 CSS 变量。

• true：完全生成主题键。
• false：禁用主题键。（不推荐 ⚠️）
• 'on-demand'：仅在使用时生成主题键。-> ✅ (默认)

生成的 CSS

在 PresetWind4 的输出中，新增了两个图层：theme 和 cssvar-property。

图层名称	描述	顺序
cssvar-property	由 @property 定义的 CSS 属性	-200
theme	主题相关的 CSS 变量	-150

cssvar-property 图层

我们在许多规则中使用 @property 来定义 CSS 属性，以实现更好的性能和更小的体积。

例如，常用的实用工具如 text-op-xx、bg-op-xx 等。

@property --un-text-opacity {
  syntax: '<percentage>';
  inherits: false;
  initial-value: 100%;
}

theme 图层

我们将主题相关的 CSS 变量放在 theme 图层中，使您更容易覆盖和直接使用。 它可以是全面的或按需的。它始终来自您的主题配置。

:root,
:host {
  --spacing: 0.25rem;
  --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
    'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
  --font-serif: ui-serif, Georgia, Cambria, 'Times New Roman', Times, serif;
  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
  --colors-black: #000;
  --colors-white: #fff;
  /* ... */
}

与其他预设的兼容性

PresetWind4 增强并兼容 PresetWind3。由于其他包最初是为 PresetWind3 开发的，因此在一起使用时可能会出现一些问题。已知的问题包括：

presetWebFonts

在使用 presetWebFonts 和 PresetWind4 时，不再支持 fontFamily 主题键。 请进行以下调整：

import { defineConfig, presetWebFonts, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4(),
    presetWebFonts({
      themeKey: 'font', 
      // ^?
    }),
  ],
})

presetLegacyCompat

在 presetWind4 中，我们使用 oklch 颜色模型以支持更好的颜色对比度和颜色感知。因此，它与 presetLegacyCompat 不兼容，不建议一起使用。

请参考兼容性部分了解更多信息。

transformDirectives

transformDirectives 与 PresetWind4 配合使用时可能会出现问题。请谨慎使用。

WARNING

• 当使用 @apply 处理具有 @property 的规则时，不同图层级别之间可能会发生冲突。