将外部库添加到 SharePoint 客户端 Web 部件

2022-06-29

Web 部件中必须包含一个或多个 JavaScript 库。本文介绍了如何捆绑外部库和共享库。

捆绑一个脚本

默认情况下，Web 部件捆绑程序会自动包含所有属于 Web 部件模块依赖项的库。这表示库将在同一个 JavaScript 捆绑文件中作为你的 Web 部件进行部署。这对于不会在多个 Web 部件中使用的小型库更有帮助。

示例

将字符串验证库验证程序包添加到 Web 部件。
从 npm 下载验证程序包：
```
npm install validator --save
```
备注

由于使用的是 TypeScript，因此添加的包需要有类型。编写代码时这一步很重要，因为 TypeScript 只是 JavaScript 的超集。编译时，所有 TypeScript 代码都仍会转换为 JavaScript 代码。可以使用 npm 安装类型定义。例如，npm install @types/{package} --save-dev。
在 Web 部件的文件夹中创建一个名为 validator.d.ts 的文件并添加以下内容：
```
declare module "validator" {
    export function isEmail(email: string): boolean;
    export function isAscii(text: string): boolean;
}
```
备注

一些库没有类型定义。虽然验证程序库有社区提供的类型定义，但对于这个场景，我们假设它没有。这种情况下需要为库定义自己的类型定义 .d.ts 文件。之前的代码是一个示例。
在 Web 部件文件中导入类型定义：
```
import * as validator from 'validator';
```
在 Web 部件代码中使用验证程序库：
```
validator.isEmail('someone@example.com');
```

客户端解决方案可能包含多个 Web 部件。这些 Web 部件可能需要导入或共享同一个库。在这种情况下，不能捆绑库，而应该将库添加到单独的 JavaScript 文件中以提升性能并增强缓存功能。此操作尤其适用于大型库。

示例

在此示例中要将 marked 包（一种标记编译器）共享到单独的捆绑包中。

从 NPM 下载 marked 包：
```
npm install marked --save
```
在你的项目中安装类型定义包：
```
npm install @types/marked --save-dev
```
编辑 config/config.json 并向 externals 映射添加项。此操作可以指示捆绑程序将其放入单独的文件中。此操作可以阻止捆绑程序绑定该库：
```
"marked": "node_modules/marked/marked.min.js"
```
目前我们已经添加了库的包和类型定义，可以添加语句将 marked 库导入 Web 部件了：
```
import * as marked from 'marked';
```

在 Web 部件中使用库：

console.log(marked('I am using __markdown__.'));

从 CDN 中加载脚本

如果不从 NPM 包中加载库，则可以从内容交付网络 (CDN) 中加载脚本。若要实现此操作，可以编辑 config.json 文件来通过库的 CDN URL 加载库。

示例

在此示例中要从 CDN 加载 jQuery。无需安装 npm 包。但是仍然需要安装类型定义。

安装 jQuery 的类型定义：
```
npm install --save-dev @types/jquery
```
更新 config 文件夹中的 config.json 以从 CDN 加载 jQuery。向 externals 字段添加项：
```
"jquery": "https://code.jquery.com/jquery-3.1.0.min.js"
```
将 jQuery 导入到 Web 部件：
```
import * as $ from 'jquery';
```
在 Web 部件中使用 jQuery：
```
alert( $('#foo').val() );
```

加载非 AMD 模块

一些脚本遵循旧的 JavaScript 模式将库存储在全局命名空间上。此模式目前已被弃用，现支持使用通用模块定义 (UMD)/异步模块定义 (AMD) 或 ES6 模块但是需要将这些库加载到 Web 部件中。

提示

很难手动确定你尝试加载的脚本是 AMD 脚本还是非 AMD 脚本。如果你尝试加载的是缩小的脚本，则情况尤其如此。

如果你的脚本托管于可公开访问的 URL 中，则可以使用免费的 Rencore SharePoint 框架脚本检查工具为你确定脚本的类型。另外，此工具可以让你知道你从中加载脚本的托管位置是否正确配置。 VS 代码扩展 Rencore SPSp Script Check 中也提供了此工具

若要加载非 AMD 模块，可以向 config.json 文件中的条目添加附加属性。

示例

在此示例中，你将从 Contoso 的 CDN 中加载虚拟的非 AMD 模块。这些步骤适用于 src/ 或 node_modules/ 目录中的所有非 AMD 脚本。

此脚本名称为 Contoso.js 且存储在 https://contoso.com/contoso.js 上。其内容为：

var ContosoJS = {
  say: function(text) { alert(text); },
  sayHello: function(name) { alert('Hello, ' + name + '!'); }
};

在 Web 部件文件夹中名称为 contoso.d.ts 的文件中创建此脚本的键入。

declare module "contoso" {
  interface IContoso {
    say(text: string): void;
    sayHello(name: string): void;
  }
  var contoso: IContoso;
  export = contoso;
}

更新 config.json 文件夹以将该脚本包含在内。向 externals 映射添加项：

