Webpack 是 JavaScript 的模块建置工具,运行在 Node.js 上,它可以将零散的 JavaScript 文件用各式工具优化并打包起来,加快网页的加载时间。Webpack 也并不限于用在 JavaScript 上,它除了还能打包网页有用到的静态资源(如 JS、CSS、图片档等)外,也还能透过 HTML 模板来产生 HTML 网页。

本篇文章不会介绍用 Webpack 打包文件的方式,如果您还不熟悉这部份的话,请先阅读这篇文章:

Webpack 的 HTML 网页大致上可以分为两种,一种是传统将 HTML 语法直接写在 HTML 文件内。例如:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title>Title</title>
        <script type="text/javascript" src="./path/to/bundle.min.js"></script>
        <link href="./path/to/bundle.min.css" rel="stylesheet">
    </head>
    <body>
        <main class="container">
            <h1 class="mt-5">欢迎</h1>
            <p class="lead">这是我用Webpack做的第一个网页。</p>
            <p>如果你也有兴趣的话可以浏览<a href="https://magiclen.org/webpack/">这篇文章</a>。</p>
        </main>
    
        <footer class="footer">
            <div class="container">
                <span class="text-muted">没有著作权,欢迎分享</span>
            </div>
        </footer>
    </body>
</html>

这种 HTML 网页可以直接被 Webpack 打包。

一种是将主要的 CSS 语法甚至是 HTML 语法都写进 JavaScript 中,而 HTML 文件内只有撰写如下的内容:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title>Title</title>
        <!-- 可能会有简单的CSS -->
    </head>
    <body>
        <!-- 可能会有读取画面 -->
        <script type="text/javascript" src="./path/to/bundle.min.js"></script>
    </body>
</html>

当网页浏览器打开这个 HTML 网页时,网页浏览器就会下载 JavaScript 文件来运行,接着将 HTML 和 CSS 注入(inject)到 HTML 网页中,此时网页才会显示出真正的内容。本篇文章将会介绍多种不同的 HTML 模板引擎来应用这种方式产生出 HTML 网页。

Handlebars

Handlebars 是个 HTML 模板引擎,被广泛用于 JavaScript 生态圈,由于它兼容于原本的 HTML,而且又多了模板引用机制(partial),因此非常适合拿来切版。

Handlebars 的官方网站:

在这篇文章介绍过的 Webpack 基本用法,这边就不再详细说明了。现在就让我们把 Handlebars 模板引擎加进 Webpack 项目吧!

Handlebars 加载器

为了能够让 Webpack 打包并处理 Handlebars 的模板文件,我们需要使用 handlebars-loader 这个 Handlebars 加载器。可以在终端机运行以下指令来安装:

npm i -D handlebars-loader handlebars

在 webpack.config.cjs 设置档中,于 module 字段的 rules 数组内,加入 Handlebars 加载器的规则。若是要加载扩展名为 .hbs 或 .handlebars 的文件的话,规则如下:

module.exports = {
    ...

    module: {
        rules: [
            ...

            {
                test: /\.(hbs|handlebars)$/i,
                use: "handlebars-loader",
            }

            ...
        ]
    }

    ...
};

加入 html-webpack-plugin 插件

html-webpack-plugin 插件可以帮助我们产生 HTML 文件,或是将现有的 HTML 文件最小化。这个在先前的文章中也有介绍过。

可以在终端机运行以下指令来安装 html-webpack-plugin:

npm i -D html-webpack-plugin

在 webpack.config.cjs 设置档中,将 html-webpack-plugin 的实体加进 plugins 字段的数组中,有几个 HTML 文件就加几个 html-webpack-plugin 的实体。

如下:

const HtmlWebpackPlugin = require("html-webpack-plugin");

module.exports = {
    ...

    plugins: [
        ...

        new HtmlWebpackPlugin({
            template: "./path/to/original-html-file",
            filename: "./path/to/output-html-file",
            minify: {
                collapseBooleanAttributes: true,
                collapseWhitespace: true,
                removeAttributeQuotes: true,
                removeComments: true,
                removeEmptyAttributes: true,
                removeRedundantAttributes: true,
                removeScriptTypeAttributes: true,
                removeStyleLinkTypeAttributes: true,
                minifyCSS: true,
                minifyJS: true,
                sortAttributes: true,
                useShortDoctype: true,
            },
            inject: false,
        })

        ...
    ]

    ...
};

至于 HTML 网页的写法,刚才也已经有提到了,就像是以下这个样子:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title>Title</title>
        <!-- 可能会有简单的CSS -->
    </head>
    <body>
        <!-- 可能会有读取画面 -->
        <script type="text/javascript" src="./path/to/bundle.min.js"></script>
    </body>
</html>

网页浏览器在打开上面这个 HTML 网页后,会去读取并运行 ./path/to/bundle.min.js,而这个 JavaScript 程序内就有我们用 Handlebars 产生出来的 HTML 语法,其会被 JavaScript 程序注入到现有的 HTML 网页中。

HTML 注入

我们必须要自己撰写 HTML 注入的 JavaScript 程序。最基本的方式就是替网页浏览器的 document 加上 DOMContentLoaded 事件,并在此事件的回呼(callback)函数中去创建或搜索要修改的元素,然后修改其拥有的 innerHTML 字段值。

