style-loader

将 CSS 注入到 DOM 中。

入门

首先，你需要安装 style-loader

npm install --save-dev style-loader

或

yarn add -D style-loader

或

pnpm add -D style-loader

建议将 style-loader 与 css-loader 结合使用

然后将加载器添加到 webpack 配置中。例如

style.css

body {
  background: green;
}

component.js

import "./style.css";

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
    ],
  },
};

安全警告

此加载器主要用于开发。默认设置不适用于生产环境。有关详细信息，请参阅 推荐的示例配置 和 随机数 部分。

选项

• injectType
• attributes
• insert
• styleTagTransform
• base
• esModule

injectType

类型

type injectType =
  | "styleTag"
  | "singletonStyleTag"
  | "autoStyleTag"
  | "lazyStyleTag"
  | "lazySingletonStyleTag"
  | "lazyAutoStyleTag"
  | "linkTag";

默认值：styleTag

允许设置将样式注入到 DOM 中的方式。

可能的值

styleTag

使用多个 <style></style> 自动将样式注入到 DOM 中。这是默认行为。

component.js

import "./styles.css";

带本地变量的示例（CSS 模块）

component-with-css-modules.js

import styles from "./styles.css";

const divElement = document.createElement("div");
divElement.className = styles["my-class"];

所有本地变量（类名）都存储在导入的对象中。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          // The `injectType`  option can be avoided because it is default behaviour
          { loader: "style-loader", options: { injectType: "styleTag" } },
          "css-loader",
        ],
      },
    ],
  },
};

加载器注入类似这样的样式

<style>
  .foo {
    color: red;
  }
</style>
<style>
  .bar {
    color: blue;
  }
</style>

singletonStyleTag

使用一个 <style></style> 自动将样式注入到 DOM 中。

警告

源映射不起作用。

component.js

import "./styles.css";

component-with-css-modules.js

import styles from "./styles.css";

const divElement = document.createElement("div");
divElement.className = styles["my-class"];

所有本地变量（类名）都存储在导入的对象中。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: { injectType: "singletonStyleTag" },
          },
          "css-loader",
        ],
      },
    ],
  },
};

加载器注入类似这样的样式

<style>
  .foo {
    color: red;
  }
  .bar {
    color: blue;
  }
</style>

autoStyleTag

与 styleTag 的工作方式相同，但如果代码在 IE6-9 中执行，则会启用 singletonStyleTag 模式。

lazyStyleTag

根据需要使用多个 <style></style> 将样式注入到 DOM 中。我们建议遵循 .lazy.css 命名约定来使用惰性样式，而 .css 则用于基本的 style-loader 用法（类似于其他文件类型，即 .lazy.less 和 .less）。当您 lazyStyleTag 值 style-loader 时，会惰性注入样式，使其可以通过 style.use() / style.unuse() 按需使用。

⚠️ 当 unuse 被调用的频率高于 use 时，行为未定义。不要这样做。

component.js

import styles from "./styles.lazy.css";

styles.use();
// For removing styles you can use
// styles.unuse();

component-with-css-modules.js

import styles from "./styles.lazy.css";

styles.use();

const divElement = document.createElement("div");
divElement.className = styles.locals["my-class"];

所有本地（类名）存储在导入对象的 locals 属性中。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        exclude: /\.lazy\.css$/i,
        use: ["style-loader", "css-loader"],
      },
      {
        test: /\.lazy\.css$/i,
        use: [
          { loader: "style-loader", options: { injectType: "lazyStyleTag" } },
          "css-loader",
        ],
      },
    ],
  },
};

加载器注入类似这样的样式

<style>
  .foo {
    color: red;
  }
</style>
<style>
  .bar {
    color: blue;
  }
</style>

lazySingletonStyleTag

按需使用一个 <style></style> 将样式注入 DOM。我们建议为惰性样式遵循 .lazy.css 命名约定，为基本 style-loader 使用 .css（类似于其他文件类型，即 .lazy.less 和 .less）。当您 lazySingletonStyleTag 值时，style-loader 会惰性注入样式，使其可以通过 style.use() / style.unuse() 按需使用。

⚠️ 源映射不起作用。

⚠️ 当 unuse 被调用的频率高于 use 时，行为未定义。不要这样做。

component.js

import styles from "./styles.css";

styles.use();
// For removing styles you can use
// styles.unuse();

component-with-css-modules.js

import styles from "./styles.lazy.css";

styles.use();

const divElement = document.createElement("div");
divElement.className = styles.locals["my-class"];

