設定

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;

內容

您可以使用檔案名稱或 glob在新視窗中開啟陣列來指定 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，您可以使用檔案名稱或 glob在新視窗中開啟陣列來指定 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 沒有被移除，您可能需要使用自訂的 extractor。Extractor 可以根據副檔名來使用。如果您想要在所有類型的檔案中使用相同的 extractor，請在 defaultExtractor 中指定您的 extractor。

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

extractors

PurgeCSS 可以根據您的需求進行調整。如果您發現很多未使用的 CSS 沒有被移除，您可能需要使用自訂的 extractor。您可以找到可用 extractor 的清單，它們可以提供更好的準確度和最佳化，但它們的行為會因 extractor 而異。這可能會讓事情難以理解。

考慮將 extractor 視為進階最佳化技術，這可能不是必要的。

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']
    }
  ]
})

您可以在此處進一步了解 extractor。

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 來移除未使用的 keyframes。

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.deep 將選擇器及其子項設定為安全清單。

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

在此範例中，即使找不到 child-of-bg，選擇器（例如 .bg-red .child-of-bg）仍會保留在最終的 CSS 中。

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

區塊清單會阻止 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"]

# 設定

# 設定檔

# 選項

設定

設定檔

選項