外部ライブラリを SharePoint のクライアント側 Web パーツに追加するAdd an external library to your SharePoint client-side web part

Web パーツに 1 つまたは複数の JavaScript ライブラリを含む必要がある場合があるかもしれません。この資料では、外部ライブラリをバンドルして、ライブラリを共有する方法を説明します。You might want to include one or more JavaScript libraries in your web part. This article shows you how to bundle an external library and share libraries.

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

既定では、Web パーツの Bundler ツールでは、Web パーツ モジュールに依存する任意のライブラリが自動的に含まれます。By default, the web part bundler automatically includes any library that is a dependency of the web part module. すなわち、ライブラリが Web パーツと同じ JavaScript バンドル ファイルに配置されます。This means that the library is deployed in the same JavaScript bundle file as your web part. 複数の Web パーツで使用されていない小規模なライブラリにとってはさらに便利です。This is more useful for smaller libraries that are not used in multiple web parts.

Example

  1. ライブラリ検証パッケージを検証する文字列を Web パーツに加えます。Include the string validating library validator package into a web part.

  2. npm から検証ソフト パッケージをダウンロードします。Download the validator package from npm:

    npm install validator --save
    

    注意

    TypeScript を使用しているため、追加するパッケージには typings が必要です。TypeScript は JavaScript のスーパーセットなので、コードを記述する際にこれが不可欠になります。TypeScript のすべてのコードは、コンパイル時に JavaScript コードに変換されます。npm を使用すると、typings を検索して見つけることができます。例: npm install @types/{package} --saveBecause you're using TypeScript, you need typings for the package you add. This is essential when you are writing code because TypeScript is just a superset of JavaScript. All the TypeScript code is still converted to JavaScript code when you compile. You can search for and find typings by using npm, for example: npm install @types/{package} --save

  3. validator.d.ts と呼ばれる Web パーツのフォルダーにファイルを作成し、次を追加します。Create a file in the your web part's folder called validator.d.ts and add the following:

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

    注意

    typings がないライブラリもあります。Some libraries do not have typings. 検証ソフトのライブラリにはコミュニティが提供した typings のファイルが用意されていますが、このシナリオではファイルは存在しないと仮定します。While the validator library does have a community provided typings file, for this scenario let's assume it does not. この場合、ライブラリ用に独自の typings 定義 .d.ts ファイルを定義する必要がでてきます。Note: Some libraries do not have typings. Validator is one of them. In this case you would want to define your own typings definition .d.ts file for the library. The following code shows an example. 前述のコードは一例です。The following code shows an example token file.

  4. Web パーツのファイルに、typings をインポートします。In your web part file, import the typings:

    import * as validator from 'validator';
    
  5. Web パーツ コードで検証ソフトのライブラリを使用します。Use the validator library in your web part code:

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

複数の Web パーツ間のライブラリの共有Share a library among multiple web parts

クライアント側のソリューションには、複数の Web パーツが含まれていることがあります。これらの Web パーツは同じライブラリをインポート、または共有しなければならない可能性があります。その場合、ライブラリをバンドルするのではなく、別の JavaScrip ファイルに加え、パフォーマンスとキャッシングを向上させます。これは、特に大きなライブラリの場合当てはまります。Your client-side solution might include multiple web parts. These web parts might need to import or share the same library. In such cases, instead of bundling the library, you should include it in a separate JavaScript file to improve performance and caching. This is especially true of larger libraries.

Example