所有本地（类名）存储在导入对象的 locals 属性中。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        exclude: /\.lazy\.css$/i,
        use: ["style-loader", "css-loader"],
      },
      {
        test: /\.lazy\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: { injectType: "lazySingletonStyleTag" },
          },
          "css-loader",
        ],
      },
    ],
  },
};

加载器生成此

<style>
  .foo {
    color: red;
  }
  .bar {
    color: blue;
  }
</style>

lazyAutoStyleTag

与 lazyStyleTag 的工作方式相同，但如果代码在 IE6-9 中执行，则会启用 lazySingletonStyleTag 模式。

linkTag

使用多个 <link rel="stylesheet" href="path/to/file.css"> 将样式注入 DOM。

ℹ️ 加载器将在运行时通过 JavaScript 动态插入 <link href="path/to/file.css" rel="stylesheet"> 标记。如果您想包含静态 <link href="path/to/file.css" rel="stylesheet">，则应使用 MiniCssExtractPlugin。

import "./styles.css";
import "./other-styles.css";

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.link\.css$/i,
        use: [
          { loader: "style-loader", options: { injectType: "linkTag" } },
          { loader: "file-loader" },
        ],
      },
    ],
  },
};

加载器生成此

<link rel="stylesheet" href="path/to/style.css" />
<link rel="stylesheet" href="path/to/other-styles.css" />

attributes

类型

type attributes = HTMLAttributes;

默认值：{}

如果已定义，style-loader 将在其值上附加给定属性，在 <style> / <link> 元素上。

component.js

import style from "./file.css";

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader", options: { attributes: { id: "id" } } },
          { loader: "css-loader" },
        ],
      },
    ],
  },
};

<style id="id"></style>

insert

类型

type insert =
  | string
  | ((htmlElement: HTMLElement, options: Record<string, any>) => void);

默认值：head

默认情况下，style-loader 将 <style>/<link> 元素追加到样式目标的末尾，即页面的 <head> 标记，除非由 insert 指定。这将导致加载器创建的 CSS 优先于目标中已存在的 CSS。如果您认为标准行为不适合您，可以使用其他值，但我们不建议这样做。如果您以 iframe 为目标，请确保您有足够的访问权限，样式将被注入到内容文档头部。

string

Selector

允许设置自定义 查询选择器，其中样式注入到 DOM 中。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              insert: "body",
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

绝对路径到函数

允许设置到自定义函数的绝对路径，该函数允许覆盖默认行为并在任意位置插入样式。

警告

不要忘记此代码将在浏览器中使用，并非所有浏览器都支持最新的 ECMA 特性，如 let、const、箭头函数表达式 等。我们建议使用 babel-loader 来支持最新的 ECMA 特性。

警告

不要忘记某些 DOM 方法在较旧的浏览器中可能不可用，我们建议仅使用 DOM core 2 级属性，但这取决于您想要支持哪些浏览器

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              insert: require.resolve("modulePath"),
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

新的 <style>/<link> 元素将插入到 body 标记的底部。

function

允许覆盖默认行为并在任意位置插入样式。

警告

不要忘记此代码将在浏览器中使用，并非所有浏览器都支持最新的 ECMA 特性，如 let、const、箭头函数表达式 等，我们建议仅使用 ECMA 5 特性，但这取决于您想要支持哪些浏览器

警告

