提取

UnoCSS通过在代码库中搜索工具的使用情况，并根据需求生成相应的CSS。我们将这个过程称为提取（extracting）。

内容来源

UnoCSS支持从多个来源提取工具的使用情况：

  • Pipeline – 从您的构建工具流程中提取正确的部分
  • Filesystem – 通过读取和监视文件从您的文件系统中提取
  • inline – 从内联的纯文本中提取

来自不同来源的工具使用情况将被合并在一起，并生成最终的CSS。

从构建工具流程中提取内容

这在 Vite 和 Webpack 的集成中得到支持。

UnoCSS将读取通过构建工具流程的内容，并从中提取工具的使用情况。这是最高效和准确的提取方式，因为我们只智能提取实际在您的应用程序中使用的工具使用情况，并且在提取过程中不进行额外的文件IO操作。

默认情况下，UnoCSS将从构建流程中的具有扩展名 .jsx、.tsx、.vue、.md、.html、.svelte、.astro 的文件中提取工具的使用情况，并根据需要生成相应的CSS。默认情况下，不包括 .js 和 .ts 文件。

要进行配置，您可以更新您的 uno.config.ts 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 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 文件包括在扫描目标中。

1
2
3
4
5
6
7
8
9
// ./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 来实现：

1
2
3
4
5
6
7
8
9
10
<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 插件），或者您正在与后端框架进行集成且代码不经过构建流程，您可以手动指定要提取的文件。

1
2
3
4
5
6
7
8
9
// uno.config.ts
export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html',
    ]
  }
})

匹配的文件将直接从文件系统中读取，并在开发模式下进行更改监视。

从内联文本中提取

此外，您还可以从内联文本中提取工具的使用情况，这些文本可能来自其他地方。

您还可以传递一个异步函数来返回内容。但请注意，该函数只会在构建时调用一次。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 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 在构建时运行，这意味着只有静态呈现的工具才会生成并传递到您的应用程序中。在运行时动态使用或从外部资源获取的工具可能不会被应用。

安全列表

有时您可能希望使用动态的拼接，例如：

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

由于 UnoCSS 在构建时使用静态提取，我们无法在编译时知道所有工具的组合情况。因此，您可以配置 safelist 选项来解决这个问题。

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

生成对应的 CSS：

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

或者更灵活：

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

如果您希望在运行时进行真正的动态生成，您可以查看 @unocss/runtime 包

黑名单

类似于 safelist，您还可以配置 blocklist 来排除某些工具的生成。不同于 safelist，blocklist 接受字符串进行精确匹配和正则表达式进行模式匹配。

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

这将排除 p-1、p-2、p-3 和 p-4 的生成。这对于排除一些误报非常有用。