SharePoint Framework の Web パーツでサードパーティ製の CSS スタイルを参照する

2023-03-21

豊富な SharePoint Framework クライアント側 Web パーツをビルドするために、多数のサードパーティ製ライブラリを活用できます。スクリプトだけではなく、こうしたライブラリにスタイルシートなどの追加アセットも含まれることがよくあります。この記事では、サードパーティ製の CSS スタイルを Web パーツに含める 2 つの方法と、それぞれの方法によって、結果として生じる Web パーツバンドルがどのように影響を受けるかを示します。この資料で取り上げる Web パーツ例では、アコーディオンを表示するために jQuery および jQuery UI を使用します。

SharePoint Framework クライアント側 Web パーツによってレンダリングされる jQuery UI アコーディオン

注:

この記事の手順を実行する前に、必ず SharePoint のクライアント側 Web パーツ開発環境を設定しておいてください。

プロジェクトを準備する

新規プロジェクトを作成する

プロジェクト用の新しいフォルダーを作成します。
```
md js-thirdpartycss
```
プロジェクトフォルダーに移動します。
```
cd js-thirdpartycss
```
プロジェクトフォルダーで SharePoint Framework Yeoman ジェネレーターを実行し、新しい SharePoint Framework プロジェクトをスキャホールディングします。
```
yo @microsoft/sharepoint
```
ダイアログボックスが表示されたら、次の値を入力します。
- js-thirdpartycss: ソリューション名
- ファイルの配置場所として Use the current folder と入力する
- Web パーツ構築のための開始点としての JavaScript フレームワークはありません
- jQuery accordion: Web パーツ名
- Shows jQuery accordion: Web パーツの説明
コードエディターでプロジェクトフォルダーを開きます。この記事の手順とスクリーンショットでは Visual Studio Code を使用していますが、お好きなエディターをどれでも使用できます。

テストコンテンツを追加する

コードエディターで、./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts ファイルを開きます。そして、render() メソッドを次のように変更します。

export default class JQueryAccordionWebPart extends BaseClientSideWebPart<IJQueryAccordionWebPartProps> {
  // ...
  public render(): void {
    this.domElement.innerHTML = `
      <div>
        <div class="accordion">
          <h3>Information</h3>
          <div>
            <p>
            The Volcanoes, crags, and caves park is a scenic destination for
            many visitors each year. To ensure everyone has a good
            experience and to preserve the natural beauty, access is
            restricted based on a permit system.
            </p>
            <p>
            Activities include viewing active volcanoes, skiing on mountains,
            walking across lava fields, and caving (spelunking) in caves
            left behind by the lava.
            </p>
          </div>
          <h3>Snow permit</h3>
          <div>
            <p>
            The Northern region has snow in the mountains during winter.
            Purchase a snow permit for access to approved ski areas.
            </p>
          </div>
          <h3>Hiking permit</h3>
          <div>
            <p>
            The entire region has hiking trails for your enjoyment.
            Purchase a hiking permit for access to approved trails.
            </p>
          </div>
          <h3>Volcano access</h3>
          <div>
            <p>
            The volcanic region is beautiful but also dangerous. Each
            area may have restrictions based on wind and volcanic
            conditions. There are three type of permits based on activity.
            </p>
            <ul>
              <li>Volcano drive car pass</li>
              <li>Lava field access permit</li>
              <li>Caving permit</li>
            </ul>
          </div>
        </div>
      </div>`;

      ($('.accordion', this.domElement) as any).accordion();
  }
  // ...
}

プロジェクトをこの時点でビルドすると、$ が定義されていないことを示すエラーが示されます。プロジェクトが、jQuery を最初に読み込むことなく参照するためです。ライブラリを読み込むには 2 つの方法があります。どちらの方法も、コードにおけるスクリプトの使用法には影響を与えません。

方法 1:バンドルにサードパーティ製のライブラリを含める

