在 SharePoint 框架工具链中扩展 Webpack

项目
03/21/2023

Webpack 是一个 JavaScript 模块捆绑程序，它采用 JavaScript 文件及其依赖项，并生成一个或多个 JavaScript 文件，以便为不同的方案加载不同的代码段。

框架工具链使用 CommonJS 进行构建。这便于你对模块及其使用位置进行定义。工具链还使用通用的模块加载器 SystemJS 来加载模块。这有助于通过确保每个 Web 部件在其各自的命名空间中执行，确定 Web 部件的范围。

可以向 SharePoint 框架工具链添加的一个常见任务是，使用自定义加载程序和插件扩展 Webpack 配置。

使用 Webpack 加载程序

在许多情况下，可能需要在开发过程中导入和利用非 JavaScript 资源，这通常通过图像或模板实现。 Webpack 加载程序会将资源转换为可供 JavaScript 应用程序使用的内容，或提供 JavaScript 应用程序可以理解的简单引用。

例如，markdown 模板可能会被编译并转换为文本字符串，而图像资源可能会转换为内联 Base64 图像，或者可能被引用为 URL 并复制到 dist目录进行部署。

存在大量有用的加载程序，其中多个已由标准 SharePoint 框架 Webpack 配置使用，如：

html-loader
json-loader
loader-load-themed-styles

使用自定义加载程序扩展框架 Webpack 配置是一个简单的过程，此过程记录在 Webpack 加载程序中。

示例：使用 markdown-loader 包

举一个例子，我们将使用 markdown-loader 包。通过此加载程序，可引用 .md 文件并将其输出为 HTML 字符串。

可以在 samples/js-extend-webpack 下载已完成的示例。

步骤 1 - 安装包

在项目中引用 markdown-loader。

npm i --save markdown-loader

步骤 2 - 配置 Webpack

安装程序包后，配置 SharePoint 框架 Webpack 配置以将 markdown-loader 包含在内。

在 markdown-loader 文档中，介绍了如何扩展 Webpack 配置来包括该加载程序：

{
  module: {
    rules: [
      {
        test: /\.md$/,
        use: [
          {
            loader: 'html-loader'
          },
          {
            loader: 'markdown-loader',
            options: {
              /* options for markdown-loader here */
            }
          }
        ]
      }
    ]
  }
}

让我们看一看此配置正在执行的操作：

Webpack 配置中的 rules 数组定义了一组文件路径测试，以及在找到与测试相匹配的资源时应使用的加载程序。在这种情况下，test 属性检查以 .md 结尾的文件路径。
use 数组描述了按顺序应用于资源的加载程序列表。加载程序按照最后一个最先应用，第一个最后应用的顺序进行应用。在这种情况下，要应用的第一个加载程序是 markdown-loader，要应用的最后一个加载程序是 html-loader。
当指定多个加载程序时，每个加载程序的结果将被传送到下一个程序。

我们将使用此信息在项目中对其进行配置。

若要将此自定义加载程序添加到 SharePoint 框架 Webpack 配置，需要指示生成任务配置 Webpack。在 gulpfile.js 中定义生成任务，此文件位于项目的根目录中。

编辑 gulpfile.js 并在 build.initialize(gulp); 前直接添加以下代码：

build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfiguration) => {
    generatedConfiguration.module.rules.push(
      {
        test: /\.md$/,
        use: [
          {
            loader: 'html-loader'
          },
          {
            loader: 'markdown-loader'
          }
        ]
      }
    );

    return generatedConfiguration;
  }
});

让我们看一下此代码片段正在执行的操作：

ConfigureWebpackTask（实例化为 build.configureWebpack）为我们配置 Webpack。构建 SPFx 项目有大量特殊的配置，因此在此任务中存在一些不常用的逻辑。
ConfigureWebpackTask 采用一个可选的 additionalConfiguration 属性。我们希望将此属性设置为一个函数，该函数采用生成的配置，对其进行修改，然后返回更新的配置。 此函数必须将 Webpack 配置返回到工具链，否则 Webpack 将不能正确配置。
在我们设置为 additionalConfiguration 的函数主体内部，只需将新规则推送到配置中现有的一组规则即可。请注意，此新规则与步骤 2 顶部的配置代码段中的示例相似。

注意

尽管可用此方法彻底替换工具链的默认 Webpack 配置，但为了实现最佳性能和优化，除非文档中另有规定，否则不建议这样做。

步骤 3 - 更新代码

配置加载程序后，更新代码并添加一些文件来测试方案。

创建其中包含部分标记文本的 ./src/my-markdown.md 文件。

#Hello Markdown

*Markdown* is a simple markup format to write content.

You can also format text as **bold** or *italics* or ***bold italics***

生成项目时，Webpack markdown-loader 会将此 markdown 文本转换为 HTML 字符串。

若要在任何源 .ts 文件中使用此 HTML 字符串，请导入后在文件顶部添加以下 require() 行，例如：
```
const markdownString: string = require<string>('./../../../../src/my-markdown.md');
```
默认情况下，Webpack 将在 lib 文件夹中查找文件，但 .md 文件不会默认复制到 lib 文件夹，这意味着需要创建一个很长的相对路径。可以通过定义配置文件控制此设置，指示工具链将 md 文件复制到 lib 文件夹。
创建文件 ./config/copy-static-assets.json，以指示生成系统将其他文件从 src 复制到 lib。默认情况下，此生成任务将复制带有默认工具链 Webpack 配置可识别的扩展名（如 png 和 json）的文件，因此只需指示其也复制 md 文件。
```
{
  "includeExtensions": [
    "md"
  ]
}
```
现在，可以在 require 语句中使用该文件路径，而非相对路径，例如：
```
const markdownString: string = require<string>('./../../readme.md');
```

然后可在代码中引用此字符串，例如：

public render(): void {
  this.domElement.innerHTML = markdownString;
}

步骤 4 - 生成和测试代码

若要生成并测试代码，请在控制台中项目目录的根目录中执行以下命令：

gulp serve

另请参阅

SharePoint 框架概述

通过