提取

UnoCSS 的工作原理是从代码库中搜索使用的样式类并按需生成相应的 CSS。我们称这个过程为提取。

内容来源

UnoCSS supports extracting utilities usages from multiple sources: UnoCSS 支持从多个来源提取使用的样式：

Pipeline - 从构建工具管道中直接提取
Filesystem - 通过读取和监控文件从文件系统中提取
Inline - 从行内文本中提取

不同来源的样式类将合并在一起并生成最终的 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 扫描的文件中的任何位置添加 @unocss-include 魔术注释（基于每个文件）。如果需要扫描 *.js or *.ts 文件，也是这样配置。

// ./some-utils.js

// 默认情况下 `.js` 文件是不被扫描的
// 通过添加下面这个注释，可以告诉 UnoCSS 来扫描这个文件
// @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 。注意，必须成对使用才有效。

html

<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 插件），或者您正在与后端框架集成，这样代码就不会通过 pipeline ，您可以手动指定要提取的文件。

// 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 在构建时 工作，这意味着只会生成静态呈现的样式类并将其发送到您的应用程序。在运行时动态生成或从外部资源获取的样式类则可能不会被检测或应用。

安全列表

有时您可能想使用动态串联，例如：

html

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

由于 UnoCSS 在构建时使用静态提取来工作，因此在编译时它不可能知道实用程序的所有组合。为此，您可以配置 安全列表 选项。

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

总是会生成相应的CSS：

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

静态列表组合

解决动态构造样式类的另一种方法是，您可以使用一个静态列出所有组合的对象。例如，如果你想要这样：

html

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

您可以创建一个列出所有组合的对象（假设您知道要使用的 颜色 的任何可能值）

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

然后在您的模板中使用它：

html

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

黑名单

与 安全列表 类似，您还可以配置 黑名单 以排除某些实用程序的生成。这对于排除一些提取误报很有用。与 安全列表 不同， 黑名单 既接受字符串进行精确匹配，也接受正则表达式进行模式匹配。

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

这将排除生成 p-1 和 p-2, p-3, p-4。

提取 ​

内容来源 ​

从构建工具管道中提取 ​

从文件系统中提取 ​

从行内文本中提取 ​

限制 ​

安全列表 ​

静态列表组合 ​

黑名单 ​

提取

内容来源

从构建工具管道中提取

从文件系统中提取

从行内文本中提取

限制

安全列表

静态列表组合

黑名单