この例では、別のバンドルに含まれる印がついたパッケージ、つまりマークダウン コンパイラを共有します。In this example, you will share the marked package - a Markdown compiler - in a separate bundle.

  1. npm から印がついたパッケージをダウンロードします。Download the marked package from npm:

    npm install marked --save
    
  2. typings をダウンロードします。Download the typings:

    npm install @types/marked --save
    
  3. config/config.json を編集し、外部マップに項目を追加します。Edit the config/config.json, and add an entry to the externals map. これは、Bundler ツールにこれを別のファイルに配置するよう示しています。This is what tells the bundler to put this in a separate file. これにより、Bundler ツールはこのライブラリをバンドルできません。This prevents the bundler from bundling this library:

    "marked": "node_modules/marked/marked.min.js"
    
  4. これでライブラリ用のパッケージと typings が追加されたので、ステートメントを追加して Web パーツに marked ライブラリをインポートします。Add the statement to import the marked library in your web part now that we have added the package and typings for the library:

    import * as marked from 'marked';
    
  5. Web パーツでライブラリを使用します。Use the library in your web part:

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

CDN からのスクリプトの読み込みLoading a script from a CDN

npm パッケージからライブラリを読み込むのではなく、コンテンツ配信ネットワーク (CDN) からスクリプトを読み込むことをお勧めします。Instead of loading the library from an npm package, you might want to load a script from a Content Delivery Network (CDN). これを行うには、config.json ファイルを編集して CDN URL からライブラリを読み込みます。Instead of loading the library from a npm package, you might want to load a script from a CDN. To do so, edit the config.json file to load the library from its CDN URL.

Example

この例では、CDN から jQuery を読み込みます。npm パッケージをインストールする必要はありません。ただし、typings はインストールする必要があります。In this example, you will load jQuery from CDN. You don't need to install the npm package. However, you still need to install the typings.

  1. JQuery の typings をインストールします。Install the typings for jQuery:

    npm install --save @types/jquery
    
  2. config フォルダーの config.json を更新して、CDN から jQuery を読み込みます。externals フィールドに項目を追加します。Update the config.json in the config folder to load jQuery from CDN. Add an entry to the externals field:

    "jquery": "https://code.jquery.com/jquery-3.1.0.min.js"
    
  3. Web パーツ内の JQuery をインポートします。Import jQuery in your web part:

    import * as $ from 'jquery';
    
  4. Web パーツ内の jQuery を使用します。Use jQuery in your web part:

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

非 AMD モジュールの読み込みLoading a non-AMD module

いくつかのスクリプトは、グローバルな名前空間にライブラリを保存する従来の JavaScript のパターンに従います。現在はユニバーサル モジュール定義 (ドメイン ユーザー マネージャー)、 / 非同期モジュール定義 (AMD)、や ES6 モジュール が推奨されるため、このパターンは推奨されなくなりました。ただし、Web パーツに、このようなライブラリをロードする必要がある場合があります。Some scripts follow the legacy JavaScript pattern of storing the library on the global namespace. This pattern is now deprecated in favor of Universal Module Definitions (UMD) / Asynchronous Module Definitions (AMD) or ES6 modules. However, you might need to load such libraries in your web part.

ヒント

読み込もうとしているスクリプトが AMD スクリプトか非 AMD スクリプトかを手動で判断するのは困難です。It's difficult to determine manually whether the script that you're trying to load is an AMD or a non-AMD script. 読み込もうとしているスクリプトが縮小されている場合は特にそうです。This is especially the case if the script that you're trying to load is minified. スクリプトが公開されている URL でホストされている場合は、無料の Rencore SharePoint Framework スクリプト チェック ツールを使用して、スクリプトの種類を判断できます。If your script is hosted on a publicly accessible URL, you can use the free Rencore SharePoint Framework Script Check tool to determine the type of script for you. さらに、このツールを使用すると、スクリプトを読み込んでいるホストの場所が正しく構成されているかどうかを確認することができます。Additionally, this tool lets you know whether the hosting location from which you're loading the script is properly configured.

非 AMD モジュールを読み込むには、追加のプロパティを config.json ファイルの項目に追加します。To load a non-AMD module, you add an additional property to the entry in your config.json file.

Example

