提取

¥Extracting

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

¥UnoCSS works by searching for the utilities usages from your codebase and generate the corresponding CSS on-demand. We call this process extracting.

内容来源

¥Content Sources

UnoCSS 支持从多个来源提取工具用法：

¥UnoCSS supports extracting utilities usages from multiple sources:

管道 - 直接从构建工具管道中提取
¥Pipeline - Extract right from your build tools pipeline
文件系统 - 通过读取和观察文件从文件系统中提取
¥Filesystem - Extract from your filesystem by reading and watching files
行内 - 从内嵌纯文本中提取
¥Inline - Extract from inline plain text

来自不同来源的工具的用法将合并在一起并生成最终的 CSS。

¥Usages of utilities that comes from different sources will be merged together and generate the final CSS.

从构建工具管道中提取

¥Extracting from Build Tools Pipeline

Vite 和 Webpack 集成支持此功能。

¥This is supported in the Vite and Webpack integrations.

UnoCSS 将读取通过构建工具管道的内容并从中提取工具的用法。这是最有效、最准确的提取方法，因为我们仅巧妙地提取应用中实际使用的用法，而在提取过程中不会进行额外的文件 I/O。

¥UnoCSS will read the content that goes through your build tools pipeline and extract the utilities usages from them. This is the most efficient and accurate way to extract as we only extract the usages that are actually used in your app smartly with no additional file I/O is made during the extraction.

默认情况下，UnoCSS 将从构建管道中扩展名为 .jsx、.tsx、.vue、.md、.html、.svelte、.astro 的文件中提取工具用法，然后根据需要生成适当的 CSS。默认情况下不包含 .js 和 .ts 文件。

¥By default, UnoCSS will extract the utilities usage from files in your build pipeline with extension .jsx, .tsx, .vue, .md, .html, .svelte, .astro and then generate the appropriate CSS on demand. .js and .ts files are NOT included by default.

要配置它们，你可以更新 uno.config.ts：

¥To configure them, you can update your 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 或 *.ts 文件，请将它们添加到配置中以将所有 js/ts 文件作为扫描目标。

¥You can also add @unocss-include magic comment, per-file basis, anywhere in the file that you want UnoCSS to scan. If you need to scan *.js or *.ts files, add them in the configuration to include all js/ts files as scan targets.

// ./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 来绕过整个文件的扫描和转换。

¥Similarly, you can also add @unocss-ignore to bypass the scanning and transforming for the whole file.

如果你希望 UnoCSS 跳过一段代码而不在任何提取文件中提取，你可以成对使用 @unocss-skip-start @unocss-skip-end。注意必须成对使用才有效。

¥If you want the UnoCSS to skip a block of code without being extracted in any extracting files, you can use @unocss-skip-start @unocss-skip-end in pairs. Note that it must be used in pairs to be effective.

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

从文件系统中提取

¥Extracting from Filesystem

如果你使用的集成无法访问构建工具管道（例如 PostCSS 插件），或者你正在与后端框架集成以使代码不通过管道，则你可以手动指定文件被提取。

¥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

由于 UnoCSS 在构建时工作，这意味着只会生成静态渲染的工具并将其发送到你的应用。可能无法检测或应用在运行时动态使用或从外部资源获取的工具。

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

html

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

由于 UnoCSS 在构建时使用静态提取来工作，因此在编译时它不可能知道工具的所有组合。为此，你可以配置 safelist 选项。

¥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(' ')

总是会生成相应的 CSS：

¥The corresponding CSS will always be generated:

css

.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}`),
]

如果你正在寻求运行时真正的动态生成，你可能需要查看 @unocss/runtime 包。

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

html

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

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

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

html

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

黑名单

¥Blocklist

与 safelist 类似，你还可以配置 blocklist 以排除生成某些工具。这对于排除一些提取误报很有用。与 safelist 不同，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]$/,
]

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

¥This will exclude p-1 and p-2, p-3, p-4 from being generated.

提取 ​

内容来源 ​

从构建工具管道中提取 ​

从文件系统中提取 ​

从内嵌文本中提取 ​

局限性 ​

安全列表 ​

静态列表组合 ​

黑名单 ​

提取

内容来源

从构建工具管道中提取

从文件系统中提取

从内嵌文本中提取

局限性

安全列表

静态列表组合

黑名单