アプリケーション カスタマイザーでカスタム CSS をロードする

モダン ページでは、クラシック時代によく利用した Web パーツ 内に STYLE タグや SCRIPT タグを記載するようなカスタマイズは行えませんが、同様のカスタマイズを行いたい際には、SharePoint Framework のアプリケーション カスタマイザーを用いることでサイト内のすべてのモダン ページにタグを挿入したりさまざまなスタイルを適用することが可能です。しかし仕様変更時に CSS を手軽に反映させたいためソリューション内に含めたくないと考える方も一定数いるのではないでしょうか。

今回は、アプリケーション カスタマイザーを用いて、外部 CSS をロードする方法についてご紹介します。

【動作イメージ】

アプリケーション カスタマイザー ソリューションの作成

サイト内のすべてのモダン ページに対して、CSS をロードするソリューションを作成します。

1. 任意の場所にフォルダーを作成します。
   
2. 作成したフォルダーを右クリック [その他オプションを表示] – [code で開く] を選択します。
3. Visual Studio Code で [ターミナル] – [新しいターミナル] をクリックします。
   
4. 表示されたターミナルに以下のコマンドを入力し実行します。
   yo @microsoft/sharepoint
5. ソリューション名を確認されます。今回はそのまま Enter キーを押下します。
   
6. どのコンポーネントを作成するのかを確認されます。Extention を選択し Enter キーを押下します。
   
7. 拡張機能 (Extension) の種類を確認されるため、Application Customiser を選択し Enter キーを押下します。
   
8. ソリューションの名前を確認されるため、今回は 任意の名前をつけ Enter キーを押下します。
   ソリューションに必要となる各種パッケージがダウンロードされます。
   
9. しばらくすると以下の画面が表示されソリューションの作成が完了したことが通知されます。
   

プログラム ソースの修正とテスト

① 既定で用意されている不要なコードを削除

手順は loadCSS 部分を自身で付与したソリューション名に置き換えてご確認ください。

1. src\extensions\loadCss\LoadCssApplicationCustomizer.ts を開きます。
2. 上部の各種 import を行っている箇所から以下のコードを削除します。
   import { Dialog } from '@microsoft/sp-dialog';
3. アプリケーション カスタマイザーのプロパティ インターフェースとして用意されている ILoadCssApplicationCustomizerProperties の属性を削除し、次のような内容に変更します。

   export interface ILoadCssApplicationCustomizerProperties {
   }

4. onInit メソッド内の不要なソースを削除し、次のような内容に変更します。

   public onInit(): Promise {
       Log.info(LOG_SOURCE, `Initialized ${strings.Title}`);
       return Promise.resolve();
   }

5. 保存します。

② 外部 CSS をロードするためのコードを追加

1. src\extensions\loadCss\LoadCssApplicationCustomizer.ts を開きます。
2. 上部の import 宣言部に各種ファイルをロードする時に利用する SPComponentLoader クラスをインポートするためのコードを追加します。
   import { SPComponentLoader } from '@microsoft/sp-loader';
3. onInit メソッドを次のように修正します。

   public onInit(): Promise {
     Log.info(LOG_SOURCE, `Initialized ${strings.Title}`);
     SPComponentLoader.loadCss('/sites/0725/SiteAssets/customStyle.css');
     return Promise.resolve();
   }

   ※ 外部 CSS ファイルのパスは、自分が用意する CSS ファイルの保存先としてください。
   ※ CSS をキャッシュさせたくない場合、以下のような工夫もあり。

   SPComponentLoader.loadCss('/sites/0725/SiteAssets/customStyle.css?' + (new Date()).getTime());

4. 上書き保存します。

③ 外部 CSS の作成とドキュメント ライブラリへの配置

ライブラリに配置する CSS の記載はどんな内容になるかは要件によってさまざまですが、テストするためにサンプルを用意しました。

1. 以下の内容を含む CSS ファイルを作成します。

   /* ホームの Web パーツタイトルを赤字にします。*/
   .ControlZone span[role="heading"] {
     color: red;
   }
   
   /* ヘッダー部の背景に画像を指定します */
   #spSiteHeader div[role="region"] {
     background: transparent url(sample.svg) repeat;
   }
   

   ※ sample.svg 部分に任意の画像パスを指定してください。
2. 作成した CSS ファイルをライブラリに保存します。
   

④ ソリューションのテスト

1. テストを行うための設定ファイルを変更するため、config\serve.json を開き、pageUrl を変更します。

   {
     "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
     "port": 4321,
     "https": true,
     "serveConfigurations": {
       "default": {
         "pageUrl": "https://{tenantDomain}/sites/0725",
         "customActions": {
           "49d1c808-bc6f-435e-a5ec-6a4f3edd051e": {
             "location": "ClientSideExtension.ApplicationCustomizer",
             "properties": {
               "testMessage": "Test message"
             }
           }
         }
       },
       "loadCss": {
         "pageUrl": "https://{tenantDomain}/SitePages/myPage.aspx",
         "customActions": {
   

   ※ SPFx v1.17 で追加された {tenantDomain} 機能使っています。
2. ターミナルから以下コマンドを実行します。
   gulp serve
3. しばらくすると、既定のブラウザーが起動しスクリプトを読み込むかどうかの確認ダイアログが表示されますので、ターミナルに reload が2回表示されているまでしっかり待ってから、[デバッグ スクリプトを読み込む] をクリックします。
   
   
4. 作成したアプリケーション カスタマイザーが動作し、作成した CSS が動作している状態でページが読み込まれます。正しく表示されなかった場合は、F5 キーを押下しブラウザーを更新しましょう。
   

まとめ

アプリケーション カスタマイザーなどの SPFx ソリューションでは、動的 CSS も利用でき、デザインに対するニーズにも対応することが可能です。内部に埋め込まずに CSS 部分などを外だししておくことで、 SPFx に対するスキルがない方も変更に対応できるようになります。

今回ご紹介した SPComponentLoader クラスには、CSS をロードするための loadCSS の他に、loadScript というメソッドも用意されています。SharePoint の HTML 要素に対する変更を行うような Script を作成することは製品のアップデートにより動作しなくなる可能性があることは当然考慮の上、利用しなければいけませんが、アプリケーション カスタマイザーで追加した HTML に対応させる CSS や Script は外だししてメンテナンスが柔軟にできるようにしておきたいですね。