Share via


既存するスクリプト エディター Web パーツのカスタマイズを SharePoint Framework に移行する

SharePoint Framework は、SharePoint カスタマイズを作成するためのモデルです。 スクリプト エディター Web パーツを使用してクライアント側の SharePoint ソリューションを作成してきた場合、SharePoint Framework に移行する利点とは何かと考えるかもしれません。

この記事では、既存のクライアント側カスタマイズを SharePoint Framework へ移行することの利点を強調し、移行を計画する際に考慮する必要のある事柄をいくつか示します。

注:

この記事の情報は、コンテンツ エディター Web パーツとスクリプト エディター Web パーツのどちらを使用して作成されたカスタマイズにも適用されます。 スクリプト エディター Web パーツに言及している場合でも、コンテンツ エディター Web パーツおよびスクリプト エディター Web パーツとして読んでください。

既存のクライアント側カスタマイズを SharePoint Framework に移行する利点

SharePoint Framework は、クライアント側の開発に重点を置いた SharePoint 開発モデルとして一からビルドされてきました。 主に、モダン チーム サイト向けの拡張性機能を提供しますが、SharePoint Framework に基づいてビルドされたカスタマイズは SharePoint クラシック エクスペリエンスでも動作します。 SharePoint Framework を使用してカスタマイズをビルドすることには、現在利用できる他の SharePoint 開発モデルを使用する場合に比べて、より多くの利点があります。

一度ビルドして、すべてのデバイスで再利用する

SharePoint モダン ユーザー エクスペリエンスは、あらゆるデイバスの SharePoint に格納されている情報に対するアクセスをネイティブでサポートするよう設計されています。 さらに、モダン エクスペリエンスは SharePoint モバイル アプリもサポートします。 SharePoint Framework を使用してビルドするソリューションは SharePoint の最新のエクスペリエンスとシームレスに統合し、SharePoint モバイル アプリ内と同様に、多様なデバイスでも使用できます。 SharePoint Framework ソリューションは SharePoint クラシック エクスペリエンスでも動作するため、モダン エクスペリエンスにまだ移行していない組織でも使用できます。

より堅牢で将来も使用可能

開発者は、これまでは、ユーザー インターフェイスに特定の DOM 要素を追加して SharePoint をカスタマイズしてきました。 この方法を使って、標準のユーザー エクスペリエンスを変更したり、エンド ユーザーに追加機能を提供したりすることがありました。 しかし、こうしたソリューションではエラーが発生しやすい状況でした。 SharePoint ページの DOM は拡張可能なサーフェイスではないため、変更の際に、この DOM に依存するソリューションは壊れる可能性がありました。

SharePoint Framework は、標準化された API と拡張性ポイントを開発者に提供します。開発者はそれらを利用して、クライアント側ソリューションをビルドしたり、エンド ユーザーに追加機能を提供したりできます。 開発者は SharePoint Framework を使用して、サポートを受けながら将来も利用できる方法でソリューションをビルドでき、将来の SharePoint ユーザー インターフェイスの変更がソリューションに与えるかもしれない影響を心配する必要がありません。

SharePoint と Office 365 の情報へのアクセスが容易

Microsoft は SharePoint と Office 365 の機能を継続的に強化しています。 組織が両方のプラットフォームをより活用するにつれて、開発者がOffice 365に格納されている情報や分析情報を活用して、豊富なソリューションを構築することがますます重要になっています。 SharePoint Framework が掲げる 1 つの目標は、開発者が各種の SharePoint API と Office 365 API に簡単に接続でできるようにすることです。

ユーザーのニーズに応じてソリューションを構成できる

多くの場合、スクリプト埋め込みによって構築されたクライアント側のソリューションでは、エンド ユーザーがニーズに合わせて簡単に構成する方法が提供されませんでした。 そうしたソリューションを構成する唯一の方法は、特定の目的にためにコードを変更するか、ユーザー インターフェイスをカスタマイズすることでした。

