html-loader

免责声明： html-loader 是由社区成员维护的第三方包，它可能不支持与 webpack 相同的支持、安全策略或许可证，并且它不受 webpack 维护。

将 HTML 导出为字符串。当编译器需要时，HTML 会被最小化。

入门

首先，你需要安装 html-loader

npm install --save-dev html-loader

或

yarn add -D html-loader

或

pnpm add -D html-loader

然后将插件添加到你的 webpack 配置中。例如

file.js

import html from "./file.html";

webpack.config.js

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

选项

来源
预处理器
最小化
esModule

`sources`

类型

type sources =
  | boolean
  | {
      list?: Array<{
        tag?: string;
        attribute?: string;
        type?: string;
        filter?: (
          tag: string,
          attribute: string,
          attributes: string,
          resourcePath: string,
        ) => boolean;
      }>;
      urlFilter?: (
        attribute: string,
        value: string,
        resourcePath: string,
      ) => boolean;
      scriptingEnabled?: boolean;
    };

默认值：true

默认情况下，每个可加载属性（例如 - <img src="image.png"/>）都会被导入（const img = require('./image.png') 或 import img from "./image.png""）。您可能需要在配置中为图像指定加载器（推荐 asset modules）。

支持的标签和属性

audio 标签的 src 属性
embed 标签的 src 属性
img 标签的 src 属性
img 标签的 srcset 属性
input 标签的 src 属性
object 标签的 data 属性
script 标签的 src 属性
script 标签的 href 属性
script 标签的 xlink:href 属性
source 标签的 src 属性
source 标签的 srcset 属性
track 标签的 src 属性
video 标签的 poster 属性
video 标签的 src 属性
image 标签的 xlink:href 属性
image 标签的 href 属性
use 标签的 xlink:href 属性
use 标签的 href 属性
当 rel 属性包含 stylesheet、icon、shortcut icon、mask-icon、apple-touch-icon、apple-touch-icon-precomposed、apple-touch-startup-image、manifest、prefetch、preload 或当 itemprop 属性为 image、logo、screenshot、thumbnailurl、contenturl、downloadurl、duringmedia、embedurl、installurl、layoutimage 时，link 标签的 href 属性
当 rel 属性包含 stylesheet、icon、shortcut icon、mask-icon、apple-touch-icon、apple-touch-icon-precomposed、apple-touch-startup-image、manifest、prefetch、preload 时，link 标签的 imagesrcset 属性
当 name 属性为 msapplication-tileimage、msapplication-square70x70logo、msapplication-square150x150logo、msapplication-wide310x150logo、msapplication-square310x310logo、msapplication-config、twitter:image 或当 property 属性为 og:image、og:image:url、og:image:secure_url、og:audio、og:audio:secure_url、og:video、og:video:secure_url、vk:image 或当 itemprop 属性为 image、logo、screenshot、thumbnailurl、contenturl、downloadurl、duringmedia、embedurl、installurl、layoutimage 时，meta 标签的 content 属性
当 name 属性为 msapplication-task 时，meta 标签的 content 属性中的 icon-uri 值组件

`boolean`

true 值启用所有默认元素和属性的处理，false 值禁用所有属性的处理。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          // Disables attributes processing
          sources: false,
        },
      },
    ],
  },
};

`object`

允许您指定要处理的标签和属性，过滤它们，过滤 URL，并处理以 / 开头的来源。

例如

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          sources: {
            list: [
              // All default supported tags and attributes
              "...",
              {
                tag: "img",
                attribute: "data-src",
                type: "src",
              },
              {
                tag: "img",
                attribute: "data-srcset",
                type: "srcset",
              },
            ],
            urlFilter: (attribute, value, resourcePath) => {
              // The `attribute` argument contains a name of the HTML attribute.
              // The `value` argument contains a value of the HTML attribute.
              // The `resourcePath` argument contains a path to the loaded HTML file.

              if (/example\.pdf$/.test(value)) {
                return false;
              }

              return true;
            },
          },
        },
      },
    ],
  },
};

`list`

类型

type list = Array<{
  tag?: string;
  attribute?: string;
  type?: string;
  filter?: (
    tag: string,
    attribute: string,
    attributes: string,
    resourcePath: string,
  ) => boolean;
}>;

