# 配置

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
  stdin?: boolean
  stdout?: boolean
  variables?: boolean
  whitelist?: string[]
  whitelistPatterns?: Array<RegExp>
  whitelistPatternsChildren?: Array<RegExp>
}

interface RawContent {
  extension: string
  raw: string
}

interface RawCSS {
  raw: string
}
  • 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
})
  • whitelist

你可以将 CSS 选择器加入到白名单中来阻止 Purgecss 将其从 CSS 代码中删除。这可以通过 whitelistwhitelistPatterns 参数实现。

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

上述示例中,CSS 选择器 .random#yepbutton 将被保留在最终的 CSS 代码中。

  • whitelistPatterns

你可以通过 whitelistPatterns 参数来设置基于正则表达式的 CSS 选择器白名单。

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

上述示例中,以 red 结尾的选择器(例如 .bg-red)将被保留在最终的 CSS 代码中。

  • whitelistPatternsChildren

你可以通过 whitelistPatternsChildren 参数来设置基于正则表达式的 CSS 选择器白名单。与 whitelistPatterns 参数相反,他还将 CSS 选择器的子元素加入了白名单。

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

上述示例中,类似 red p.bg-red .child-of-bg 之类的 CSS 选择器将保留在最终的 CSS 代码中。