SharePoint Framework プロジェクトでサードパーティ製ライブラリを参照する最も簡単な方法は、生成されたバンドルにライブラリを含めることです。ライブラリはパッケージとしてインストールされ、プロジェクトで参照されます。プロジェクトをバンドルすると、Webpack がライブラリに対する参照を取得し、生成されたバンドルにライブラリを含めます。

ライブラリをインストールする

JQuery と jQuery UI を次のコマンドを実行してインストールします。
```
npm install jquery jquery-ui --save
```
Web パーツを TypeScript でビルドしているため、以下のコマンドを実行してインストールできる jQuery 用の TypeScript 型宣言も必要です。
```
npm install @types/jquery --save-dev
```

Web パーツでライブラリを参照する

ライブラリのインストール後、次の手順として、プロジェクトでそれらのライブラリを参照します。

コードエディターで、./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts ファイルを開きます。その上部セクションにある最後の import ステートメントのすぐ下に、jQuery と jQuery UI への参照を追加します。
```
import * as $ from 'jquery';
require('../../../node_modules/jquery-ui/ui/widgets/accordion');
```
jQuery パッケージ用の TypeScript 型宣言をインストールしたので、import ステートメントを使用してその型宣言を参照できます。ただし、jQuery UI パッケージは別にビルドされます。構造化されるモジュールの数に関係なく、使用できるすべてのコンポーネントに対する参照が含まれるメインエントリポイントはありません。代わりに、使用する特定のコンポーネントを直接参照します。そのコンポーネントのエントリポイントには、正常に動作する必要のある依存関係へのすべての参照が含まれています。
次のコマンドを実行し、プロジェクトがビルドされていることを確認します。
```
gulp serve
```
キャンバスに Web パーツを追加すると、アコーディオン動作を確認できます。

この時点では jQuery UI スクリプトのみを参照しているため、アコーディオンがスタイル指定されていません。次に、欠落している CSS スタイルシートを追加してアコーディオンをブランド化します。

Web パーツでサードパーティ製 CSS スタイルシートを参照する

プロジェクトにインストールされているパッケージの一部となっているサードパーティ製 CSS スタイルシートへの参照を追加することは、パッケージ自体への参照を追加するのと同じように簡単です。 SharePoint Framework には、Webpack を介して CSS ファイルを読み込むための標準サポートが備わっています。

コードエディターで、./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts ファイルを開きます。最後の require ステートメントのすぐ下に、jQuery UI アコーディオン CSS ファイルへの参照を追加します。
```
require('../../../node_modules/jquery-ui/themes/base/core.css');
require('../../../node_modules/jquery-ui/themes/base/accordion.css');
require('../../../node_modules/jquery-ui/themes/base/theme.css');
```
プロジェクト内のパッケージの一部である CSS ファイルを参照することは、JavaScript ファイルへの参照を追加することに似ています。行う必要があるのは、読み込む CSS ファイルへの相対パスを .css 拡張子を含めて指定することだけです。プロジェクトをバンドルすると、Webpack がこれらの参照を処理し、生成された Web パーツバンドルにファイルを含めます。
次のコマンドを実行し、プロジェクトがビルドされていることを確認します。
```
gulp serve
```

アコーディオンが標準の jQuery UI テーマを使用して正しく表示され、ブランド化されます。

SharePoint Framework クライアント側 Web パーツによってレンダリングされた既定の jQuery UI テーマを使用した jQuery UI アコーディオン

生成された Web パーツバンドルの内容を分析する

サードパーティ製のライブラリとそのリソースを使用する最も簡単な方法は、生成された Web パーツバンドルにそれらを含めることです。この方法の場合、各種ライブラリ間のすべての依存関係を Webpack が自動的に解決し、すべてのスクリプトが正しい順序で読み込まれるようにします。この方法の欠点は、参照されるすべてのリソースが、Web パーツごとに別個に読み込まれることです。そのため、プロジェクト内に複数の Web パーツが存在し、すべてで jQuery UI を使用している場合には、各 Web パーツは独自の jQuery UI コピーを読み込むので、ページの速度が低下します。

