提取

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 -->

从文件系统中提取

在你使用的集成无法访问构建工具管道的情况下（例如 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 在构建时工作，这意味着只有静态呈现的实用工具会被生成并打包到你的应用中。那些在运行时动态使用或从外部资源获取的实用工具可能无法被检测到或应用。

Safelist（安全列表）

有时你可能会想用动态拼接的方式：

<div class="p-${size}"></div> <!-- 这样是无效的！ -->

由于 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> <!-- 这样是无效的！ -->

你可以创建一个对象，列出所有组合（假设你知道所有可能的 color 值）：

// 由于它们是静态的，UnoCSS 能在构建时提取到
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

然后在模板中这样用：

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

Blocklist（阻止列表）

类似于 safelist，你也可以配置 blocklist 来排除某些实用工具的生成。这对于排除一些提取的误报很有用。与 safelist 不同，blocklist 既可以用字符串精确匹配，也可以用正则表达式进行模式匹配。

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

这样会排除 p-1 以及 p-2、p-3、p-4 的生成。