{
  "contoso": {
    "path": "https://contoso.com/contoso.js",
    "globalName": "ContosoJS"
  }
}

向 Web 部件代码添加导入项：
```
import contoso from 'contoso';
```
在代码中使用 contoso 库：
```
contoso.sayHello(username);
```

加载对其他库存在依赖关系的库

许多库对其他库存在依赖关系。可以使用 globalDependencies 属性在 config.json 文件中指定此类依赖关系。

重要

请注意，无需为 AMD 模块指定该字段；它们可以正确地相互导入。但是，非 AMD 模块不能将 AMD 模块作为依赖项。某些情况下，可以加载 AMD 脚本作为非 AMD 脚本。当使用 jQuery（它本身是 AMD 脚本）和 jQuery 插件（大多数时候会将其作为非 AMD 脚本交付，具体取决于 jQuery）时，通常需要这样操作。

下面介绍两个相关示例。

非 AMD 模块具有非 AMD 模块依赖项

此示例涉及两个虚拟脚本。它们位于 src/ 文件夹中，但是也可从 CDN 中加载它们。

ContosoUI.js

Contoso.EventList = {
  alert: function() {
    var events = Contoso.getEvents();
    events.forEach( function(event) {
      alert(event);
    });
  }
}

ContosoCore.js

var Contoso = {
  getEvents: function() {
    return ['A', 'B', 'C'];
  }
};

添加或创建此类的键入。在此示例中，你将创建 Contoso.d.ts ，其中会包含两个 JavaScript 文件的类型定义。

contoso.d.ts

declare module "contoso" {
  interface IEventList {
    alert(): void;
  }
  interface IContoso {
    getEvents(): string[];
    EventList: IEventList;
  }
  var contoso: IContoso;
  export = contoso;
}

更新 config.json 文件。向 externals 添加两个项：

{
  "contoso": {
    "path": "/src/ContosoCore.js",
    "globalName": "Contoso"
  },
  "contoso-ui": {
    "path": "/src/ContosoUI.js",
    "globalName": "Contoso",
    "globalDependencies": ["contoso"]
  }
}

添加 Contoso 和 ContosoUI 的导入项：

import contoso = require('contoso');
require('contoso-ui');

在代码中使用库：
```
contoso.EventList.alert();
```

加载 SharePoint JSOM

加载 SharePoint JSOM 与加载具有依赖项的非 AMD 脚本本质上属于同一方案。这表示同时使用 globalName 和 globalDependency 两个选项。

重要

注意，以下方法会导致经典 SharePoint 页面发生错误，因为其中已经加载了 SharePoint JSOM。如果你需要 Web 部件同时使用经典页面和新式页面，如果 SharePoint JSOM 已经可用，应该先进行检查，如果不可用，则通过使用 SPComponentLoader 动态加载。

安装属于 JSOM 类型依赖项的 Microsoft Ajax 的类型定义：
```
npm install @types/microsoft-ajax --save-dev
```

安装 JSOM 的类型定义：

npm install @types/sharepoint --save-dev

向 config.json 添加项：

{
  "sp-init": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/init.js",
    "globalName": "$_global_init"
  },
  "microsoft-ajax": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/MicrosoftAjax.js",
    "globalName": "Sys",
    "globalDependencies": [ "sp-init" ]
  },
  "sp-runtime": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/SP.Runtime.js",
    "globalName": "SP",
    "globalDependencies": [ "microsoft-ajax" ]
  },
  "sharepoint": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/SP.js",
    "globalName": "SP",
    "globalDependencies": [ "sp-runtime" ]
  }
}

在 Web 部件中添加 require 语句：

require('sp-init');
require('microsoft-ajax');
require('sp-runtime');
require('sharepoint');

加载本地化资源

你可以使用 config.json 中一个名为 localizedResources 的映射描述如何加载本地化资源。此映射中的路径与 lib 文件夹相对，其中不能包含前导斜杠 (/)。

在此示例中，你有文件夹 src/strings/。在此文件夹中是一些名称为 en-us.js、fr-fr.js、de-de.js 的 JavaScript 文件。因为这些文件中的每一个都必须可通过模块加载程序加载，因此它们必须包含一个 CommonJS 包装器。例如，在 en-us.js 中：

  define([], function() {
    return {
      "PropertyPaneDescription": "Description",
      "BasicGroupName": "Group Name",
      "DescriptionFieldLabel": "Description Field"
    }
  });

编辑 config.json 文件。向 localizedResources 添加项。 {locale} 是区域名称的占位符标记：
```
{
  "strings": "strings/{locale}.js"
}
```

添加字符串的类型定义。在此示例中你有文件 MyStrings.d.ts：

declare interface IStrings {
  webpartTitle: string;
  initialPrompt: string;
  exitPrompt: string;
}

declare module 'mystrings' {
  const strings: IStrings;
  export = strings;
}

添加项目中字符串的导入项：
```
import * as strings from 'mystrings';
```
在项目中使用字符串：
```
alert(strings.initialPrompt);
```

另请参阅

SharePoint 框架概述

通过