SharePoint Framework クライアント側 Web パーツには、従来のクラシック Web パーツで作業してきたユーザーにとって親しみ深いプロパティ ウィンドウを使用して Web パーツを構成する標準的な方法が備わっています。 クライアント側 Web パーツをビルドする開発者は、Web パーツに再有効化プロパティ ウィンドウ (その場合、Web パーツ プロパティへのそれぞれの変更が Web パーツ本体へ直接反映される) を含める (既定) か、または非再有効化プロパティ ウィンドウ (その場合、Web パーツ プロパティへの変更は明示的に適用する必要がある) にするかを選択できます。

スクリプトなしのサイトで動作する

組織におけるカスタマイズの制御を支援するため、Microsoft は SharePoint Online でスクリプトなしの機能をリリースしました。 テナントまたは特定のサイト コレクションでスクリプトなしのフラグが有効になっていると、スクリプト インジェクションとスクリプト埋め込みに依存するカスタマイズは行えません。

SharePoint Framework のクライアント側 Web パーツは事前承認を受けたアプリ カタログ経由で配置されるため、スクリプトなしのサイトで実行できます。 既定では、モダン チーム サイトではスクリプトなし設定が有効な状態で、サイトにスクリプトを埋め込むことはできません。 これにより、モダン チーム サイトでクライアント側カスタマイズを作成するためにサポートされるのは、SharePoint Framework を使用する方法だけになります。

SharePoint Framework ソリューションとスクリプト エディター Web パーツ カスタマイズの類似点

新しいツールチェーンを使用して新しい開発モデルに基づいて構築されていますが、SharePoint Framework ソリューションは、過去に構築したスクリプト エディター Web パーツのカスタマイズに似ています。 両者は同じ概念を共有しているため、新しい SharePoint Framework に簡単に移行できます。

ページのパーツとして実行される

スクリプト エディター Web パーツに埋め込まれたカスタマイズと同様、SharePoint Framework ソリューションもページのパーツです。 このため、これらのソリューションはページの DOM にアクセスでき、同じページ上の他のコンポーネントと通信できます。 また、開発者はより簡単にソリューションの応答性を向上させて、SharePoint モバイル アプリを含む SharePoint ページを表示できる種々のフォーム ファクターに適合させることができます。

SharePoint アドインとは異なり、SharePoint Framework クライアント側 Web パーツは iframe で分離されていません。 そのため、特定のクライアント側 Web パーツがアクセスできるリソースに関係なく、ページ上の他の要素にアクセスできます。 これは、Bearer アクセス トークンを使用する OAuth 暗黙的フローに依存したり、機密情報を格納するために cookies またはブラウザーを使用したりするソリューションをビルドするときに銘記しておくべき重要な点です。 クライアント側 Web パーツはページのパーツとして実行されるため、対象ページ上の他の要素もすべてのリソースにアクセスできます。

任意のライブラリを使用して Web パーツをビルドする

スクリプト エディター Web パーツを使用してカスタマイズを作成する場合、jQuery や Knockout などのライブラリを使用してカスタマイズを動的にしたり、ユーザー操作への応答を向上させたりできました。 SharePoint Framework クライアント側 Web パーツをビルドする場合、従来と同じ方法を使用して、任意のクライアント側ライブラリによってソリューションを強化できます。 SharePoint Framework によってもたらされるその他の利点として、スクリプトの分離があります。 Web パーツはページのパーツとして実行されますが、そのスクリプトはモジュールとしてパッケージ化されるため、たとえば、同じページ上の異なる Web パーツは別のバージョンの jQuery を相互に衝突することなく利用できます。 この強力な機能により、技術的な移行を必要としたり、機能的に妥協したりすることなく、ビジネス上の価値の配信に重点を置くことが可能になります。

現在のユーザーとして実行される

スクリプト エディター Web パーツを使用してビルドされるカスタマイズの場合、SharePoint と通信が必要になるときには、API を呼び出すだけで済みました。 クライアント側ソリューションは現在のユーザーのコンテキストでブラウザーにおいて実行され、要求と一緒に認証 Cookie を自動的に送信することによって、ソリューションは SharePoint に直接接続できました。 SharePoint アドインを使用する場合と同様に、追加の認証は SharePoint と通信するために必要ありませんでした。 同じメカニズムが SharePoint Framework でビルドされたカスタマイズに当てはまります。現在認証されているユーザーのコンテキストで実行され、SharePoint と通信するための追加の認証手順は不要です。

