提取

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.