UnoCSS 中文网

Appearance

提取 ​

UnoCSS 的工作方式是从你的代码库中搜索工具类的使用情况，并按需生成相应的 CSS。我们将这个过程称为 提取。

内容来源 ​

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

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

从构建工具管道中提取 ​

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

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

默认情况下，UnoCSS 将从构建管道中扩展名为 .jsx、.tsx、.vue、.md、.html、.svelte、.astro 的文件中提取工具类使用情况，然后按需生成相应的 CSS。.js 和 .ts 文件 默认不包含在内。

要配置这些内容，你可以更新 uno.config.ts 文件：

uno.config.ts
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 文件作为扫描目标。

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。请注意，必须 成对 使用才有效。

html
<p class="text-xl text-green">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
ts
export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html',
    ],
  },
})

匹配的文件将直接从文件系统中读取，并在开发模式下监视其变化。

从内联文本中提取 ​

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

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

uno.config.ts
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! -->

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

uno.config.ts
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
ts
safelist: [
  ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
]

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

静态列表组合 ​

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

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

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

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

黑名单 ​

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

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

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