例如要将某个 Handlebars 的模板文件编译出来的 HTML 语法注入到 HTML 的 <body> 中,Webpack 的 JavaScript 进入点可以这样写:

import template from "./path/to/handlebars-file";

document.addEventListener("DOMContentLoaded", () => {
    document.body.innerHTML = template();
});

例如要在 HTML 的 <body> 中添加一个 id 为 main 的 <div>,并且把某个 Handlebars 的模板文件编译出来的 HTML 语法注入到这个 <div> 中,Webpack 的 JavaScript 进入点可以这样写:

import template from "./path/to/handlebars-file";

document.addEventListener("DOMContentLoaded", () => {
    const divMain = document.createElement("div");

    divMain.id = "main";
    divMain.innerHTML = template();

    document.body.appendChild(divMain);
});

Handlebars 的上下文(context)

如果 Handlebars 的模板有挖空格的话,例如:

Hello, {{something}}!

我们可以在 JavaScript 程序中,将 Handlebars 的上下文对象,作为参数传给引用 Handlebars 的模板文件后所得到的函数。如下:

import template from "../views/index.hbs";

document.addEventListener("DOMContentLoaded", () => {
    const context = { something: "world" };

    document.body.innerHTML = template(context);
});

更改模板引用(partial)的目录

如果要使用 Handlebars 的模板引用机制,预设的 partial 模板搜索路径是在使用这个 partial 模板的 Handlebars 模板的同一个目录下。由于许多人会把 partial 模板分开来存放,若要修改 partial 模板的存放目录,可以在 webpack.config.cjs 设置档的 Handlebars 加载器规则中,添加 options 字段,这个字段值是一个对象,该对象的 partialDirs 字段可以用来设置 partial 模板的多个存放目录。

如下:

const path = require("node:path");

module.exports = {
    ...

    module: {
        rules: [
            ...

            {
                test: /\.(hbs|handlebars)$/i,
                use: {
                    loader: "handlebars-loader",
                    options: { partialDirs: [path.join(__dirname, "views", "partials")] },
                },
            }

            ...
        ]
    }

    ...
};

自订 Handlebars 的 Helper

handlebars-loader 提供了 Handlebars 的 Helper 的自动引用机制,并将 Helper 模块化。如果想使用自订的 Helper,可以在 webpack.config.cjs 设置档的 Handlebars 加载器规则中,添加 options 字段,这个字段值是一个对象,该对象的 helperDirs 字段可以用来设置 Helper 模块的多个存放目录。

如下:

const path = require("node:path");

module.exports = {
    ...

    module: {
        rules: [
            ...

            {
                test: /\.(hbs|handlebars)$/i,
                use: {
                    loader: "handlebars-loader",
                    options: { helperDirs: [path.join(__dirname, "views", "helpers")] },
                },
            }

            ...
        ]
    }

    ...
};

只要存在于 Helper 目录中的 JavaScript 模块,都会被自动引用。Helper 模块的实作方式如下:

import Handlebars from "handlebars/dist/handlebars.runtime";

export default function link(text, url) {
    text = Handlebars.escapeExpression(text);
    url = Handlebars.escapeExpression(url);
    
    return new Handlebars.SafeString(`<a href="${url}">${text}</a>`);
}

如果将以上模块存成 link.js,则这个 Helper 的名称为 link。这个 Helper 可以用来将一个文字和一个网址组成拥有超链接的 HTML 文字。

调用方式如下:

My website is {{{link 'MagicLen' 'https://magiclen.org'}}}.

React

React 用的 JSX 是一种将 JavaScript 程序和 HTML 语法结合在一起的模板,非常适合用于大型项目。

React 的官方网站:

我们也可以让 Webpack 直接支持 JSX。不过在这篇文章介绍过的 Webpack 基本用法,这边就不再详细说明了。现在就让我们把 JSX 加进 Webpack 项目吧!

替 Babel 加上 @babel/preset-react 套件

在终端机运行以下指令来安装 @babel/preset-react 套件:

npm i -D @babel/preset-react

修改 webpack.config.cjs 设置档中的 Babel 加载器的规则,如下:

module.exports = {
    ...

    module: {
        rules: [
            ...

            {
                test: /\.jsx?$/i,
                use: {
                    loader: "babel-loader",
                    options: {
                        presets: [
                            "@babel/preset-env",
                            "@babel/preset-react",
                        ],
                    },
                },
            }

            ...
        ]
    }

    ...
};

如此一来就可以直接在 .js 文件中撰写 JSX 了,或者也可以用 .jsx 文件。

安装 React 套件

为了要能够在 JSX 中使用到 React 的模块,我们还需要安装 react 和 react-dom 这两个套件。指令如下:

npm i react react-dom

加入 html-webpack-plugin 插件

html-webpack-plugin 插件的加入方式可以参考文章上面的 Handlebars 部份。

至于 HTML 的话,React 似乎比较习惯弄一个顶层的 <div>(id 通常会叫作 root 或是 app)来操作底下的 DOM,而不是直接去控制 <body>。

所以 HTML 网页可以写成如下这样:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title>Title</title>
    </head>
    <body>
        <div id="root"></div>
        <script type="text/javascript" src="./path/to/bundle.min.js"></script>
    </body>
</html>

JSX 的 Hello World

我们可以直接在 Webpack 的进入点试写一个 JSX 的 Hello World 网页,代码如下:

import React from "react";
import ReactDOM from "react-dom";

ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById("root"));