SharePoint Framework 向web部件中添加外部库

博客地址：http://blog.csdn.net/FoxDave

在进行开发的时候，你很可能会想要引用一些公开的JavaScript库到你的项目中，本文将会介绍如何打包和共享这些库。

打包脚本

默认情况下，web部件包会自动包含项目所依赖的库。这意味着库会随着你的web部件一起被部署。这对于非公用的规模较小的库来说是比较有益的。

例子

将字符串验证库validator包加入到web部件。从npm下载validator包，输入命令：

npm install validator --save

注意：由于你在使用TypeScript，它是JavaScript的超集，所以在编译的时候它们仍然会转换成JavaScript，你可以通过npm命令搜索并找到类型：npm install @types/{package} --save

在web部件所在文件夹创建一个文件validator.d.ts然后添加如下代码：

declare module "validator" {
    export function isEmail(email: string): boolean;
    export function isAscii(text: string): boolean;
}

注意，一些库是没有类型的，我们假定本文示例中引用的Validator库是没有的（事实上它有），在这种情况下你需要为该库定义你自己的类型定义文件.d.ts，也就是上述代码。

在你的web部件文件中，引用该类型，用如下代码：

import * as validator from 'validator';

然后就可以在你的web部件代码中使用了，例如：

validator.isEmail('someone@example.com');

在多个web部件工程共享库
你的客户端解决方案可能会包含多个web部件。这些web部件可能需要引入或共享相同的库。在这种情况下，应该放弃捆绑库的方式，而是在一个单独的JavaScript文件中包含它来提高性能，尤其对于大型的库来说更是必要的。

例子

在本例中，让我们演示在一个单独的包中共享marked包（一个Markdown编译器）。首先下载marked包：npm install marked --save，然后下载类型：npm install @types/marked --save。

打开config/config.json文件进行编辑，向externals映射添加一条新内容。这将会告诉打包器将它放到一个单独的文件，以避免将它直接打到包中：

"marked": "node_modules/marked/marked.min.js"

在你的web部件中添加引入marked库的声明：

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 @types/jquery

更新config目录中的config.json文件来从CDN加载jQuery，在externals部分添加一条新项：

"jquery": "https://code.jquery.com/jquery-3.1.0.min.js"

在你的web部件中引入jQuery：

import * as $ from 'jquery';

在你的web部件中使用jQuery

alert( $('#foo').val() );

加载SharePoint JSOM
注意下面介绍的方式并不适用于传统的SharePoint页面，因为JSOM已经加载了。如果你需要让你的web部件能在传统和现代页面同时工作，你需要首先检查SharePoint JSOM是否可用并已经加载了。

安装JSOM依赖的Microsoft Ajax类型：

npm install @types/microsoft-ajax --save

安装JSOM的类型：

npm install @types/sharepoint --save

在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/的文件夹，里面有几个JavaScript文件如en-us.js、fr-fr.js、de-de.js。由于每个文件都需要通过模块加载器加载，它们必须包含一个公用的JS包装器。例如在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声明：

import * as strings from 'mystrings';

这样就可以在项目中使用 strings了：

本篇就介绍到这里。