不要忘记某些 DOM 方法在较旧的浏览器中可能不可用，我们建议仅使用 DOM core 2 级属性，但这取决于您想要支持哪些浏览器

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              insert: function insertAtTop(element) {
                var parent = document.querySelector("head");
                // eslint-disable-next-line no-underscore-dangle
                var lastInsertedElement =
                  window._lastElementInsertedByStyleLoader;

                if (!lastInsertedElement) {
                  parent.insertBefore(element, parent.firstChild);
                } else if (lastInsertedElement.nextSibling) {
                  parent.insertBefore(element, lastInsertedElement.nextSibling);
                } else {
                  parent.appendChild(element);
                }

                // eslint-disable-next-line no-underscore-dangle
                window._lastElementInsertedByStyleLoader = element;
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

在 head 标记的顶部插入样式。

您可以将任何参数传递给 style.use(options)，此值将传递给 insert 和 styleTagTransform 函数。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              injectType: "lazyStyleTag",
              // Do not forget that this code will be used in the browser and
              // not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc,
              // we recommend use only ECMA 5 features,
              // but it is depends what browsers you want to support
              insert: function insertIntoTarget(element, options) {
                var parent = options.target || document.head;

                parent.appendChild(element);
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

将样式插入到提供的元素或 head 标记中（如果未提供目标）。现在，您可以将样式注入到 Shadow DOM（或任何其他元素）中。

custom-square.css

div {
  width: 50px;
  height: 50px;
  background-color: red;
}

custom-square.js

import customSquareStyles from "./custom-square.css";

class CustomSquare extends HTMLElement {
  constructor() {
    super();

    this.attachShadow({ mode: "open" });

    const divElement = document.createElement("div");

    divElement.textContent = "Text content.";

    this.shadowRoot.appendChild(divElement);

    customSquareStyles.use({ target: this.shadowRoot });

    // You can override injected styles
    const bgPurple = new CSSStyleSheet();
    const width = this.getAttribute("w");
    const height = this.getAttribute("h");

    bgPurple.replace(`div { width: ${width}px; height: ${height}px; }`);

    this.shadowRoot.adoptedStyleSheets = [bgPurple];

    // `divElement` will have `100px` width, `100px` height and `red` background color
  }
}

customElements.define("custom-square", CustomSquare);

export default CustomSquare;

styleTagTransform

类型

type styleTagTransform =
  | string
  | ((
      css: string,
      styleElement: HTMLStyleElement,
      options: Record<string, any>
    ) => void);

默认值：undefined

string

允许设置到自定义函数的绝对路径，该函数允许覆盖默认行为 styleTagTransform。

警告

不要忘记此代码将在浏览器中使用，并非所有浏览器都支持最新的 ECMA 特性，如 let、const、箭头函数表达式 等，我们建议仅使用 ECMA 5 特性，但这取决于您想要支持哪些浏览器

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              injectType: "styleTag",
              styleTagTransform: require.resolve("module-path"),
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

function

当将“样式”标记插入到 DOM 中时，转换标记和 css。

警告

不要忘记此代码将在浏览器中使用，并非所有浏览器都支持最新的 ECMA 特性，如 let、const、箭头函数表达式 等，我们建议仅使用 ECMA 5 特性，但这取决于您想要支持哪些浏览器

警告

不要忘记某些 DOM 方法在较旧的浏览器中可能不可用，我们建议仅使用 DOM core 2 级属性，但这取决于您想要支持哪些浏览器

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              injectType: "styleTag",
              styleTagTransform: function (css, style) {
                // Do something ...
                style.innerHTML = `${css}.modify{}\n`;

                document.head.appendChild(style);
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

base

type base = number;

此设置主要用作 css 冲突 的解决方法，在使用一个或多个 DllPlugin 时。base 允许你防止应用程序的 css（或 DllPlugin2 的 css）覆盖 DllPlugin1 的 css，方法是指定一个 css 模块 ID 基数，该基数大于 DllPlugin1 使用的范围，例如：

webpack.dll1.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
    ],
  },
};

webpack.dll2.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader", options: { base: 1000 } },
          "css-loader",
        ],
      },
    ],
  },
};

webpack.app.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader", options: { base: 2000 } },
          "css-loader",
        ],
      },
    ],
  },
};

esModule

类型

type esModule = boolean;

默认值：true

默认情况下，style-loader 会生成使用 ES 模块语法的 JS 模块。在某些情况下，使用 ES 模块是有益的，例如在 模块串联 和 tree shaking 的情况下。

你可以使用以下方法启用 CommonJS 模块语法

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "style-loader",
        options: {
          esModule: false,
        },
      },
    ],
  },
};

示例

推荐

对于 production 构建，建议从你的包中提取 CSS，以便以后能够并行加载 CSS/JS 资源。这可以通过使用 mini-css-extract-plugin 来实现，因为它创建单独的 css 文件。对于 development 模式（包括 webpack-dev-server），你可以使用 style-loader，因为它使用多个 <style></style> 将 CSS 注入到 DOM 中，并且工作速度更快。

警告

不要同时使用 style-loader 和 mini-css-extract-plugin。

webpack.config.js

const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const devMode = process.env.NODE_ENV !== "production";

module.exports = {
  module: {
    rules: [
      {
        test: /\.(sa|sc|c)ss$/,
        use: [
          devMode ? "style-loader" : MiniCssExtractPlugin.loader,
          "css-loader",
          "postcss-loader",
          "sass-loader",
        ],
      },
    ],
  },
  plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
};

CSS 模块的命名导出

警告

本地名称将转换为 camelCase。

警告

不允许在 css 类名中使用 JavaScript 保留字。

警告

