pt>

Vite插件

Vite 插件 unocss包.

安裝

pnpmyarnnpm

bash

pnpm add -D unocss

bash

yarn add -D unocss

bash

npm install -D unocss

安裝插件:

// vite.config.ts
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS(),
  ],
})

創建一個uno.config.ts文件:

// uno.config.ts
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS選項
})

添加 virtual:uno.css 到main入口:

// main.ts
import 'virtual:uno.css'

模式

Vite插件提供了一組模式，可以實現不同的行為。

`global`（默認）

這是插件的默認模式：在這種模式下，您需要在入口點添加 uno.css的導入。

此模式為build和dev啟用了一組Vite插件，並支持HMR。

生成的css將是在index.html上注入的全局樣式表。

`vue-scoped`

此模式將生成的CSS注入Vue SFCs<style scoped>以進行隔離。

`svelte-scoped`

svelte-scoped 模式已移至其自己的包，請參見 @unocss/svelte-scoped/vite。

`shadow-dom`

由於Web Components使用Shadow DOM，因此無法直接從全局樣式表對內容進行樣式設置（除非使用CSS自定義屬性，否則這些屬性將穿透Shadow DOM），因此需要將插件生成的CSS內聯到Shadow DOM樣式中。

要內聯生成的CSS，您只需要將插件模式配置為shadow-dom，並在每個web組件樣式的CSS塊上包含@unocss-placeholder。如果您在VueSFC中定義Web組件，並希望在UnoCSS旁邊定義自定義樣式，則可以將佔位符包裝在CSS註釋中，以避免IDE中出現語法錯誤。

`per-module`（實驗性）

此模式將為每個模塊生成一個CSS表，可以確定範圍。

`dist-chunk`（實驗性）

這種模式將為構建時的每個代碼塊生成一個CSS表，非常適合MPA。

在DevTools中編輯類

因為"按需"的限制，DevTools不知道那些你還沒有在源代碼中使用過的東西。因此，如果你想通過直接更改DevTools中的類來嘗試如何工作，只需在主條目中添加以下行即可。

import 'uno.css'
import 'virtual:unocss-devtools'

警告

請謹慎使用，在底層我們使用 MutationObserver 來檢測類的變化。這意味著不僅是你的手動更改，還包括腳本標籤中邏輯所做的更改也將被檢測幷包含在樣式表中。這可能會導致開發和生產構建之間的一些不一致，當你根據腳本標籤中的某些邏輯添加動態類時。我們建議將動態部分添加到安全列表，或者儘可能為生產構建設置 UI 迴歸測試。

框架

一些UI/App框架有一些必須解決的注意事項，如果您使用以下框架之一，請應用這些建議。

VanillaJS / TypeScript

使用 VanillaJS 或 TypeScript 時，需要添加 js 和 ts 文件擴展名以允許 UnoCSS 讀取和解析內容，默認情況下 js 和 ts 文件被排除，請查看從構建工具管道中提取部分。

React

如果你使用 @vitejs/plugin-react：

// vite.config.js
import UnoCSS from 'unocss/vite'
import React from '@vitejs/plugin-react'

export default {
  plugins: [
    React(),
    UnoCSS(),
  ],
}

如果你使用 @unocss/preset-attributify，應該從 build 腳本中刪除 tsc。

如果你使用 @vitejs/plugin-react 和 @unocss/preset-attributify，必須在 @vitejs/plugin-react 之前添加插件。

// vite.config.js
import UnoCSS from 'unocss/vite'
import React from '@vitejs/plugin-react'

export default {
  plugins: [
    UnoCSS(),
    React(),
  ],
}

你可以在 examples/vite-react 目錄中找到一個使用這兩個插件的 React 示例項目，請查看 package.json 中的腳本和 Vite 配置文件。

Preact

如果你使用 @preact/preset-vite：

// vite.config.js
import Preact from '@preact/preset-vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Preact(),
  ],
}

或者如果你使用 @prefresh/vite：

// vite.config.js
import Prefresh from '@prefresh/vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Prefresh(),
  ],
}

如果你使用 @unocss/preset-attributify，應該從 build 腳本中刪除 tsc。

你可以在 examples/vite-preact 目錄中找到一個使用這兩個插件的 Preact 示例項目，請查看 package.json 中的腳本和 Vite 配置文件。

Svelte

必須在 @sveltejs/vite-plugin-svelte 之前添加插件。

要支持 class:foo 和 class:foo={bar}，請添加插件並在 extractors 選項中配置 extractorSvelte。