この例では、Contoso 社の CDN から非 AMD 架空モジュールをロードします。これらの手順は、src/ または node_modules/ ディレクトリ内の非 AMD スクリプトを適用します。In this example, you will load a fictional non-AMD module from Contoso's CDN. These steps apply for any non-AMD script in your src/ or node_modules/ directory.

スクリプトはContoso.js と呼ばれ、https://contoso.com/contoso.js に保存されます。その内容は次のとおりです。The script is called Contoso.js and is stored at https://contoso.com/contoso.js. Its contents are:

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


  1. Web パーツ フォルダーの contoso.d.ts というファイル内のスクリプトの typings を作成します。Create typings for the script in a file called contoso.d.ts in the web part folder.

    declare module "contoso" {
        interface IContoso {
            say(text: string): void;
            sayHello(name: string): void;
        }
        var contoso: IContoso;
        export = contoso;
    }
    
  2. config.json ファイルを更新して、このスクリプトを加えます。外部マップに項目を追加します。Update the config.json file to include this script. Add an entry to the externals map:

    {
        "contoso": {
            "path": "https://contoso.com/contoso.js",
            "globalName": "ContosoJS"
        }
    }
    
  3. Web パーツ コードにインポートを追加します。Add an import to your web part code:

    import contoso from 'contoso';
    
  4. コードには Contoso 社のライブラリを使用します。Use the contoso library in your code:

    contoso.sayHello(username);
    

別のライブラリに依存しているライブラリの読み込みLoading a library that has a dependency on another library

多くのライブラリは、別のライブラリに依存関係があります。Many libraries have dependencies on another library. globalDependencies プロパティを使用して、config.json ファイル内でこのような依存関係を指定することができます。Many libraries have dependencies on another library. You can specify such dependencies in the config.json file using the globalDependencies property.

重要

AMD モジュールの場合はこのフィールドを指定する必要はありません。互いに正しくインポートします。Note that you don't have to specify this field for non-AMD modules; they will properly import each other. However, it is important to note that a non-AMD module have a AMD module as a dependency. ただし、非 AMD モジュールへの依存関係として、AMD モジュールを持つことはできません。However, a non-AMD module cannot have an AMD module as a dependency. 場合によっては、非 AMD スクリプトとして AMD スクリプトを読み込むことが可能です。In some cases, it is possible to load an AMD script as a non-AMD script. これは jQuery (それ自体が AMD スクリプト) と、jQuery プラグイン (ほとんどの場合非 AMD スクリプトとして配布され、jQuery に依存) を使用する場合に頻繁に必要になります。This is often required when working with jQuery, which by itself is an AMD script, and jQuery plug-ins, which most of the time are distributed as non-AMD scripts and which depend on jQuery.

これには 2 つの例があります。There are two examples of this.

非 AMD モジュールには、非 AMD モジュールの依存関係がありますNon-AMD module has a non-AMD module dependency

この例には、2 つの架空のスクリプトが含まれます。これらは、CDN から読み込むこともできますが、src/ フォルダー内にあります。This example involves two fictional scripts. These are in the src/ folder, although they can also be loaded from a CDN.

ContosoUI.jsContosoUI.js

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

ContosoCore.jsContosoCore.js

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


  1. このクラスの typings を追加、または作成します。この場合、JavaScript の両ファイルの typings を含む Contoso.d.ts を作成します。Add or create typings for this class. In this case, you will create Contoso.d.ts, which contains typings for both JavaScript files.

    contoso.d.tscontoso.d.ts

    declare module "contoso" {
        interface IEventList {
            alert(): void;
        }
        interface IContoso {
            getEvents(): string[];
            EventList: IEventList;
        }
        var contoso: IContoso;
        export = contoso;
    }
    
  2. config.json ファイルを更新します。外部参照に 2 項目追加します。Update the config.json file. Add two entries to externals:

    {
        "contoso": {
            "path": "/src/ContosoCore.js",
            "globalName": "Contoso"
        },
        "contoso-ui": {
            "path": "/src/ContosoUI.js",
            "globalName": "Contoso",
            "globalDependencies": ["contoso"]
        }
    }
    
  3. Contoso と ContosoUI のインポートを追加します。Add imports for Contoso and ContosoUI:

    import contoso = require('contoso');
    require('contoso-ui');
    
  4. コード内のライブラリを使用します。Use the libraries in your code:

    contoso.EventList.alert();
    

