萃取

UnoCSS 的運作方式是從您的程式碼庫中搜尋工具程式的用法，並按需產生相應的 CSS。我們稱此過程為 **萃取**。

內容來源

UnoCSS 支援從多個來源萃取工具程式的用法

• 流水線 - 直接從您的建構工具流水線中萃取
• 檔案系統 - 透過讀取和監控檔案從檔案系統中萃取
• 內嵌 - 從內嵌純文字中萃取

來自不同來源的工具程式用法將被合併在一起並產生最終的 CSS。

從建構工具流水線中萃取

這在 Vite 和 Webpack 整合中受到支援。

UnoCSS 將讀取通過您的建構工具流水線的內容，並從中萃取工具程式的用法。這是最有效率且準確的萃取方式，因為我們只萃取應用程式中實際使用的用法，而且在萃取過程中沒有額外的檔案 I/O 操作。

預設情況下，UnoCSS 將從建構流水線中副檔名為 .jsx、.tsx、.vue、.md、.html、.svelte、.astro 的檔案中萃取工具程式用法，然後按需產生適當的 CSS。.js 和 .ts 檔案 **預設不包含在內**。

要設定它們，您可以更新您的 uno.config.ts

uno.config.ts

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // the default
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // include js/ts files
        'src/**/*.{js,ts}',
      ],
      // exclude files
      // exclude: []
    },
  },
})

您也可以在每個檔案中，在您希望 UnoCSS 掃描的檔案中的任何位置，新增 @unocss-include 魔法註解。如果您需要掃描 *.js 或 *.ts 檔案，請在設定中將它們新增為掃描目標，以包含所有 js/ts 檔案。

// ./some-utils.js

// since `.js` files are not included by default,
// the following comment tells UnoCSS to force scan this file.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

同樣地，您也可以新增 @unocss-ignore 來略過整個檔案的掃描和轉換。

如果您希望 UnoCSS 跳過一段程式碼，而不從任何萃取檔案中萃取，您可以成對使用 @unocss-skip-start 和 @unocss-skip-end。請注意，它必須 **成對使用** 才能生效。

<p class="text-green text-xl">
  Green Large
</p>

<!-- @unocss-skip-start -->
<!-- `text-red` will not be extracted -->
<p class="text-red">
  Red
</p>
<!-- @unocss-skip-end -->

從檔案系統中萃取

如果您使用的整合無法存取建構工具流水線（例如，PostCSS 插件），或者您正在與後端框架整合，使得程式碼未通過流水線，您可以手動指定要萃取的檔案。

uno.config.ts

export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html',
    ],
  },
})

匹配的檔案將直接從檔案系統中讀取，並在開發模式下監控變更。

從內嵌文字中萃取

此外，您也可以從您可能從其他地方取得的內嵌文字中萃取工具程式的用法。

您也可以傳遞一個非同步函式來返回內容。但請注意，該函式只會在建構時被呼叫一次。

uno.config.ts

export default defineConfig({
  content: {
    inline: [
      // plain text
      '<div class="p-4 text-red">Some text</div>',
      // async getter
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})

限制

由於 UnoCSS 在 **建構時** 運作，這表示只有靜態呈現的工具程式會被產生並發布到您的應用程式。在運行時動態使用或從外部資源擷取的工具程式可能 **不會** 被偵測或套用。

安全名單

有時您可能想要使用動態串連，例如

<div class="p-${size}"></div> <!-- this won't work! -->

由於 UnoCSS 在建構時使用靜態萃取方式運作，因此在編譯時它不可能知道所有工具程式的組合。為此，您可以設定 safelist 選項。

uno.config.ts

safelist: 'p-1 p-2 p-3 p-4'.split(' ')

相應的 CSS 將始終被產生

.p-1 { padding: 0.25rem; }
.p-2 { padding: 0.5rem; }
.p-3 { padding: 0.75rem; }
.p-4 { padding: 1rem; }

或者更靈活的方式

uno.config.ts

safelist: [
  ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
]

如果您正在尋找真正的運行時動態產生，您可能需要查看 @unocss/runtime 套件。

靜態列表組合

解決動態建構工具程式限制的另一種方法是，您可以使用一個物件 **靜態地** 列出所有組合。例如，如果您想要這樣做

<div class="text-${color} border-${color}"></div> <!-- this won't work! -->

您可以建立一個物件，列出所有組合（假設您知道要使用的 color 的所有可能值）

// Since they are static, UnoCSS will able to extract them on build time
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

然後在您的模板中使用它

<div class="${classes[color]}"></div>

封鎖名單

與 safelist 類似，您也可以設定 blocklist 來排除某些工具程式的產生。這對於排除一些萃取誤判很有用。與 safelist 不同的是，blocklist 接受字串進行精確匹配，也接受正則表達式進行模式匹配。

uno.config.ts

blocklist: [
  'p-1',
  /^p-[2-4]$/,
]

這將排除 p-1、p-2、p-3、p-4 的產生。