应启用 css-loader 中的 esModule 和 modules.namedExport 选项。

styles.css

.foo-baz {
  color: red;
}
.bar {
  color: blue;
}

index.js

import { fooBaz, bar } from "./styles.css";

console.log(fooBaz, bar);

你可以使用以下方法启用 ES 模块命名导出

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: "style-loader",
          },
          {
            loader: "css-loader",
            options: {
              modules: {
                namedExport: true,
              },
            },
          },
        ],
      },
    ],
  },
};

源映射

当上一个加载器发出源映射时，加载器会自动注入源映射。因此，要生成源映射，请为上一个加载器将 sourceMap 选项设置为 true。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          { loader: "css-loader", options: { sourceMap: true } },
        ],
      },
    ],
  },
};

Nonce

如果你正在使用 内容安全策略 (CSP)，则注入的代码通常会被阻止。解决方法是使用 nonce。但请注意，使用 nonce 会显著降低 CSP 提供的保护。你可以在 规范 中阅读有关安全影响的更多信息。更好的解决方案是在生产中不使用此加载器。

有两种使用 nonce 的方法

• 使用 attributes 选项
• 使用 __webpack_nonce__ 变量

警告

attributes 选项优先于 __webpack_nonce__ 变量

attributes

component.js

import "./style.css";

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              attributes: {
                nonce: "12345678",
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

加载器生成

<style nonce="12345678">
  .foo {
    color: red;
  }
</style>

__webpack_nonce__

create-nonce.js

__webpack_nonce__ = "12345678";

component.js

import "./create-nonce.js";
import "./style.css";

require 的替代示例

component.js

__webpack_nonce__ = "12345678";

require("./style.css");

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
    ],
  },
};

加载器生成

<style nonce="12345678">
  .foo {
    color: red;
  }
</style>

在顶部插入样式

在 head 标记的顶部插入样式。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              insert: function insertAtTop(element) {
                var parent = document.querySelector("head");
                var lastInsertedElement =
                  window._lastElementInsertedByStyleLoader;

                if (!lastInsertedElement) {
                  parent.insertBefore(element, parent.firstChild);
                } else if (lastInsertedElement.nextSibling) {
                  parent.insertBefore(element, lastInsertedElement.nextSibling);
                } else {
                  parent.appendChild(element);
                }

                window._lastElementInsertedByStyleLoader = element;
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

在目标元素之前插入样式

在 #id 元素之前插入样式。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              insert: function insertBeforeAt(element) {
                const parent = document.querySelector("head");
                const target = document.querySelector("#id");

                const lastInsertedElement =
                  window._lastElementInsertedByStyleLoader;

                if (!lastInsertedElement) {
                  parent.insertBefore(element, target);
                } else if (lastInsertedElement.nextSibling) {
                  parent.insertBefore(element, lastInsertedElement.nextSibling);
                } else {
                  parent.appendChild(element);
                }

                window._lastElementInsertedByStyleLoader = element;
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

自定义元素（Shadow DOM）

你可以为 lazyStyleTag 类型定义样式的自定义目标。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "style-loader",
            options: {
              injectType: "lazyStyleTag",
              // Do not forget that this code will be used in the browser and
              // not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc,
              // we recommend use only ECMA 5 features,
              // but it is depends what browsers you want to support
              insert: function insertIntoTarget(element, options) {
                var parent = options.target || document.head;

                parent.appendChild(element);
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};

将样式插入到提供的元素或 head 标记中，如果未提供目标。

custom-square.css

div {
  width: 50px;
  height: 50px;
  background-color: red;
}

custom-square.js

import customSquareStyles from "./custom-square.css";

class CustomSquare extends HTMLElement {
  constructor() {
    super();

    this.attachShadow({ mode: "open" });

    const divElement = document.createElement("div");

    divElement.textContent = "Text content.";

    this.shadowRoot.appendChild(divElement);

    customSquareStyles.use({ target: this.shadowRoot });

    // You can override injected styles
    const bgPurple = new CSSStyleSheet();
    const width = this.getAttribute("w");
    const height = this.getAttribute("h");

    bgPurple.replace(`div { width: ${width}px; height: ${height}px; }`);

    this.shadowRoot.adoptedStyleSheets = [bgPurple];

    // `divElement` will have `100px` width, `100px` height and `red` background color
  }
}

customElements.define("custom-square", CustomSquare);

export default CustomSquare;

贡献

如果你还没有这样做，请花点时间阅读我们的贡献指南。

CONTRIBUTING

许可证

MIT