配置

PurgeCSS 提供了一系列选项，允许你自定义其行为。自定义可以提高 PurgeCSS 的性能和效率。你可以创建一个包含以下选项的配置文件。

配置文件

配置文件是一个简单的 JavaScript 文件。默认情况下，JavaScript API 将查找 purgecss.config.js。

module.exports = {
  content: ['index.html'],
  css: ['style.css']
}

然后你可以使用配置文件：

const purgecss = await new PurgeCSS().purge()
// 或使用文件路径作为唯一参数
const purgecss = await new PurgeCSS().purge('./purgecss.config.js')

选项

选项由以下类型定义：

interface UserDefinedOptions {
  content: Array<string | RawContent>;
  css: Array<string | RawCSS>;
  defaultExtractor?: ExtractorFunction;
  extractors?: Array<Extractors>;
  fontFace?: boolean;
  keyframes?: boolean;
  output?: string;
  rejected?: boolean;
  rejectedCss?: boolean;
  stdin?: boolean;
  stdout?: boolean;
  variables?: boolean;
  safelist?: UserDefinedSafelist;
  blocklist?: StringRegExpArray;
}

interface RawContent {
  extension: string
  raw: string
}

interface RawCSS {
  raw: string
}

type StringRegExpArray = Array<RegExp | string>;

type ComplexSafelist = {
  standard?: StringRegExpArray;
  deep?: RegExp[];
  greedy?: RegExp[];
  variables?: StringRegExpArray;
  keyframes?: StringRegExpArray;
};

type UserDefinedSafelist = StringRegExpArray | ComplexSafelist;
  • content

你可以使用文件名或通配符数组指定 PurgeCSS 应分析的内容。文件可以是 HTML、Pug、Blade 等。

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css']
})

PurgeCSS 还支持原始内容。要这样做，你需要传递一个带有 raw 属性的对象，而不是文件名。要正确使用自定义提取器，你需要同时传递 extension 属性。

await new PurgeCSS().purge({
  content: [
    {
      raw: '<html><body><div class="app"></div></body></html>',
      extension: 'html'
    },
    '**/*.js',
    '**/*.html',
    '**/*.vue'
  ],
  css: [
    {
      raw: 'body { margin: 0 }'
    },
    'css/app.css'
  ]
})
  • css

与 content 类似，你可以使用文件名或通配符数组指定 PurgeCSS 应处理的 CSS。

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css']
})

PurgeCSS 还支持原始 CSS。要这样做，你需要传递一个带有 raw 属性的对象，而不是文件名。

await new PurgeCSS().purge({
  content: [
    {
      raw: '<html><body><div class="app"></div></body></html>',
      extension: 'html'
    },
    '**/*.js',
    '**/*.html',
    '**/*.vue'
  ],
  css: [
    {
      raw: 'body { margin: 0 }'
    }
  ]
})
  • defaultExtractor

PurgeCSS 可以根据你的需求进行调整。如果你注意到很多未使用的 CSS 没有被删除，你可能需要使用自定义提取器。提取器可以基于文件扩展名使用。如果你希望对所有类型的文件使用相同的提取器，请在 defaultExtractor 中指定。

await new PurgeCSS().purge({
  // ...
  defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || []
})
  • extractors

PurgeCSS 可以根据你的需求进行调整。如果你注意到很多未使用的 CSS 没有被删除，你可能需要使用自定义提取器。你可以找到可用提取器的列表，它们可以提供更好的准确性和优化，但它们的行为将是特定的。这可能会使事情难以理解。

考虑将提取器视为可能不是必要的高级优化技术。

import purgeFromHTML from 'purge-from-html'

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css'],
  extractors: [
    {
      extractor: purgeFromHTML,
      extensions: ['html']
    },
    {
      extractor: content => content.match(/[\w-/:]+(?<!:)/g) || [],
      extensions: ['vue', 'js']
    }
  ]
})

你可以在这里了解更多关于提取器的信息。

  • fontFace (默认值：false)

如果 CSS 中有任何未使用的 @font-face 规则，可以通过将 fontFace 选项设置为 true 来删除它们。

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css'],
  fontFace: true
})
  • keyframes (默认值：false)

如果你使用 CSS 动画库（如 animate.css），可以通过将 keyframes 选项设置为 true 来删除未使用的关键帧。

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css'],
  keyframes: true
})
  • variables (默认值：false)

如果你使用自定义属性（CSS 变量），或使用它们的库（如 Bootstrap），可以通过将 variables 选项设置为 true 来删除未使用的 CSS 变量。

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css'],
  variables: true
})
  • rejected (默认值：false)

有时扫描已删除列表以查看是否有明显错误的地方会更实用。如果你想这样做，请使用 rejected 选项。

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css'],
  rejected: true
})
  • rejectedCss (默认值：false)

如果你想保留被丢弃的 CSS，可以使用 rejectedCss 选项。

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css'],
  rejectedCss: true
})
  • safelist

你可以指示哪些选择器可以保留在最终的 CSS 中。这可以通过选项 safelist 来完成。

有两种形式可用：

safelist: ['random', 'yep', 'button', /^nav-/]

在形式中，safelist 是一个数组，可以接受字符串或正则表达式。

复杂形式是：

safelist: {
    standard: ['random', 'yep', 'button', /^nav-/],
    deep: [],
    greedy: [],
    keyframes: [],
    variables: []
}

例如：

const purgecss = await new PurgeCSS().purge({
  content: [],
  css: [],
  safelist: ['random', 'yep', 'button']
})

在这个例子中，选择器 .random、#yep、button 将保留在最终的 CSS 中。

const purgecss = await new PurgeCSS().purge({
  content: [],
  css: [],
  safelist: [/red$/]
})

在这个例子中，选择器以 red 结尾的，如 .bg-red 将保留在最终的 CSS 中。

  • safelist.deep

你可以 safelist 选择器及其子选择器基于正则表达式与 safelist.deep。

const purgecss = await new PurgeCSS().purge({
  content: [],
  css: [],
  safelist: {
    deep: [/red$/]
  }
})

在这个例子中，选择器如 .bg-red .child-of-bg 将保留在最终的 CSS 中，即使 child-of-bg 未找到。

  • safelist.greedy

最后，你可以 safelist 整个选择器，如果任何部分选择器匹配正则表达式与 safelist.greedy。

const purgecss = await new PurgeCSS().purge({
  content: [],
  css: [],
  safelist: {
    greedy: [/red$/]
  }
})

在这个例子中，选择器如 button.bg-red.nonexistent-class 将保留在最终的 CSS 中，即使 button 和 nonexistent-class 未找到。

  • blocklist

Blocklist 将阻止 CSS 选择器出现在最终输出 CSS 中。选择器将由 PurgeCSS 删除，即使它们被视为已使用。

blocklist: ['usedClass', /^nav-/]

即使 nav-links 和 usedClass 由提取器找到，它们也将被删除。

  • skippedContentGlobs

如果你提供 globs 用于 content 参数，你可以使用此选项来排除应扫描的某些文件或文件夹。传递一个匹配项应排除的 globs 数组。（注意：如果 content 不是 globs，此选项无效。）

skippedContentGlobs: ['node_modules/**', 'components/**']

这里，PurgeCSS 不会扫描 "node_modules" 和 "components" 文件夹中的任何内容。

  • dynamicAttributes

选项以添加自定义 CSS 属性选择器，如 "aria-selected", "data-selected", ...etc.

dynamicAttributes: ["aria-selected"]