外部ライブラリを SharePoint のクライアント側 Web パーツに追加する

[アーティクル]
03/21/2023

Web パーツに 1 つまたは複数の JavaScript ライブラリを含む必要がある場合があるかもしれません。この資料では、外部ライブラリをバンドルして、ライブラリを共有する方法を説明します。

スクリプトをバンドルする

既定では、Web パーツの Bundler ツールでは、Web パーツモジュールに依存する任意のライブラリが自動的に含まれます。すなわち、ライブラリが Web パーツと同じ JavaScript バンドルファイルに配置されます。複数の Web パーツで使用されていない小規模なライブラリにとってはさらに便利です。

例

ライブラリ検証パッケージを検証する文字列を Web パーツに加えます。
NPM から検証ソフトパッケージをダウンロードします。
```
npm install validator --save
```
注:

TypeScript を使用しているため、追加するパッケージの型宣言が必要になる可能性があります。 TypeScript は JavaScript のスーパーセットに過ぎないため、コードを記述する場合に便利です。 TypeScript のすべてのコードは、コンパイルするとき JavaScript コードに変換されます。 NPM を使用して型宣言をインストールできます。例: npm install @types/{package} --save-dev
validator.d.ts と呼ばれる Web パーツのフォルダーにファイルを作成し、次を追加します。
```
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 パーツは同じライブラリをインポート、または共有しなければならない可能性があります。その場合、ライブラリをバンドルするのではなく、別の JavaScrip ファイルに加え、パフォーマンスとキャッシングを向上させます。これは、特に大きなライブラリの場合当てはまります。

例

この例では、別のバンドルに含まれる印がついたパッケージ、つまりマークダウンコンパイラを共有します。

NPM から印がついたパッケージをダウンロードします。
```
npm install marked --save
```
プロジェクトに型宣言パッケージをインストールします。
```
npm install @types/marked --save-dev
```
config/config.json を編集し、externalsマップに項目を追加します。これは、Bundler ツールにこれを別のファイルに配置するよう示しています。これにより、Bundler ツールはこのライブラリをバンドルできません。
```
"marked": "node_modules/marked/marked.min.js"
```
これでライブラリ用のパッケージと型宣言が追加されたので、ステートメントを追加して 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 を読み込みます。フィールドに項目を追加します。
```
"jquery": "https://code.jquery.com/jquery-3.1.0.min.js"
```
Web パーツ内の JQuery をインポートします。
```
import * as $ from 'jquery';
```
Web パーツ内の jQuery を使用します。
```
alert( $('#foo').val() );
```

非 AMD モジュールの読み込み

いくつかのスクリプトは、グローバルな名前空間にライブラリを保存する従来の JavaScript のパターンに従います。現在はユニバーサルモジュール定義 (ドメインユーザーマネージャー)、/非同期モジュール定義 (AMD)、や ES6 モジュールが推奨されるため、このパターンは推奨されなくなりました。ただし、Web パーツに、このようなライブラリをロードする必要がある場合があります。

ヒント

読み込もうとしているスクリプトが AMD スクリプトか非 AMD スクリプトかを手動で判断するのは困難です。読み込もうとしているスクリプトが縮小されている場合は特にそうです。

スクリプトが公開されている URL でホストされている場合は、無料の Rencore SharePoint Framework スクリプトチェックツールを使用して、スクリプトの種類を判断できます。さらに、このツールを使用すると、スクリプトを読み込んでいるホストの場所が正しく構成されているかどうかを確認することができます。このツールは、VS Code の拡張機能 Rencore SPFx スクリプトチェックでも利用可能です

非 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 ファイルを更新して、このスクリプトを含めます。外部マップにエントリ を追加します 。
```
{
  "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 に依存) を使用する場合に頻繁に必要になります。

これには 2 つの例があります。

非 AMD モジュールには、非 AMD モジュールの依存関係があります

この例には、2 つの架空のスクリプトが含まれます。これらは、CDN から読み込むこともできますが、src/ フォルダー内にあります。

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'];
  }
};

このクラスの型宣言を追加または作成します。この場合は、両方の JavaScript ファイルの型宣言を含む Contoso.d.ts を作成します。

contoso.d.ts

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

config.json ファイルを更新します。に 2 つのエントリを追加します 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 スクリプトの読み込みと基本的に同じシナリオです。つまり、オプションと globalDependency オプションの両方をglobalName使用します。

重要

次の方法では、SharePoint JSOM が既に読み込まれている従来の SharePoint ページでエラーが発生します。従来のページと最新のページの両方で 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 のクライアント側 Web パーツに追加する

スクリプトをバンドルする

例

例

CDN からのスクリプトの読み込み

例

非 AMD モジュールの読み込み

例

別のライブラリに依存しているライブラリの読み込み

非 AMD モジュールには、非 AMD モジュールの依存関係があります

SharePoint JSOM の読み込み

ローカライズされたリソースの読み込み

関連項目

その他のリソース

次の方法で共有

外部ライブラリを SharePoint のクライアント側 Web パーツに追加する

スクリプトをバンドルする

例

複数の Web パーツ間のライブラリの共有

例

CDN からのスクリプトの読み込み

例

非 AMD モジュールの読み込み

例

別のライブラリに依存しているライブラリの読み込み

非 AMD モジュールには、非 AMD モジュールの依存関係があります

SharePoint JSOM の読み込み

ローカライズされたリソースの読み込み

関連項目

その他のリソース