クライアント側のコードのみを使用する

SharePoint Framework Web パーツ ソリューションとスクリプト エディター Web パーツ ソリューションの両方がブラウザーで実行され、クライアント側の JavaScript コードのみを含めることができます。 クライアント側ソリューションには、SharePoint でのアクセス許可の昇格や、クロスオリジン通信 (CORS) や OAuth 暗黙的フローを使用した認証をサポートしていない外部 API へのアクセスなど、さまざまな制限があります。 このような場合、クライアント側ソリューションはリモート サーバー側 API を利用して必要な操作を行い、結果をクライアントに返すことができます。

SharePoint でソリューションをホストする

スクリプト エディター Web パーツを使用して SharePoint カスタマイズを作成する 1 つの利点は、コードを通常の SharePoint ドキュメント ライブラリでホストできるという点でした。 SharePoint アドインと比較して、必要なインフラストラクチャが少なく、ソリューションのホスティングが簡単でした。 また、組織は SharePoint アクセス許可を使用してソリューション ファイルへのアクセスを制御できました。

CDN における SharePoint Framework ソリューションのホスティングには多数の利点がありますが、必須ではありません。コードを通常の SharePoint ドキュメント ライブラリでホストするという選択も可能です。 アプリ カタログにデプロイされたSharePoint Framework パッケージ (*.sppkg ファイル) は、ソリューションのコードを見つけることができる URL SharePoint Framework指定します。 Web パーツが含まれるページを参照するユーザーが指定の場所から対象スクリプトをダウンロードできる限りは、指定する URL に制限はありません。

Office 365 に備わっているパブリック CDN 機能を使用すると、特定の SharePoint ドキュメント ライブラリから CDN にファイルを公開できます。 Office 365 のパブリック CDN では、CDN を使用する利点と、SharePoint ドキュメント ライブラリでコード ファイルをホストする簡便さのバランスがうまく保たれています。 コード ファイルが公に使用可能になることを組織が問題にしない場合には、Office 365 のパブリック CDN の使用を検討する価値があります。

SharePoint Framework ソリューションとスクリプト エディター Web パーツ カスタマイズの相違点

SharePoint Framework およびスクリプト エディター Web パーツを使用して作成される SharePoint カスタマイズはよく似ています。 すべては、現在のユーザーのコンテキストでページのパーツとして実行され、クライアント側 JavaScript を使用して作成されます。 ただし、いくつかの大きな違いもあり、アーキテクチャ上の決定に影響を及ぼすため、ソリューションの設計時に銘記しておく必要があります。

スクリプトなしのサイトで実行する

クライアント側のカスタマイズをスクリプト エディター Web パーツを使用して作成する場合、カスタマイズを使用することになるサイトがスクリプトなしのサイトかどうかを考慮する必要がありました。 サイトがスクリプトなしのサイトの場合、スクリプトなしの設定を無効にするよう管理者に要求するか、アドイン モデルを使用するなど別の方法でソリューションをビルドする必要がありました。

SharePoint Framework ソリューションは事前承認を受けたアプリ カタログ経由で配置されるため、スクリプトなしの制約を受けず、すべてのサイトで動作します。

IT を利用して配置および更新する

スクリプト エディター Web パーツは主に市民開発者が SharePoint カスタマイズを作成するために使用されてきました。 市民開発者は、サイト所有者のアクセス許可さえあれば、ビジネス上の価値を付加できる魅力的な SharePoint カスタマイズを作成できます。 カスタマイズを更新する必要がある場合、必要なアクセス許可を持つユーザーはソリューションのスクリプト ファイルに更新を適用でき、すべてのユーザーが変更内容をすぐに確認できます。

スクリプト エディター Web パーツ ソリューションを使用すると、IT 組織は、使用されているカスタマイズとその使用場所を追跡するのが困難になります。 さらに、どの外部スクリプトが組織のイントラネットで使用されていて、組織のデータにアクセスできるかを判断することもできません。