生成された Web パーツバンドルのサイズによってライブラリがどのような影響を受けるかを確認するには、プロジェクトのバンドル後、./temp/stats/js-thirdpartycss.stats.html ファイルを Web ブラウザーで開きます。グラフの上にマウスを置くと、たとえば、対象の Web パーツが参照している jQuery UI CSS ファイルが、全体の Web パーツバンドルのサイズの 6% を超えるなどと表示されます。

生成された Web パーツバンドルの部分ごとにサイズが異なることを示す、グラフ内で強調表示されている jQuery UI CSS

グラフの下にある免責事項で言及されているように、サイズは実際の値ではなく、バンドルのデバッグバージョンのサイズを反映しています。バンドルのリリースバージョンでは、もっと小さくなります。とはいえ、Web パーツバンドルを構成している各部を把握し、バンドル内の他の要素に対する相対サイズを知るのに役立ちます。

方法 2:URL からサードパーティ製ライブラリを読み込む

SharePoint Framework 内のサードパーティ製ライブラリを参照する別の方法は、パブリック CDN またはプライベートに管理されているロケーションなどの URL から参照するという方法です。最大の利点は、頻繁に使用するライブラリをパブリックなロケーションから読み込む場合に、ユーザーのコンピューター上に特定のライブラリが既にダウンロードされている可能性があるという点です。その場合には、SharePoint Framework はキャッシュされているライブラリを再利用し、Web パーツが迅速に読み込まれます。

一元管理されている場所からライブラリを読み込むためにパブリック CDN を使用できない場合であっても、パフォーマンスの観点から、これは優れた方法であるといえます。 URL を示すことによって、ユーザーはスクリプトを 1 回だけダウンロードし、ポータル全体で再利用できます。そのため、ページの読み込み速度が大幅に上がり、ユーザーエクスペリエンスがかなり向上します。

パブリック URL からサードパーティ製ライブラリを読み込むときは、ライブラリの使用に関連してリスクがあることに留意してください。特定のスクリプトのホストロケーションを管理していないため、その内容を確認できません。 SharePoint Framework が読み込むスクリプトは現在のユーザーのコンテキストで実行され、そのユーザーが実行可能な事柄を行えます。また、ホストロケーションがオフラインの場合は、Web パーツは動作しません。

ライブラリに型宣言をインストールする

URL からサードパーティ製ライブラリを参照する場合は、プロジェクト内でパッケージとしてインストールする必要はありません。開発中に型セーフチェックを利用する場合、TypeScript型宣言をインストールする必要があります。

この資料で既に取り上げたように空のプロジェクトを作成することから始めた場合には、次のコマンドを実行して、jQuery 用の TypeScript 型宣言をインストールします。

npm install @types/jquery --save-dev

ライブラリの URL を指定する

URL からサードパーティ製ライブラリを読み込むには、プロジェクト内の構成にライブラリが配置されている URL を指定する必要があります。コードエディターで、./config/config.json ファイルを開きます。 externals セクションで、次の JSON を追加します。

{
  //...
  "externals": {
    //...
    "jquery": "https://code.jquery.com/jquery-3.1.1.min.js",
    "jquery-ui": "https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"
    //...
  }
  //...
}

Web パーツで URL からライブラリを参照する

SharePoint Framework が jQuery と jQuery UI を読み込むために使用する URL を指定した後、次の手順としてそれらをプロジェクトで参照します。

コードエディターで、./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts ファイルを開きます。その上部セクションにある最後の import ステートメントのすぐ下に、jQuery と jQuery UI への以下の参照を追加します。
```
import * as $ from 'jquery';
require('jquery-ui');
```
プロジェクト内でパッケージとしてインストールされたライブラリを参照する方法と URL から参照する方法は類似しています。 jQuery には TypeScript 型宣言がインストールされているため、import ステートメントを使用して参照できます。 jQuery UI の場合、ページ上のスクリプトを読み込むだけです。

