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.

源代码

¥Source Code

提示

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

¥You can spend a little time reading this document to understand the changes

安装

¥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 presetWind4 from '@unocss/preset-wind4'
import { defineConfig } from 'unocss'

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

兼容性

¥Compatibility

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

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

主题

¥Theme

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

¥PresetWind4's theme is almost identical to PresetWind3's theme, but some theme keys have been adjusted.

警告

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

¥Please note when switching to PresetWind4, refer to the table below to check your theme key configuration and make appropriate adjustments.

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 is a global default theme configuration that will be applied to reset styles or used as default values for certain rules.

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

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

Click to view default values

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)',
  },
}

选项

¥Options

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

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

重置样式

¥Reset Styles

在 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-compact.css'

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

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

uno.config.ts

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

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

工具解析器

¥Utility Resolver

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

¥In PresetWind4, we've upgraded the postProcess hook to provide a more concise API. You can now directly customize utilities in the preset.

例如，如果你想使用 presetRemToPx 预设将 rem 转换为 px，则无需再单独导入此预设，因为 presetWind4 内部提供了此功能。

¥For example, 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 { createRemToPxResolver } from '@unocss/preset-wind4/utils'
import { defineConfig, presetWind4 } from 'unocss'

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

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

¥You can customize more resolver sets to process utilities and output the CSS you want.

具体实现方法请参考 postProcess 或 Wind4 预设测试用例。

¥For specific implementation methods, please refer to postProcess or the presetWind4 test case

主题预检

¥Theme Preflight

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

¥Choose how to generate theme CSS variables.

安装了 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：完全生成主题键。

  ¥true: Generate theme keys fully.

• false：禁用主题键。（不推荐⚠️）

  ¥false: Disable theme keys. (Not recommended ⚠️)

• 'on-demand'：仅在使用时生成主题键。-> ✅（默认）

  ¥'on-demand': Generate theme keys only when used. -> ✅ (By default)

生成的 CSS

¥Generated CSS

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

¥In the output of PresetWind4, two new layers have been added: theme and cssvar-property.

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

cssvar-property 图层

¥cssvar-property 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.

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

¥PresetWind4 enhances and is compatible with PresetWind3. Since other packages were originally developed for PresetWind3, some issues may arise when using them together. Known issues include:

presetWebFonts

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

¥When using presetWebFonts with PresetWind4, the fontFamily theme key is no longer supported. Please make the following adjustment:

uno.config.ts

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

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

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.

transformDirectives

transformDirectives 与 PresetWind4 无法良好兼容。存在一些已知问题，请谨慎使用。

¥transformDirectives doesn't work well with PresetWind4. There are some known issues, so please use it with caution.

警告

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

  ¥When using @apply to process rules that have @property, conflicts may occur between different layer levels.