提取

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-include 幻数注释，在您希望 UnoCSS 扫描的任何文件的基础上。如果您需要扫描 *.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。