プロジェクト構成に外部リソースとして jquery と jquery-ui を登録してあるので、これらのライブラリを参照すると、SharePoint Framework は指定した URL を使用して実行時にライブラリを読み込みます。プロジェクトをバンドルすると、これらのリソースは外部としてマークされ、バンドルから除外されます。

覚えておく必要がある 1 つの違いは、前述の方法では jQuery UI パッケージからアコーディオンを読み込むように指定しましたが、今回は、すべての jQuery UI コンポーネントが含まれる CDN から jQuery UI を参照しているという点です。
次のコマンドを実行し、プロジェクトがビルドされていることを確認します。
```
gulp serve
```
キャンバスに Web パーツを追加すると、アコーディオン動作を確認できます。
Web ブラウザーで、開発者ツールを開き、ネットワーク要求が表示されているタブに切り替え、ページを再読み込みします。 jQuery と jQuery UI の両方が CDN から読み込まれることが分かります。

この時点では、jQuery UI スクリプトのみを参照しているため、アコーディオンがスタイル指定されていません。次に、欠落している CSS スタイルシートを追加してアコーディオンをブランド化します。

Web パーツでサードパーティ製 CSS スタイルシートを URL から参照する

URL からサードパーティ製 CSS スタイルシートへの参照を追加する方法は、プロジェクトパッケージからリソースを参照する方法とは異なります。 config.json ファイル内のプロジェクト構成を使用すると外部リソースを指定できますが、適用されるのはスクリプトに対してのみです。 URL から CSS スタイルシートを参照するには、SPComponentLoader を代わりに使用する必要があります。

SPComponentLoader を使用して URL から CSS を読み込む

コードエディターで、./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts ファイルを開きます。ファイルの上部セクションにある最後の import ステートメントの直後に、次のコードを追加します。
```
import { SPComponentLoader } from '@microsoft/sp-loader';
```
同じファイル内で、次のように onInit() メソッドを上書きします。
```
export default class JQueryAccordionWebPart extends BaseClientSideWebPart<IJQueryAccordionWebPartProps> {
  protected onInit(): Promise<void> {
    SPComponentLoader.loadCss('https://code.jquery.com/ui/1.12.1/themes/base/jquery-ui.min.css');
    return super.onInit();
  }

  // ...
}
```
Web パーツがページ上でインスタンス化されると、指定の URL から jQuery UI CSS を読み込みます。この CSS スタイルシートは、統合されて最適化されたバージョンの jQuery UI CSS です。このスタイルシートには、すべてのコンポーネント向けの基本スタイル、テーマ、スタイル設定が含まれています。
次のコマンドを実行し、プロジェクトがビルドされていることを確認します。
```
gulp serve
```

アコーディオンが標準の jQuery UI テーマを使用して正しく表示され、ブランド化されます。

SharePoint Framework クライアント側 Web パーツによってレンダリングされた既定の jQuery UI テーマを使用した jQuery UI アコーディオン

URL からリソースを読み込む、生成された Web パーツバンドルの内容を分析する

プロジェクトをビルドした後、Web ブラウザーで ./temp/stats/js-thirdpartycss.stats.html ファイルを開きます。

バンドル全体のサイズが小さくなったこと (7 KB。jQuery と jQuery UI をバンドルに含めた場合には 300 KB 超)、jQuery と jQuery UI は実行時に読み込まれるため、グラフにはそれらがリストされていないことに注目してください。

次の方法で共有

SharePoint Framework の Web パーツでサード パーティ製の CSS スタイルを参照する

プロジェクトを準備する

新規プロジェクトを作成する

テスト コンテンツを追加する

方法 1:バンドルにサード パーティ製のライブラリを含める

ライブラリをインストールする

Web パーツでライブラリを参照する

Web パーツでサード パーティ製 CSS スタイルシートを参照する

生成された Web パーツ バンドルの内容を分析する

方法 2:URL からサード パーティ製ライブラリを読み込む