PurgeCSS中文网

# 配置

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

# 配置文件

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

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

然后 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')
1
2
3

# 参数

参数及参数类型列表：

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;
  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;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
  • content

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

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

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'
  ]
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
  • css

与 content 参数类似，你可以使用文件名数组或globs (opens new window)指定 Purgecss 需要处理的 css。

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

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 }'
    }
  ]
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
  • defaultExtractor

PurgeCSS 可以根据你的需要进行调整。如果你注意到大量未被使用的 css 没有被删除，你可能需要使用自定义提取器了。提取器可以应用于具有某些扩展名的文件。如果你希望对所有类型的文件使用相同的提取器，请通过defaultExtractor 参数指定提取器。

await new PurgeCSS().purge({
  // ...
  defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || []
})
1
2
3
4
  • 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']
    }
  ]
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

关于提取器（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
})
1
2
3
4
5
  • 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
})
1
2
3
4
5
  • variables (default: false)

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

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css'],
  variables: true
})
1
2
3
4
5
  • rejected (default: false)

It can sometimes be more practical to scan through the removed list to see if there's anything obviously wrong. If you want to do it, use the rejected option.

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

await new PurgeCSS().purge({
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
  css: ['css/app.css'],
  rejected: true
})
1
2
3
4
5
  • safelist

You can indicate which selectors are safe to leave in the final CSS. This can be accomplished with the option safelist.

Two forms are available for this option.

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

In this form, safelist is an array that can take a string or a regex.

The complex form is:

safelist: {
    standard: ['random', 'yep', 'button', /^nav-/],
    deep: [],
    greedy: [],
    keyframes: [],
    variables: []
}
1
2
3
4
5
6
7
const purgecss = await new PurgeCSS().purge({
  content: [], // content
  css: [], // css
  safelist: ['random', 'yep', 'button']
})
1
2
3
4
5

上述示例中，CSS 选择器 .random、#yep、button 将被保留在最终的 CSS 代码中。

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

In this example, selectors ending with red such as .bg-red will be left in the final CSS.

  • safelist.deep

You can safelist selectors and their children based on a regular expression with safelist.deep.

const purgecss = await new PurgeCSS().purge({
  content: [], // content
  css: [], // css
  safelist: {
    deep: [/red$/]
  }
})
1
2
3
4
5
6
7

In this example, selectors such as .bg-red .child-of-bg will be left in the final CSS, even if child-of-bg is not found.

  • safelist.greedy

Finally, you can safelist whole selectors if any part of that selector matches a regular expression with safelist.greedy.

const purgecss = await new PurgeCSS().purge({
  content: [], // content
  css: [], // css
  safelist: {
    greedy: [/red$/]
  }
})
1
2
3
4
5
6
7

In this example, selectors such as button.bg-red.nonexistent-class will be left in the final CSS, even if button and nonexistent-class are not found.

  • blocklist

Blocklist will block the CSS selectors from appearing in the final output CSS. The selectors will be removed even when they are seen as used by PurgeCSS.

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

Even if nav-links and usedClass are found by an extractor, they will be removed.

  • skippedContentGlobs

If you provide globs for the content parameter, you can use this option to exclude certain files or folders that would otherwise be scanned. Pass an array of globs matching items that should be excluded. (Note: this option has no effect if content is not globs.)

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

Here, PurgeCSS will not scan anything in the "node_modules" and "components" folders.

  • dynamicAttributes

Option to add custom CSS attribute selectors like "aria-selected", "data-selected", ...etc.

dynamicAttributes: ["aria-selected"]
1

← CLI →