默认：支持的标签和属性。

允许设置要处理的标签和属性以及如何处理，以及过滤其中一些的能力。

使用 ... 语法允许您扩展默认支持的标签和属性。

例如

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          sources: {
            list: [
              // All default supported tags and attributes
              "...",
              {
                tag: "img",
                attribute: "data-src",
                type: "src",
              },
              {
                tag: "img",
                attribute: "data-srcset",
                type: "srcset",
              },
              {
                // Tag name
                tag: "link",
                // Attribute name
                attribute: "href",
                // Type of processing, can be `src` or `scrset`
                type: "src",
                // Allow to filter some attributes
                filter: (tag, attribute, attributes, resourcePath) => {
                  // The `tag` argument contains a name of the HTML tag.
                  // The `attribute` argument contains a name of the HTML attribute.
                  // The `attributes` argument contains all attributes of the tag.
                  // The `resourcePath` argument contains a path to the loaded HTML file.

                  if (/my-html\.html$/.test(resourcePath)) {
                    return false;
                  }

                  if (!/stylesheet/i.test(attributes.rel)) {
                    return false;
                  }

                  if (
                    attributes.type &&
                    attributes.type.trim().toLowerCase() !== "text/css"
                  ) {
                    return false;
                  }

                  return true;
                },
              },
            ],
          },
        },
      },
    ],
  },
};

如果未指定标签名称，它将处理所有标签。

您可以使用自定义过滤器来指定要处理的 HTML 元素。

例如

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          sources: {
            list: [
              {
                // Attribute name
                attribute: "src",
                // Type of processing, can be `src` or `scrset`
                type: "src",
                // Allow to filter some attributes (optional)
                filter: (tag, attribute, attributes, resourcePath) => {
                  // The `tag` argument contains a name of the HTML tag.
                  // The `attribute` argument contains a name of the HTML attribute.
                  // The `attributes` argument contains all attributes of the tag.
                  // The `resourcePath` argument contains a path to the loaded HTML file.

                  // choose all HTML tags except img tag
                  return tag.toLowerCase() !== "img";
                },
              },
            ],
          },
        },
      },
    ],
  },
};

过滤器还可以用于扩展受支持的元素和属性。

例如，过滤器可以帮助处理引用资产的元标签

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          sources: {
            list: [
              {
                tag: "meta",
                attribute: "content",
                type: "src",
                filter: (tag, attribute, attributes, resourcePath) => {
                  if (
                    attributes.value === "og:image" ||
                    attributes.name === "twitter:image"
                  ) {
                    return true;
                  }

                  return false;
                },
              },
            ],
          },
        },
      },
    ],
  },
};

注意
具有 tag 选项的来源优先于没有该选项的来源。

过滤器可用于禁用默认来源。

例如

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          sources: {
            list: [
              "...",
              {
                tag: "img",
                attribute: "src",
                type: "src",
                filter: () => false,
              },
            ],
          },
        },
      },
    ],
  },
};

`urlFilter`

类型

type urlFilter = (
  attribute: string,
  value: string,
  resourcePath: string,
) => boolean;

默认：undefined

允许过滤网址。所有经过过滤的网址都将不会被解析（在代码中按原样保留）。默认情况下，不会处理不可请求的来源（例如 <img src="javascript:void(0)"/>）。

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          sources: {
            urlFilter: (attribute, value, resourcePath) => {
              // The `attribute` argument contains a name of the HTML attribute.
              // The `value` argument contains a value of the HTML attribute.
              // The `resourcePath` argument contains a path to the loaded HTML file.

              if (/example\.pdf$/.test(value)) {
                return false;
              }

              return true;
            },
          },
        },
      },
    ],
  },
};

`scriptingEnabled`

类型

type scriptingEnabled = boolean;

默认值：true

默认情况下，html-loader 中的解析器将 <noscript> 标签内的内容解释为 #text，因此将忽略此标签内的内容处理。

要启用 <noscript> 内部的处理，以便解析器将内容识别为 #AST，请将此参数设置为：false

其他信息：scriptingEnabled

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          sources: {
            // Enables processing inside the <noscript> tag
            scriptingEnabled: false,
          },
        },
      },
    ],
  },
};

`preprocessor`

类型

