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了：

本篇就介紹到這裡。