SharePoint Framework は制御を IT に戻します。 SharePoint Framework ソリューションはアプリ カタログで一元的に配置および管理されるため、組織はソリューションの配置前に確認する機会があります。 さらに、すべての更新もアプリ カタログ経由で配置されるため、組織は検証および承認してから配置することができます。

ユーザー エクスペリエンスの統一に重点を置く

スクリプト エディター Web パーツを使用してカスタマイズを作成する場合、市民開発者が自分のカスタマイズの DOM すべてを所有します。 ユーザー エクスペリエンスおよびカスタマイズの動作方法についてのガイドラインはありません。 その結果、さまざまな開発者が異なる方法でカスタマイズをビルドし、エンドユーザーのユーザー エクスペリエンスに整合性がなくなります。

SharePoint Framework の目標の 1 つは、クライアント側カスタマイズのビルドを、配置、保守、ユーザー エクスペリエンスの観点で統一できるように標準化することです。 Office UI Fabric を使用すると、開発者はカスタム ソリューションの外観と動作を SharePoint の一部であるかのようにすることが簡単にでき、ユーザーによる導入を容易に行えます。 SharePoint Framework ツールチェーンによってソリューション用のパッケージ ファイルが生成されます。それを、アプリ カタログとスクリプト バンドルに配置し、選択したホスティング場所に配置します。 すべてのソリューションは同じ方法で構造化され、管理されます。

カスタマイズの外部で DOM を変更しない

従来、スクリプト エディター Web パーツを使用してページのパーツを変更すること、たとえば、ツールバーにボタンを追加したり、ページの見出しやブランドを変更したりすることがよくありました。 こうしたカスタマイズは特定の DOM 要素に依存し、SharePoint UI が更新されると、そうしたカスタマイズが壊れる可能性がありました。

SharePoint Framework では、SharePoint をカスタマイズするためにより構造化され、信頼性の高い方法が推奨されています。 特定の DOM 要素を使用して SharePoint をカスタマイズするのではなく、SharePoint Framework に備わっているパブリック API を使用して、開発者は SharePoint を拡張できます。 クライアント側 Web パーツが SharePoint Framework によってサポートされている唯一の形ですが、JSLink やユーザー カスタム アクションなどの他の形も今後使用できるように検討中で、SharePoint Framework を使用してほとんどの一般的なカスタマイズ シナリオを開発者が実装できるようにする予定です。

パッケージとして配布される

SharePoint クライアント側カスタマイズではデータを格納するための SharePoint リストとライブラリが使用されます。 スクリプト エディター Web パーツを使用してビルドする場合、必要な前提条件を自動的にプロビジョニングする簡単な方法はありませんでした。 同じカスタマイズを別のサイトに配置するときには、多くの場合、Web パーツをコピーしますが、同時に必要なデータ ストレージを適切に再作成して保守しなければなりませんでした。

SharePoint Framework ソリューションは、フィールド、コンテンツ タイプ、リストなどの前提条件を自動的にプロビジョニングできるパッケージとして配布されます。 パッケージをビルドする開発者は、ソリューションで必要となる成果物を指定できます。サイトにインストールされると、指定した成果物が作成されます。 これにより、複数のサイトにおけるソリューションの配置と管理のプロセスが大幅に簡素化されます。

より堅固なソリューションをビルドし、保守を簡単にするために TypeScript を使用する

スクリプト エディター Web パーツを使用してカスタマイズを作成するとき、多くの場合、市民開発者はプレーンな JavaScript を使用してきました。 そのようなソリューションには自動化されたテストが含まれておらず、コードのリファクタリングでエラーが生じやすい場合が少なくありませんでした。

SharePoint Framework を使用すると、開発者はソリューションのビルド時に TypeScript 型のシステムの利点を生かすことができます。 この型のシステムにより、実行時ではなく、開発中にエラーをキャッチできます。 また、コードのリファクタリングも簡単に実行できます。TypeScript によってコードに対する変更がセーフガードされるためです。 すべての JavaScript が有効な TypeScript であるため、エントリ障壁が低く、プレーンな JavaScript を時間の経過とともに徐々に TypeScript に移行し、ソリューションの保守能力を向上させていくことができます。