你可以對 class: 使用簡單規則，例如 class:bg-red-500={foo} 或使用 shortcuts 包含多個規則，請參見下面鏈接的示例項目中的 src/App.svelte。

// vite.config.js
import { svelte } from '@sveltejs/vite-plugin-svelte'
import UnoCSS from 'unocss/vite'
import extractorSvelte from '@unocss/extractor-svelte'

export default {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* 更多選項 */
    }),
    svelte(),
  ],
}

Sveltekit

要支持 class:foo 和 class:foo={bar}，請添加插件並在 extractors 選項中配置 extractorSvelte。

你可以對 class: 使用簡單規則，例如 class:bg-red-500={foo} 或使用 shortcuts 包含多個規則，請參見下面鏈接的示例項目中的 src/routes/+layout.svelte。

// vite.config.js
import { sveltekit } from '@sveltejs/kit/vite'
import UnoCSS from 'unocss/vite'
import extractorSvelte from '@unocss/extractor-svelte'

/** @type {import('vite').UserConfig} */
const config = {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* 更多選項 */
    }),
    sveltekit(),
  ],
}

Web Components

要與 web components 一起工作，你需要在插件上啟用 shadow-dom 模式。

不要忘記刪除 uno.css 的導入，因為 shadow-dom 模式不會暴露它，應用程序將無法工作。

// vite.config.js
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
    }),
  ],
}

示例

基本示例

你可以在 examples/vite-basic 目錄中找到一個基本的 Vite 示例項目。

框架示例

我們為不同的框架提供了示例項目：

性能

緩存

為了提高性能，UnoCSS 使用了一個內存緩存。在大多數情況下，這是自動處理的。但是，如果你想禁用緩存或自定義緩存行為，你可以在配置中進行設置：

// uno.config.ts
export default defineConfig({
  // 禁用緩存
  cacheDisabled: true,
  
  // 自定義緩存大小（默認為 0，表示無限制）
  cachePrefixKey: 'my-custom-prefix',
  
  // 自定義緩存失效時間（默認為 0，表示永不過期）
  cacheExpireTime: 60 * 60 * 1000, // 1小時
})

性能提示

儘可能使用 shortcuts 來減少生成的 CSS 大小
避免使用過於複雜的動態類
使用 safelist 預生成頻繁使用的類

故障排除

類未生成

如果某些類沒有被生成，請檢查：

確保類名完全匹配
檢查 uno.config.ts 中的提取器配置
使用 safelist 強制生成特定類

// uno.config.ts
export default defineConfig({
  safelist: [
    'font-bold',
    'text-lg',
    // 其他需要強制生成的類
  ],
})

開發模式性能問題

如果在大型項目中遇到性能問題，可以嘗試：

限制提取的文件範圍
優化提取器配置
使用更具體的類名選擇器

高級用法

動態類生成

你可以使用函數動態生成類：

// uno.config.ts
export default defineConfig({
  rules: [
    [/^custom-(\d+)$/, ([, d]) => ({ 'padding-top': `${Number(d) * 10}px` })],
  ],
})

條件變體

創建基於條件的變體：

// uno.config.ts
export default defineConfig({
  variants: [
    (matcher) => {
      if (matcher.startsWith('admin:')) {
        return {
          matcher: matcher.slice(6),
          selector: s => `body.admin ${s}`,
        }
      }
    },
  ],
})

使用示例：

html

<div class="admin:text-red-500">僅在管理員模式下顯示紅色文本</div>

Vite插件 ​

安裝 ​

模式 ​

global（默認） ​

vue-scoped ​

svelte-scoped ​

shadow-dom ​

per-module（實驗性） ​

dist-chunk（實驗性） ​

在DevTools中編輯類 ​

框架 ​

VanillaJS / TypeScript ​

React ​

Preact ​

Svelte ​

Sveltekit ​

Web Components ​

示例 ​

基本示例 ​

框架示例 ​

性能 ​

緩存 ​

性能提示 ​

故障排除 ​

類未生成 ​

開發模式性能問題 ​

高級用法 ​

動態類生成 ​

條件變體 ​

License ​

Vite插件

安裝

模式

`global`（默認）

`vue-scoped`

`svelte-scoped`

`shadow-dom`

`per-module`（實驗性）

`dist-chunk`（實驗性）

在DevTools中編輯類

框架

VanillaJS / TypeScript

React

Preact

Svelte

Sveltekit

Web Components

示例

基本示例

框架示例

性能

緩存

性能提示

故障排除

類未生成

開發模式性能問題

高級用法

動態類生成

條件變體

License