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 的規則時，不同圖層級別之間可能會發生衝突。