spPageContextInfo オブジェクトに依存できない

再利用可能なクライアント側のカスタマイズをビルドする場合、以前の開発者は spPageContextInfo JavaScript オブジェクトを使用して、現在のページ、サイト、またはユーザーに関する情報を取得しました。 このオブジェクトにより、SharePoint 内の異なるサイトでソリューションを再利用可能にする方法が提供され、固定の URL を使用する必要はありませんでした。

spPageContextInfo オブジェクトが依然としてクラシック SharePoint ページ上にある間は、最新の SharePoint ページとライブラリで信頼して使用することはできません。 SharePoint Framework でソリューションをビルドする際に、開発者は [IWebPartContext.pageContext](/javascript/api/sp-webpart-base/iwebpartcontext) オブジェクトを代わりに使用することをお勧めします。このオブジェクトには、特定のソリューションのコンテキスト情報が含まれています。

既定では SharePoint JavaScript オブジェクト モデルにアクセスできない

SharePoint クラシック ユーザー エクスペリエンス向けのクライアント側カスタマイズをビルドする場合、多くの開発者は JavaScript オブジェクト モデル (JSOM) を使用して SharePoint と通信しました。 JSOM により、クライアント側オブジェクト モデル (CSOM) と同じような方法で、SharePoint API に対して IntelliSense と簡単なアクセスが提供されてきました。 従来の SharePoint ページでは、JSON のコア要素は既定でページ上に存在し、開発者は、SharePoint Search との通信などのために追加要素を読み込むことができました。

既定では、SharePoint モダン ユーザー エクスペリエンスには SharePoint JSOM は含まれていません。 開発者自身で読み込むことができますが、代わりに REST API を使用することが推奨されています。 REST の使用は、jQuery、Angular、React などの異なるクライアント側ライブラリ間でより汎用的で交換可能です。

Microsoft は JSOM に関して積極的な投資は行っていません。 API を使用して作業する場合、SharePoint のパターンとプラクティスに関する JavaScript コア ライブラリを代わりに使用できます。このライブラリでは、Fluent API と TypeScript 型指定が提供されます。

既存のカスタマイズを SharePoint Framework に移行する

既存のスクリプト エディター Web パーツのカスタマイズを SharePoint Framework に移行すると、エンドユーザーと開発者の両方に多数の利点があります。 既存のカスタマイズを SharePoint Framework に移行することを検討する場合、既存のスクリプトをできるだけ多く再利用するのか、カスタマイズを完全に再作成するのかを選択できます。

既存のスクリプトを再利用する

既存のスクリプト エディター Web パーツのカスタマイズを SharePoint Framework に移行する場合、既存のスクリプトを再利用するように選択することもできます。 SharePoint Framework では TypeScript の使用が推奨されていますが、プレーンな JavaScript を使用して徐々に TypeScript に変換していくこともできます。 特定のソリューションを限られた期間だけサポートする必要がある場合や、予算が限られている場合には、この方法が適していることもあります。

SharePoint Framework ソリューションで既存のスクリプトを再利用することは常に可能とは限りません。 たとえば、SharePoint Framework ソリューションを JavaScript モジュールとしてパッケージ化し、ページ上で非同期的に読み込む場合があります。 一部の JavaScript ライブラリはモジュールで参照される場合に正常に動作せず、特定の方法で参照する必要があります。 さらに、onload() などのページ イベントに依存したり、jQuery ready() 関数を使用したりすると、望ましくない結果になることがあります。

JavaScript ライブラリが多様であることを考えると、既存のスクリプトを SharePoint Framework ソリューションで再利用できるか、結局再作成する必要があるかを簡単に見極める方法はありません。 見極める唯一の方法は、さまざまな部分を SharePoint Framework ソリューションに移行し、正常に動作するかどうか確認することです。

カスタマイズを再作成する

