提取

UnoCSS的工作原理是從代碼庫中搜索實用程序的用法，並按需生成相應的CSS。我們稱這個過程為提取。

內容源碼

UnoCSS支持從多個來源提取實用程序用法：

• Pipeline - 直接從構建工具管道中提取
• Filesystem - 通過讀取和監視文件從文件系統中提取
• Inline - 從內聯純文本中提取

來自不同來源的實用程序的使用將被合併在一起，並生成最終的CSS。

從生成工具管道中提取

This is supported in the Vite and Webpack integrations.

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 or *.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 -->

Extracting from Filesystem

In cases that you are using integrations that does not have access to the build tools pipeline (for example, the PostCSS plugin), or you are integrating with backend frameworks such that the code does not go through the pipeline, you can manually specify the files to be extracted.

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

The files matched will be read directly from the filesystem and watched for changes at dev mode.

Extracting from Inline Text

Additionally, you can also extract utilities usages from inline text, that you might retrieve from elsewhere.

You may also pass an async function to return the content. But note that the function will only be called once at the build time.

// 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()
      },
    ],
  },
})

Limitations

Since UnoCSS works at build time, it means that only statically presented utilities will be generated and shipped to your app. Utilities that are used dynamically or fetched from external resources at runtime might NOT be detected or applied.

Safelist

Sometimes you might want to use dynamic concatenations like:

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

Due the fact that UnoCSS works in build time using static extraction, at the compile time it can't possibility know all the combination of the utilities then. For that, you can configure the safelist option.

// uno.config.ts
safelist: 'p-1 p-2 p-3 p-4'.split(' ')

The corresponding CSS will always be generated:

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

Or more flexible:

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

If you are seeking for a true dynamic generation at runtime, you may want to check out the @unocss/runtime package.

Static List Combinations

Another ways to work around the limitation of dynamically constructed utilities is that you can use an object that list all the combinations statically. For example, if you want to have this:

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

You can create an object that lists all the combinations (assuming you know any possible values of color you want to use)

// 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',
}

And then use it in your template:

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

Blocklist

Similar to safelist, you can also configure blocklist to exclude some utilities from being generated. This is useful to exclude some extraction false positives. Different from safelist, blocklist accepts both string for exact match and regular expression for pattern match.

// uno.config.ts
blocklist: [
  'p-1',
  /^p-[2-4]$/,
]

This will exclude p-1 and p-2, p-3, p-4 from being generated.