type preprocessor = (
  content: string | Buffer,
  loaderContext: LoaderContext,
) => HTMLElement;

默认：undefined

允许在处理之前对内容进行预处理。

警告
您应始终返回有效的 HTML

file.hbs

<div>
  <p>{{firstname}} {{lastname}}</p>
  <img src="image.png" alt="alt" />
<div>

`function`

您可以将 preprocessor 选项设置为 function 实例。

webpack.config.js

const Handlebars = require("handlebars");

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/i,
        loader: "html-loader",
        options: {
          preprocessor: (content, loaderContext) => {
            let result;

            try {
              result = Handlebars.compile(content)({
                firstname: "Value",
                lastname: "OtherValue",
              });
            } catch (error) {
              loaderContext.emitError(error);

              return content;
            }

            return result;
          },
        },
      },
    ],
  },
};

您还可以将 preprocessor 选项设置为异步函数实例。

例如

webpack.config.js

const Handlebars = require("handlebars");

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/i,
        loader: "html-loader",
        options: {
          preprocessor: async (content, loaderContext) => {
            let result;

            try {
              result = await Handlebars.compile(content)({
                firstname: "Value",
                lastname: "OtherValue",
              });
            } catch (error) {
              await loaderContext.emitError(error);

              return content;
            }

            return result;
          },
        },
      },
    ],
  },
};

`minimize`

类型

type minimize =
  | boolean
  | {
      caseSensitive?: boolean;
      collapseWhitespace?: boolean;
      conservativeCollapse?: boolean;
      keepClosingSlash?: boolean;
      minifyCSS?: boolean;
      minifyJS?: boolean;
      removeComments?: boolean;
      removeRedundantAttributes?: boolean;
      removeScriptTypeAttributes?: boolean;
      removeStyleLinkTypeAttributes?: boolean;
    };

默认值：生产模式为 true，否则为 false

告诉 html-loader 最小化 HTML。

`boolean`

默认情况下，启用的最小化规则如下

({
  caseSensitive: true,
  collapseWhitespace: true,
  conservativeCollapse: true,
  keepClosingSlash: true,
  minifyCSS: true,
  minifyJS: true,
  removeComments: true,
  removeRedundantAttributes: true,
  removeScriptTypeAttributes: true,
  removeStyleLinkTypeAttributes: true,
});

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          minimize: true,
        },
      },
    ],
  },
};

`object`

webpack.config.js

有关可用选项的更多信息，请参阅 html-minifier-terser 的文档。

可以使用 webpack.conf.js 中的以下选项覆盖默认规则

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          minimize: {
            removeComments: false,
            collapseWhitespace: false,
          },
        },
      },
    ],
  },
};

可以扩展默认规则

webpack.config.js

const { defaultMinimizerOptions } = require("html-loader");

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {
          minimize: {
            ...defaultMinimizerOptions,
            removeComments: false,
            collapseWhitespace: false,
          },
        },
      },
    ],
  },
};

`esModule`

类型

type esModule = boolean;

默认值：true

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

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

webpack.config.js

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

示例

使用 `` 注释禁用 URL 解析

使用  注释，可以禁用对下一个标签的源处理。

<!-- Disabled url handling for the src attribute -->
<!-- webpackIgnore: true -->
<img src="image.png" />

<!-- Disabled url handling for the src and srcset attributes -->
<!-- webpackIgnore: true -->
<img
  srcset="image.png 480w, image.png 768w"
  src="image.png"
  alt="Elva dressed as a fairy"
/>

<!-- Disabled url handling for the content attribute -->
<!-- webpackIgnore: true -->
<meta itemprop="image" content="./image.png" />

<!-- Disabled url handling for the href attribute -->
<!-- webpackIgnore: true -->
<link rel="icon" type="image/png" sizes="192x192" href="./image.png" />

根

使用 resolve.roots 可以指定一个目录列表，其中解析了以“/”开头的服务器相对 URL 的请求。

webpack.config.js

module.exports = {
  context: __dirname,
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader",
        options: {},
      },
      {
        test: /\.jpg$/,
        type: "asset/resource",
      },
    ],
  },
  resolve: {
    roots: [path.resolve(__dirname, "fixtures")],
  },
};

file.html

<img src="/image.jpg" />

// => image.jpg in __dirname/fixtures will be resolved

