UnoCSS

外觀

Vite 外掛 ​

Vite 外掛隨附於 unocss 套件中。

安裝 ​

bash
pnpm add -D unocss
bash
yarn add -D unocss
bash
npm install -D unocss

安裝外掛

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

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

建立 uno.config.ts 檔案

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

export default defineConfig({
  // ...UnoCSS options
})

將 virtual:uno.css 加入您的主要入口點

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

模式 ​

Vite 外掛附帶一組模式，可啟用不同的行為。

global（預設） ​

這是外掛的預設模式：在此模式下，您需要在入口點加入 uno.css 的引入。

此模式會啟用一組 Vite 外掛，用於 build 和支援 HMR 的 dev。

生成的 css 將是一個注入到 index.html 的全域樣式表。

vue-scoped ​

此模式會將生成的 CSS 注入 Vue SFC 的 <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 魔法佔位符。如果您在 Vue SFC 中定義 Web 元件，並且想要與 UnoCSS 一起定義自訂樣式，您可以將佔位符包裝在 CSS 註釋中，以避免 IDE 中出現語法錯誤。

per-module（實驗性） ​

此模式將為每個模組生成一個 CSS 樣式表，可以設定作用域。

`dist-chunk`（實驗性） ​

此模式將為建置時每個程式碼區塊生成一個 CSS 樣式表，非常適合 MPA。

在開發工具中編輯類別 ​

由於「按需」的限制，開發工具不知道您尚未在原始碼中使用的類別。因此，如果您想嘗試透過直接在開發工具中更改類別來了解其運作方式，只需將以下幾行加入您的主要入口點即可。

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

警告

請謹慎使用，在底層我們使用 MutationObserver 來偵測類別的變化。這表示不僅您的手動更改，而且您的腳本所做的更改也將被偵測並包含在樣式表中。當您根據腳本標籤中的某些邏輯新增動態類別時，這可能會導致開發環境和生產環境建置之間出現一些不一致。如果可能，我們建議將您的動態部分新增到 安全清單 或為您的生產環境建置設定 UI 迴歸測試。

框架 ​

某些 UI/應用程式框架有一些必須修復的注意事項才能使其運作，如果您使用以下框架之一，只需套用建議即可。

VanillaJS / TypeScript ​

使用 VanillaJS 或 TypeScript 時，您需要新增 js 和 ts 檔案副檔名以允許 UnoCSS 讀取和解析內容，預設情況下會排除 js 和 ts 檔案，請參閱 從建置工具管道提取 章節。

React ​

如果您使用 @vitejs/plugin-react

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

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

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

如果您將 @vitejs/plugin-react 與 @unocss/preset-attributify 一起使用，則必須在 @vitejs/plugin-react 之前新增外掛。

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

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

您在 examples/vite-react 目錄中有一個使用這兩個外掛的 React 範例專案，請檢查 package.json 中的腳本及其 Vite 設定檔。

Preact ​

如果您使用 @preact/preset-vite

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

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

或者如果您使用 @prefresh/vite

vite.config.ts
ts
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.ts
ts
import { svelte } from '@sveltejs/vite-plugin-svelte'
import extractorSvelte from '@unocss/extractor-svelte'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* more options */
    }),
    svelte(),
  ],
}

Sveltekit ​

要支援 class:foo 和 class:foo={bar}，請新增外掛並在 extractors 選項中設定 extractorSvelte。

您可以使用帶有 `class:` 的簡單規則，例如 `class:bg-red-500={foo}` 或使用 `shortcuts` 來包含多個規則，請參閱下方連結範例專案中的 `src/routes/+layout.svelte`。

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

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

Web Components ​

要使用 Web 元件，您需要在外掛上啟用 shadow-dom 模式。

不要忘記移除 uno.css 的引入，因為 shadow-dom 模式不會公開它，應用程式將無法運作。

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

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

在每個 web component 中，只需在其樣式 CSS 區塊中新增 @unocss-placeholder 即可

ts
const template = document.createElement('template')
template.innerHTML = `
<style>
:host {...}
@unocss-placeholder
</style>
<div class="m-1em">
...
</div>
`

如果您使用的是 Lit

ts
@customElement('my-element')
export class MyElement extends LitElement {
  static styles = css`
    :host {...}
    @unocss-placeholder
  `
  // ...
}

您在 examples/vite-lit 目錄中有一個 Web Components 範例專案。

::part 內建支援 ​

您可以使用 ::part，因為外掛程式透過 `shortcuts` 以及使用 `preset-mini` 中的 `part-[]:` 規則來支援它，例如將其與簡單規則一起使用，例如 `part-[]:bg-green-500` 或使用一些 `shortcut`：請參閱下方連結範例專案中的 `src/my-element.ts`。

part-[<part-name>]:<rule|shortcut> 僅適用於使用 `shadow-dom` 模式的這個外掛程式。

外掛程式使用 `nth-of-type` 來避免在同一個 Web 元件中以及不同 Web 元件上相同部分的衝突，您不需要擔心，外掛程式會為您處理。

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

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
      shortcuts: [
        { 'cool-blue': 'bg-blue-500 text-white' },
        { 'cool-green': 'bg-green-500 text-black' },
      ],
      /* more options */
    }),
  ],
}

然後在您的 Web 元件中

ts
// my-container-wc.ts
const template = document.createElement('template')
template.innerHTML = `
<style>
@unocss-placeholder
</style>
<my-wc-with-parts class="part-[cool-part]:cool-blue part-[another-cool-part]:cool-green">...</my-wc-with-parts>
`
ts
// my-wc-with-parts.ts
const template = document.createElement('template')
template.innerHTML = `
<style>
@unocss-placeholder
</style>
<div>
  <div part="cool-part">...</div>
  <div part="another-cool-part">...</div>
</div>
`

Solid ​

您需要在 UnoCSS 的外掛程式之後新增 `vite-plugin-solid` 外掛程式。

vite.config.ts
ts
import UnoCSS from 'unocss/vite'
import solidPlugin from 'vite-plugin-solid'

export default {
  plugins: [
    UnoCSS({
      /* options */
    }),
    solidPlugin(),
  ],
}

Elm ​

您需要在 UnoCSS 的外掛程式之前新增 `vite-plugin-elm` 外掛程式。

vite.config.ts
ts
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'
import Elm from 'vite-plugin-elm'

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

舊版 ​

如果 `@vitejs/plugin-legacy` 使用 `renderModernChunks: false`，您需要將其新增到 `unocss` 選項中

ts
import legacy from '@vitejs/plugin-legacy'
import vue from '@vitejs/plugin-vue'
import { presetUno } from 'unocss'
import Unocss from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue(),
    Unocss({
      presets: [presetUno()],
      legacy: {
        renderModernChunks: false,
      },
    }),
    legacy({
      targets: ['defaults', 'not IE 11'],
      renderModernChunks: false,
    }),
  ],
})

授權條款 ​

依據 MIT 授權條款發行。

版權所有 © 2021-PRESENT Anthony Fu