設定 UnoCSS

組態

組態設定是 UnoCSS 強大的關鍵。

• 規則 - 定義原子 CSS 工具類
• 捷徑 - 將多個規則合併成單一簡寫。
• 主題 - 定義主題變數。
• 變體 - 將自定義慣例應用於規則。
• 提取器 - 定義提取工具類使用方式的位置和方法。
• 預設樣式 - 定義全域原始 CSS。
• 層級 - 定義每個工具類層級的順序。
• 預設集 - 常見用例的預定義組態。
• 轉換器 - 將使用者原始碼轉換為程式碼的轉換器，以支援慣例。
• 自動完成 - 定義自定義的自動完成建議。

選項

rules

• **類型：** Rule<Theme>[]

用於產生 CSS 工具類的規則。較後面的項目具有較高的優先順序。

shortcuts

• **類型：** UserShortcuts<Theme>

類似於 Windi CSS 的捷徑，允許您透過組合現有的工具類來建立新的工具類。較後面的項目具有較高的優先順序。

theme

• **類型：** `Theme`

主題物件，用於規則之間的共享設定。

extendTheme

• **類型：** Arrayable<ThemeExtender<Theme>> 自定義函式會改變主題物件。

也可以返回一個新的主題物件來完全取代原始物件。

variants

• **類型：** Variant<Theme>[]

預處理選擇器的變體，能夠重寫 CSS 物件。

extractors

• **類型：** `Extractor[]`

用於處理原始檔並輸出可能的類別/選擇器的提取器。可以支援特定語言。

preflights

• **類型：** Preflight<Theme>[]

原始 CSS 注入。

layers

• **類型：** `Record<string, number>`

層級順序。預設為 0。

outputToCssLayers

• **類型：** `boolean | UseCssLayersOptions`
• **預設值：** `false`

將層級輸出到 CSS Cascade Layers。

cssLayerName

• **類型：** `(internalLayer: string) => string | undefined | null`

指定內部層級應輸出到的 CSS 層級的名稱（可以是子層級，例如 "mylayer.mysublayer"）。

如果返回 `undefined`，則內部層級名稱將用作 CSS 層級名稱。如果返回 `null`，則內部層級將不會輸出到 CSS 層級。

sortLayers

• **類型：** `(layers: string[]) => string[]`

自定義函式來排序層級。

presets

• **類型：** `(PresetOrFactory<Theme> | PresetOrFactory<Theme>[])[]`

常見用例的預定義組態。

transformers

• **類型：** `SourceCodeTransformer[]`

原始碼的自定義轉換器。

blocklist

• **類型：** `BlocklistRule[]`

用於排除設計系統選擇器的規則（以縮小可能性）。結合 `warnExcluded` 選項還可以幫助您識別錯誤用法。

safelist

• **類型：** `string[]`

始終包含的工具類。

preprocess

• **類型：** `Arrayable<Preprocessor>`

預處理傳入的工具類，返回 falsy 值以排除。

postprocess

• **類型：** `Arrayable<Postprocessor>`

後處理產生的 utils 物件。

separators

• **類型：** `Arrayable<string>`
• **預設值：** `[':', '-']`

變體分隔符號。

extractorDefault

• **類型：** `Extractor | null | false`
• **預設值：** `import('@unocss/core').defaultExtractor`

始終套用的預設提取器。預設情況下，它會根據空格和引號拆分原始碼。

它可能會被預設集或使用者設定取代，只能有一個預設提取器，後面的提取器會覆蓋前面的提取器。

傳遞 `null` 或 `false` 以停用預設提取器。

autocomplete

自動完成的其他選項。

templates

• **類型：** `Arrayable<AutoCompleteFunction | AutoCompleteTemplate>`

自定義函式/範本以提供自動完成建議。

extractors

• **類型：** `Arrayable<AutoCompleteExtractor>`

自定義提取器以取得可能的類別，並將類別名稱樣式建議轉換為正確的格式。

shorthands

• **類型：** `Record<string, string | string[]>`

自定義簡寫以提供自動完成建議。如果值是一個陣列，它將與 `|` 連接並用 `()` 包裹。

content

要提取為工具類用法的來源選項。

支援的來源

• `filesystem` - 從檔案系統提取
• `plain` - 從純文字內聯提取
• `pipeline` - 從建構工具的轉換管道（例如 Vite 和 Webpack）中提取

從每個來源提取的用法將被**合併**在一起。

filesystem

• **類型：** `string[]`
• **預設值：** `[]`

除了其他內容來源之外，還要從檔案系統中提取的 Glob 模式。

在開發模式下，檔案將被監視並觸發 HMR。

inline

• **類型：** `string | { code: string; id?: string } | (() => Awaitable<string | { code: string; id?: string }>)) []`

要提取的內聯文字。

pipeline

用於確定是否從建構工具的轉換管道中提取某些模組的篩選器。

目前僅適用於 Vite 和 Webpack 整合。

設定為 `false` 以停用。

include

• **類型：** `FilterPattern`
• **預設值：** `[/\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/]`

篩選要提取的檔案的模式。支援正規表示式和 `picomatch` Glob 模式。

預設情況下，**不會**提取 `.ts` 和 `.js` 檔案。

exclude

• **類型：** `FilterPattern`
• **預設值：** `[/\.(css|postcss|sass|scss|less|stylus|styl)($|\?)/]`

篩選**不**要提取的檔案的模式。支援正規表示式和 `picomatch` Glob 模式。

預設情況下，也會提取 `node_modules` 和 `dist`。

configResolved

• **類型：** `(config: ResolvedConfig) => void`

修改已解析設定的鉤子。

首先運行預設集，然後是使用者設定。

configFile

• **類型：** `string | false`

從設定檔載入。

設定為 `false` 以停用。

configDeps

• **類型：** `string[]`

也會觸發設定重新載入的檔案清單。

命令列介面 (CLI)

UnoCSS 命令列介面選項。

entry (入口)

• 類型： Arrayable<CliEntryItem>

UnoCSS cli 的進入點。

patterns (模式)

• **類型：** `string[]`

從檔案系統中提取的 Glob 模式。

outFile (輸出檔案)

• 類型： string (字串)

輸出檔案路徑。

shortcutsLayer (捷徑層)

• 類型： string (字串)
• 預設值： 'shortcuts'

捷徑的佈局名稱。

envMode (環境模式)

• 類型： 'dev' | 'build' (開發 | 建置)
• 預設值： 'build' (建置)

環境模式。

details (詳細資訊)

• 類型： boolean (布林值)

公開內部細節以進行除錯/檢查。

warn (警告)

• 類型： boolean (布林值)
• 預設值： true (真)

當在黑名單中出現匹配的選擇器時發出警告。