SharePoint JSOM の読み込みLoad SharePoint JSOM Scripts Using SPComponentLoader

SharePoint JSOM の読み込みは、依存している非 AMD スクリプトの読み込みと基本的に同じシナリオです。つまり、globalNameglobalDependency のオプション両方を使用します。Loading SharePoint JSOM is essentially the same scenario as loading non-AMD scripts that have dependencies. This means using both the globalName and globalDependency options.

重要

次の方法では、SharePoint JSOM が既に読み込まれている従来の SharePoint ページでエラーが発生します。Note that the following approach causes errors in classic SharePoint pages, where SharePoint JSOM is already loaded. 従来のページと最新のページの両方で Web パーツを使用する必要がある場合は、まず SharePoint JSOM が使用できるかどうかを確認し、使用できない場合は SPComponentLoader を使用して動的に読み込みます。Important: Please note, that the following approach will cause error in classic SharePoint pages, where SharePoint JSOM is already loaded. If you require your web part to work with both classic and modern pages then you should first check if SharePoint JSOM is already available and if it isn't, load it dynamically using the SPComponentLoader.


  1. JSOM typings の依存関係である Microsoft Ajax の typings をインストールします。Install typings for Microsoft Ajax which is a dependency for JSOM typings:

    npm install @types/microsoft-ajax --save
    
  2. JSOM の typings をインストールします。Install typings for the JSOM:

    npm install @types/sharepoint --save
    
  3. config.json に項目を追加します。Add entries to the 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" ]
        }
    }
    
  4. Web パーツに、require ステートメントを追加します。In your web part, add the require statements:

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

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

config.json にある localizedResources というマップを使って、ローカライズされたリソースを読み込む方法を示します。You can use a map in config.json called localizedResources to describe how to load localized resources. このマップ内のパスは、lib フォルダーに相対しており、行頭スラッシュ (/) を含めることはできません。There is a map in config.json called localizedResources with which you can describe how to load localized resources. Paths in this map are relative to the lib folder and must not contain a leading slash (/).

この例では、src/strings/ というフォルダーがあります。このフォルダーには、en-us.jsfr-fr.jsde-de.js などの名前を含んだ JavaScript ファイルがいくつかあります。これらの各ファイルは、モジュール ローダーにより読み込み可能でなければいけないため、CommonJS ラッパーを含む必要があります。たとえば、以下は en us.js 内の例です。In this example, you have a folder src/strings/. In this folder are several JavaScript files with names such as en-us.js, fr-fr.js, de-de.js. Because each of these files must be loadable by the module loader, they must contain a CommonJS wrapper. For example, in en-us.js:

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


  1. config.json ファイルを編集します。Edit the config.json file. localizedResources に項目を追加します。Add an entry to localizedResources. {locale} は、ロケール名のプレースホルダー トークンです。{locale} is a placeholder token for the locale name:

    {
        "strings": "strings/{locale}.js"
    }
    
  2. 文字列用の typings を追加します。この場合、MyStrings.d.ts というファイルがあります。Add typings for your strings. In this case, you have a file MyStrings.d.ts:

    declare interface IStrings {
        webpartTitle: string;
        initialPrompt: string;
        exitPrompt: string;
    }
    
    declare module 'mystrings' {
        const strings: IStrings;
        export = strings;
    }
    
  3. プロジェクト内の文字列のインポートを追加します。Add imports for the strings in your project:

    import * as strings from 'mystrings';
    
  4. プロジェクト内の文字列を使用します。Use the strings in your project:

    alert(strings.initialPrompt);
    

関連項目See also