鍋綿ブログ

C#・SharePoint・SharePoint Framework・Office365を中心に扱うブログです。

SharePoint Framework (SPFx) 開発で分かった私的ベストプラクティスまとめ

SPFx開発を始めて幾星霜。当たり前のものもそうでないものもありますが、個人的に実施している実装方法をベストプラクティス集としてまとめました。これらを反映したサンプルをGitHubにもアップしておりますので併せてご覧ください。

github.com

f:id:micknabewata:20191022101622p:plain

開発したサンプル

 

 

マニフェストファイル関連

srcフォルダ配下の~.manifest.jsonファイルでは、パッケージに含まれる機能(Webパーツなど)に関するIDや名称、プロパティなどが定義されます。

Webパーツ名などはすべて英語で作成し後から日本語に変更

Webパーツ名はページの編集時に、コマンド名はコマンドの利用者に、それぞれ表示されてしまいます。ここは日本語にしておきたいところですが、Yoコマンドでのプロジェクト作成時に日本語を入力してしまうとJavaScriptやTypeScriptのソースファイル名まで日本語になってしまいます。従ってプロジェクト作成時は英語で入力しておき、後からマニフェストファイルを編集してtitleを日本語にすることが必要になります。

アイコンを変えるだけで印象が全然違う

officeFabricIconFontNameプロパティには、Webパーツや拡張コマンドにはOffice UI Fabric ICONで用意されているアイコン名を設定することができます。既定のままにせず、機能をよく表したアイコンに変えておきましょう。

WebパーツにはSPO標準機能のように編集可能なタイトルを実装する

SharePointの標準Webパーツには、ページの編集中にだけ入力可能なタイトル欄があります。これを実装しておくとWebパーツがSharePointサイトに良く馴染むようになります。

実装方法は簡単です。まずマニフェストファイルでプロパティ(GitHubにアップしたソースではtitle)を定義しておきます。このプロパティに値を代入する(例:this.properties.title = "Sample")ことで、代入した値を保存できます。
値はページの編集中(this.displayMode === DisplayMode.Edit)にだけ表示するテキストボックスにユーザーが入力できるように描画処理を記述します。実際のソースコードはSpfxBestPracticeWebPart.tsSpfxBestPractice.tsxを参考にしてください。

スタイルシート関連

共通のscssファイルを作成し各scssファイルにインポートする

後述のmixin定義などモジュール全体に関わる記述をすべてのscssファイルに記述するのは避けたいです。そこで私は共通のscssファイル(GitHubにアップしたソースではTheme.module.scss)を定義し、各scssファイルでimportするようにしています。

メディアクエリを書きやすくするためのmixinを定義する

SharePoint標準Webパーツでも一部行っているように、スタイルシート内にメディアクエリを書きたいシーンが結構あります。閾値の記述が各scssファイルに分散してしまうと嫌なので、変数とmixinを共通のscssファイルに記述するようにしています。

記述方法はTheme.module.scssを参考にしてください。また、mixinの利用方法はSpfxBestPractice.module.scssを参考にしてください。

SharePointサイトのテーマを反映する

ここを意識せずに開発すると、SharePoint標準機能の「外観の変更」を行ったときに見た目がおかしくなる可能性があります。これについては別の記事にまとめましたので参考にしてください。

www.micknabewata.com

TypeScript関連

esnextを利用できるようにする

便利な関数が使えるようになるので個人的にはesnextの利用がお気に入りです。tsconfig.jsonのlibを以下のように指定します。

    "lib": [
      "es5",
      "dom",
      "es2015.collection",
      "dom.iterable",
      "esnext"
    ]

例えばGitHubにアップしたサンプルではdocuments.tsファイル内でテストデータを生成するためにpadStartメソッドを利用していますが、これはesnextで利用可能になるメソッドです。

デバッグ・動作確認関連

ローカルワークベンチとリモートワークベンチの両方を利用可能にしておく

Webパーツ開発を行う際、gulp serveコマンドを実行するとブラウザでワークベンチが起動しますが、ローカルワークベンチではSharePointと接続できないため、テストデータを利用するなどしてデータ取得/更新部分以外を動作確認することになります。これはこれで必要なのですが、最終的にはSharePointと接続することが多いためリモートワークベンチでも動作確認を行えるようにしておくとスムーズです。

これを実現するには、serve.jsonファイルでserveConfigurationsを記述します。最初から記述されているinitialPageは削除してしまって問題ありません。

"serveConfigurations": {
    "default": {
        "pageUrl": "https://localhost:5432/workbench"
    },
    "spo": {
        "pageUrl": "https://contoso.sharepoint.com/_layouts/workbench.aspx"
    }
}

上記の指定を行うと、gulp serve コマンドでローカルワークベンチが起動し、gulp serve --config spo コマンドでリモートワークベンチが起動します。

その他

複数言語対応

事業をグローバルに展開している企業様では、SharePointサイトも複数言語に対応している場合があります。このような場合、Webパーツを言語毎に開発するのではなく、ローカライズ用のファイルを利用することができます。

例えばGitHubにアップロードしたサンプルでは、locフォルダ配下に言語毎のファイルが存在します。ここで定義したオブジェクトをmystrings.d.tsファイルで受け取り、SpfxBestPracticeWebPart.tsファイルでstringsとしてimportして利用しています。

locフォルダのパスはconfig.jsonに記述したlocalizedResourcesによって決まっています。

パッケージ化のコマンド定義

開発したソリューションをSharePointテナントにアップロードするには、以下のコマンドを利用してパッケージ化を行う必要があります。

gulp bundle --ship

gulp package-solution --ship

毎回2つのコマンドを打つのが面倒なので、package.jsonでコマンド定義をしておきましょう。

 "scripts": {
 "build": "gulp bundle",
 "clean": "gulp clean",
 "test": "gulp test",
 "package": "gulp clean && gulp bundle --ship && gulp package-solution --ship"
},

 

以上、参考になれば幸いです。