CDN

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.jpg$/,
        type: "asset/resource",
      },
      {
        test: /\.png$/,
        type: "asset/inline",
      },
    ],
  },
  output: {
    publicPath: "http://cdn.example.com/[fullhash]/",
  },
};

file.html

<img src="image.jpg" data-src="image2x.png" />

index.js

require("html-loader!./file.html");

// => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg" data-src="image2x.png"/>'

require('html-loader?{"sources":{"list":[{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');

// => '<img src="image.jpg" data-src="data:image/png;base64,..." />'

require('html-loader?{"sources":{"list":[{"tag":"img","attribute":"src","type":"src"},{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');

// => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg" data-src="data:image/png;base64,..." />'

处理 `script` 和 `link` 标签

script.file.js

console.log(document);

style.file.css

a {
  color: red;
}

file.html

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Title of the document</title>
    <link rel="stylesheet" type="text/css" href="./style.file.css" />
  </head>
  <body>
    Content of the document......
    <script src="./script.file.js"></script>
  </body>
</html>

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/,
        type: "asset/resource",
        generator: {
          filename: "[name][ext]",
        },
      },
      {
        test: /\.html$/i,
        use: ["html-loader"],
      },
      {
        test: /\.js$/i,
        exclude: /\.file.js$/i,
        loader: "babel-loader",
      },
      {
        test: /\.file.js$/i,
        type: "asset/resource",
      },
      {
        test: /\.css$/i,
        exclude: /\.file.css$/i,
        loader: "css-loader",
      },
      {
        test: /\.file.css$/i,
        type: "asset/resource",
      },
    ],
  },
};

模板

你可以使用任何模板系统。以下是 handlebars 的示例。

file.hbs

<div>
  <p>{{firstname}} {{lastname}}</p>
  <img src="image.png" alt="alt" />
<div>

webpack.config.js

const Handlebars = require("handlebars");

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/i,
        loader: "html-loader",
        options: {
          preprocessor: (content, loaderContext) => {
            let result;

            try {
              result = Handlebars.compile(content)({
                firstname: "Value",
                lastname: "OtherValue",
              });
            } catch (error) {
              loaderContext.emitError(error);

              return content;
            }

            return result;
          },
        },
      },
    ],
  },
};

PostHTML

你可以使用 PostHTML 而无需任何其他加载器。

file.html

<img src="image.jpg" />

webpack.config.js

const posthtml = require("posthtml");
const posthtmlWebp = require("posthtml-webp");

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/i,
        loader: "html-loader",
        options: {
          preprocessor: (content, loaderContext) => {
            let result;

            try {
              result = posthtml().use(plugin).process(content, { sync: true });
            } catch (error) {
              loaderContext.emitError(error);

              return content;
            }

            return result.html;
          },
        },
      },
    ],
  },
};

导出到 HTML 文件

一个非常常见的场景是将 HTML 导出到它们自己的 .html 文件中，以直接提供它们而不是通过 javascript 注入。这可以通过 html-loader 和 asset modules 的组合来实现。

html-loader 将解析 URL、所需图像以及你期望的所有内容。extract 加载器将 javascript 解析回一个正确的 html 文件，确保所需图像并指向正确的路径，而 asset modules 将为你编写 .html 文件。示例

webpack.config.js

module.exports = {
  output: {
    assetModuleFilename: "[name][ext]",
  },
  module: {
    rules: [
      {
        test: /\.html$/,
        type: "asset/resource",
        generator: {
          filename: "[name][ext]",
        },
      },
      {
        test: /\.html$/i,
        use: ["html-loader"],
      },
    ],
  },
};

贡献

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

CONTRIBUTING

许可证

« 上一页

html-loader

入门

选项

sources

boolean

object

list

urlFilter

scriptingEnabled

preprocessor

function

minimize

boolean

object

esModule

示例

使用  注释禁用 URL 解析

根

CDN

处理 script 和 link 标签

模板

PostHTML

导出到 HTML 文件

贡献

许可证

`sources`

`boolean`

`object`

`list`

`urlFilter`

`scriptingEnabled`

`preprocessor`

`function`

`minimize`

`boolean`

`object`

`esModule`

使用 `` 注释禁用 URL 解析

处理 `script` 和 `link` 标签