ソリューションを長期にわたりサポートする必要がある場合、SharePoint Framework を有効活用したい場合や、既存のスクリプトを SharePoint Framework で再利用できないことがわかった場合には、カスタマイズを完全に再作成しなければならない可能性があります。 既存のスクリプトを再利用するよりもコストが高くなりますが、長い目で見るとより良い結果が得られ、ソリューションのパフォーマンスは向上し、保守と使用が簡単になります。

既存のスクリプト エディター Web パーツのカスタマイズを SharePoint Framework ソリューションに再作成するときは、まず必要な機能に注意を払ってください。 ユーザー エクスペリエンスを実装するため、Office UI Fabric の使用を検討してください。それにより、ソリューションが SharePoint の不可欠な部分のようになります。 グラフやスライドなどの特定のコンポーネントに関しては、モジュールとして配布され、TypeScript 型指定を持つモダン ライブラリを探してください。 そうしたライブラリを使用すると、ソリューションに簡単にコンポーネントを統合できるようになります。

特定のシナリオで使用する最適なコンポーネントはどれかについて答えは 1 つではありませんが、SharePoint Framework はほとんどの一般的なシナリオに十分対応でき、既存のクライアント側カスタマイズを完全に機能の揃った SharePoint Framework ソリューションに変換できます。

移行のヒント

既存のスクリプト エディター Web パーツのカスタマイズを SharePoint Framework に変換するときは、いくつかの一般的なパターンがあります。

既存のコードを SharePoint Framework に移動する

スクリプト エディター Web パーツを使用してビルドする SharePoint カスタマイズは多くの場合、Web パーツに含まれるいくつかの HTML マークアップと、JavaScript ファイルへの 1 つまたは複数の参照で構成されます。 既存のカスタマイズを SharePoint Framework ソリューションに変換する場合には、スクリプト エディター Web パーツの HTML マークアップを、SharePoint Framework クライアント側 Web パーツの render() メソッドに移行することが必要である可能性が高くなります。 外部スクリプトへの参照は、./config/config.json ファイルの externals プロパティ内の参照に変更されます。 内部スクリプトは、Web パーツ ソース フォルダーにコピーされ、require() ステートメントを使用して Web パーツ クラスから参照されます。

スクリプト ファイルから関数を参照する

スクリプト ファイルから関数を参照するには、これらの関数をエクスポートとして定義する必要があります。 SharePoint Framework クライアント側 Web パーツで使用する、既存の JavaScript ファイルについて検討しましょう。

var greeting = function() {
  alert('How are you doing?');
  return false;
}

Web パーツ クラスから greeting 関数を呼び出せるようにするには、JavaScript ファイルを次のように変更する必要があります。

var greeting = function() {
  alert('How are you doing?');
  return false;
}

module.exports = {
  greeting: greeting
};

次に、Web パーツ クラスでこのスクリプトを参照し、greeting 関数を呼び出せます。

public render(): void {
  this.domElement.innerHTML = `<input type="button" value="Click me"/>`;

  const myScript = <any> require('./my-script.js');
  this.domElement.querySelector('input').addEventListener('click', myScript.greeting);
}

AJAX 呼び出しを実行する

多くのクライアント側カスタマイズでは、わかりやすさやブラウザー間の互換性を確保するために、AJAX 要求の実行用に jQuery を使用します。 jQuery を使用する目的がその点だけに限られている場合、SharePoint Framework に備わっている標準の HTTP クライアントを使用して、AJAX 呼び出しを実行できます。

SharePoint Framework には 2 つの種類の HTTP クライアント、つまり SPHttpClient (SharePoint REST API に対する要求の実行用) と HttpClient (他の REST API に対する Web 要求の発行用) が備わっています。 SPHttpClient を使用して、現在の SharePoint サイトのタイトルを取得する呼び出しの実行方法を次に示します。

this.context.spHttpClient.get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
SPHttpClient.configurations.v1,
{
  headers: {
    'Accept': 'application/json;odata=nometadata',
    'odata-version': ''
  }
})
.then((response: SPHttpClientResponse): Promise<{Title: string}> => {
  return response.json();
})
.then((web: {Title: string}): void => {
  // web.Title
}, (error: any): void => {
  // error
});

関連項目