Wind4 预设

UnoCSS 的 Tailwind4 CSS 紧凑预设。它与 PresetWind3 的所有功能兼容，并进一步对其进行了增强。

源代码

提示

您可以花一点时间阅读本文档，以了解这些变化

安装

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

uno.config.ts

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

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

兼容性

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

主题

PresetWind4 的主题几乎与 PresetWind3 的主题相同，但部分主题键已进行调整。

警告

请注意，在切换到 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 的默认值，您可以在主题配置中覆盖这些值。

点击查看默认值

uno.config.ts

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 类似，但有以下重要更改。

Preflights

我们在 PresetWind4 中添加了 preflights 配置选项，用于控制是否启用预设样式。

Reset

在 PresetWind4 中，我们将重置样式与 Tailwind4 保持一致，并将其集成到内部。您无需安装任何额外的 CSS 重置包，如 @unocss/reset 或 normalize.css。

main.ts

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

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

uno.config.ts

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

export default defineConfig({
  presets: [
    presetWind4({
      preflights: { 
        reset: true, 
      } 
    }),
  ],
})

Theme

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

Mode

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

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

uno.config.ts

import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: { 
        theme: true, 
      }, 
    }),
  ],
})

Process

并且您可以进一步控制主题变量的输出。例如，如果您想将主题变量中的 rem 转换为 px，我们提供了 createRemToPxProcessor 函数来处理您的主题变量。

uno.config.ts

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

export default defineConfig({
  presets: [
    presetWind4({
      preflights: { 
        theme: { 
          mode: 'on-demand', // Default by 'on-demand'
          process: createRemToPxProcessor(), 
        } 
      }, 
    }),
  ],
})

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

uno.config.ts

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

export default defineConfig({
  presets: [
    presetWind4({
      preflights: { 
        theme: { 
          process: createRemToPxProcessor(), 
        } 
      }, 
    }),
  ],
  postprocess: [createRemToPxProcessor()], 
})

生成的 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 层中，以便您更轻松地覆盖和直接使用这些变量。 它既可以全面生成，也可以按需生成。这些变量始终来自您的主题配置。

信息

生成的键名可能与 Tailwind4 不完全相同。为了尊重从 presetWind3 迁移过来的用户，我们尽量避免对主题中的键名进行重大更改。 您还可以在 预飞行主题处理 中自定义所需的输出。

: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 开发的，因此在与 PresetWind4 一起使用时可能会出现一些问题。已知问题包括：

预设 rem 转 px（presetRemToPx）

在 PresetWind4 中，presetRemToPx 已不再需要，因为它已在内部集成。您可以从配置中移除它。

请参考选项中的 process 选项。

预设网络字体（presetWebFonts）

当将 presetWebFonts 与 PresetWind4 一起使用时，fontFamily 主题键不再受支持。 请进行以下调整：

uno.config.ts

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

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

预设旧版兼容性（presetLegacyCompat）

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

有关更多信息，请参考 兼容性 部分。

转换指令（transformDirectives）

transformDirectives 与 PresetWind4 配合使用时效果不佳。存在一些已知问题，因此请谨慎使用。

警告

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