Wind4 预设

🌐 Wind4 preset

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

🌐 The Tailwind4 CSS compact preset for UnoCSS. It's compatible with all features of PresetWind3 and enhances it further.

源代码

TIP

你可以花一点时间阅读本文档来了解这些变化。

安装

🌐 Installation

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 { defineConfig, presetWind4 } from 'unocss'

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

兼容性

🌐 Compatibility

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

🌐 Refer to Tailwind Compatibility to learn about browser support and compatibility.

主题

🌐 Theme

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

WARNING

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

PresetWind3	PresetWind4
fontFamily	font
fontSize	Moved to fontSize property in text
lineHeight	Moved to lineHeight property in text or use leading
letterSpacing	Moved to letterSpacing property in text or use tracking
borderRadius	radius
easing	ease
breakpoints	breakpoint
verticalBreakpoints	verticalBreakpoint
boxShadow	shadow
-	insetShadow
Size properties like width, height, maxWidth, maxHeight, minWidth, minHeight	Unified to use spacing
transitionProperty	property
gridAutoColumn, gridAutoRow, gridColumn, gridRow, gridTemplateColumn, gridTemplateRow	-
container.maxWidth	containers.maxWidth
-	defaults

Theme.defaults

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

以下是 Theme.defaults 的默认值，你可以在主题配置中进行覆盖。

🌐 Below are the default values for Theme.defaults, which you can override in your theme configuration.

点击查看默认值

uno.config.ts

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

export const defaults: Theme['default'] = {
  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)',
  },
}

选项

🌐 Options

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

🌐 PresetWind4's basic configuration is similar to PresetWind3, with the following important changes.

预检

🌐 Preflights

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

🌐 We have added the preflights configuration option in PresetWind4 to control whether to enable preset styles.

重置

🌐 Reset

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

🌐 In PresetWind4, we align the reset styles with tailwind4 and integrate them internally. You don't need to install any additional CSS reset package like @unocss/reset or normalize.css.

main.ts

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

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

🌐 You only need to control whether to enable reset styles through a switch:

uno.config.ts

import { defineConfig, presetWind4 } from 'unocss'

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

主题

🌐 Theme

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

🌐 Choose how to generate theme CSS variables.

模式

🌐 Mode

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

🌐 The UnoCSS engine with presetWind4 installed will automatically collect dependencies on the theme when parsing utilities and generate CSS variables at the end.

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

uno.config.ts

import { defineConfig, presetWind4 } from 'unocss'

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

进程

🌐 Process

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

🌐 And you can further control the output of your theme variables. For example, if you want to convert rem to px for theme variables, we provide the createRemToPxProcessor function to process your theme variables.

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 已经在内部提供了此功能。

🌐 By the way, if you want to use the presetRemToPx preset to convert rem to px, you no longer need to import this preset separately as presetWind4 provides this functionality internally.

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()], 
})

属性

🌐 Property

控制 properties 层中 @property CSS 规则的生成。

🌐 Control the generation of @property CSS rules in the properties layer.

默认情况下，PresetWind4 使用 @property 来定义 CSS 自定义属性，以实现更好的浏览器优化。这些属性会根据你的工具使用情况自动生成，并封装在 @supports 查询中，以实现渐进式增强。

🌐 By default, PresetWind4 uses @property to define CSS custom properties for better browser optimization. These properties are automatically generated based on your utilities usage and wrapped in a @supports query for progressive enhancement.

uno.config.ts

import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: {
        property: true, // Enable (default) | `false` to disable
      },
    }),
  ],
})

父元素和选择器

🌐 Parent and Selector

你可以自定义父容器和选择器：

🌐 You can customize the parent wrapper and selector:

uno.config.ts

import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: {
        property: {
          // Custom parent selector (e.g., use @layer instead of @supports)
          parent: '@layer custom-properties',
          // Custom selector for applying properties
          selector: ':where(*, ::before, ::after)',
        },
      },
    }),
  ],
})

如果你不想要 @supports 封装器，而是希望直接应用属性：

🌐 If you don't want the @supports wrapper and want properties applied directly:

uno.config.ts

import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: {
        property: {
          parent: false, // No parent wrapper
        },
      },
    }),
  ],
})

默认输出：

@supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or
  ((-moz-orient: inline) and (not (color: rgb(from red r g b)))) {
  *,
  ::before,
  ::after,
  ::backdrop {
    --un-text-opacity: 100%;
    /* ... */
  }
}

使用 parent: false：

*,
::before,
::after,
::backdrop {
  --un-text-opacity: 100%;
  /* ... */
}

生成的 CSS

🌐 Generated CSS

在 PresetWind4 的输出中，新增了三个图层：base、theme 和 properties。

🌐 In the output of PresetWind4, three new layers have been added: base, theme, and properties.

图层名称	描述	顺序
properties	由 @property 定义的 CSS 属性	-200
theme	与主题相关的 CSS 变量	-150
base	基础预设/重置样式	-100

properties 层

🌐 properties Layer

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

🌐 We have used @property to define CSS properties in many rules to achieve better performance and smaller size.

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

🌐 For example, commonly used utilities like text-op-xx, bg-op-xx, and so on.

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

theme 层

🌐 theme Layer

我们已将与主题相关的 CSS 变量放置在 theme 层，以便你更方便地直接覆盖和使用。它可以是全面的，也可以按需使用。它始终来源于你的主题配置。

🌐 We've placed theme-related CSS variables in the theme layer to make it easier for you to override and use directly. It can be comprehensive or on-demand. It always comes from your theme configuration.

INFO

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

: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;
  /* ... */
}

与其他预设的兼容性

🌐 Compatibility with Other Presets

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

presetRemToPx

presetRemToPx 在 PresetWind4 中不再需要，因为它已经内部包含。你可以从配置中将其移除。

请参阅选项中的 process 选项。

🌐 Refer to the process option in Options.

presetLegacyCompat

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

🌐 In presetWind4, we use the oklch color model to support better color contrast and color perception. Therefore, it is not compatible with presetLegacyCompat and is not recommended for use together.

请参阅兼容性部分以获取更多信息。

🌐 Please refer to the Compatibility section for more information.