跳到主要内容

配置

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#yepbutton 将保留在最终的 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$/]
}
})

在此示例中,即便并未实际使用到 buttonnonexistent-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"]