配置

Purgecss 提供了一系列参数满足你自定义其行为的需求。自定义参数可以提高 Purgecss 的性能和效率。以下参数可以用在你的配置文件中。

配置文件

配置文件时一个普通的 JavaScript 文件。默认情况下，JavaScript API 将自动查找命名为 purgecss.config.js 的文件。

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

然后 PurgeCSS 就可以使用此配置文件了：

const purgecss = await new PurgeCSS().purge()
// or use the path to the file as the only parameter
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

你可以使用文件名或 globs 数组指定 Purgecss 需要分析的内容。文件类型可以是 HTML、Pug、Blade 等。

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

Purgecss 还可以处理原始内容。为此，需要你传递一个 raw 属性的对象，而不是文件名。为了让自定义提取器能正确工作，除了 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 参数类似，你可以使用文件名数组或 globs 指定 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']
    }
  ]
})

关于提取器（extractors）的更多信息请参考这里.

fontFace (default: false)

如果 css 代码中有任何未使用的 @font-face ，可以通过将 fontFace 参数设置为 true 来删除这些规则。

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

keyframes (default: false)

如果使用的时 CSS 动画库，例如 animate.css，你可以通过将 keyframes 参数设置为 true 来删除未使用的 keyframes。

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

variables (default: false)

如果您使用的是自定义属性（CSS 变量）或使用此项技术的软件库（例如 Bootstrap），则可以通过将 variables 参数设置为 true 来删除未使用的 CSS 变量。

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

rejected (default: false)

有时更实际的做法是浏览被删除内容的列表，看看是否有明显的错误。如果您想这样做，请开启 rejected 参数。

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

rejectedCss (default: false)

If you would like to keep the discarded CSS you can do so by using the rejectedCss option.

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.deep 参数设置正则表达式，从而保留选择器所对应的元素以及其子元素。

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

在此示例中，类似 .bg-red .child-of-bg 的选择器将被保留在最终的 CSS 中，即便 child-of-bg 并未被实际被使用到。

safelist.greedy

最后，如果选择器的任何部分能够匹配 safelist.greedy 参数所设置的正则表达式，则整个选择器将被保留。

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

在此示例中，即便并未实际使用到 button 和 nonexistent-class，类似 button.bg-red.nonexistent-class 的选择器也将在最终的 CSS 中得已保留。

blocklist

blocklist 参数将阻止 CSS 选择器出现在最终输出的 CSS 中，即使 PurgeCSS 识别到这些选择器实际被使用了。

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

即便 nav-links 和 usedClass 正在被使用并且被提取器找到了，它们也会被删除。

skippedContentGlobs

如果你为 content 参数设置的值是 glob，则可以使用此参数排除某些文件或文件夹，使其不被扫描。此参数接收一个 glob 数组，该数组所匹配的文件都不会被扫描。（注意：如果为 content 设置的值不是 glob，则此参数无效。）

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

如上设置时，PurgeCSS 将不会扫描 "node_modules" 和 "components" 目录下的任何内容。

dynamicAttributes

此参数用于添加自定义的 CSS 属性选择器，例如 "aria-selected"、"data-selected" 等等。

dynamicAttributes: ["aria-selected"]

配置

配置文件​

参数​

配置文件

参数