SharePoint Framework の最初の拡張機能を構築する (Hello World パート 1)Build your first SharePoint Framework Extension (Hello World part 1)

SharePoint Framework (SPFx) 拡張機能は、SharePoint ページのコンテキスト内で実行されるクライアント側コンポーネントです。拡張機能は SharePoint Online に展開することができます。また、最新の JavaScript ツールとライブラリを使用して、拡張機能を構築できます。SharePoint Framework (SPFx) Extensions are client-side components that run inside the context of a SharePoint page. You can deploy extensions to SharePoint Online, and you can use modern JavaScript tools and libraries to build them.

この記事の手順は、SharePoint PnP YouTube チャンネルのビデオを視聴しながら実行することもできます。You can also follow the steps in this article by watching the video on the SharePoint PnP YouTube Channel.

Screenshot of the YouTube video player for this tutorial

拡張機能のプロジェクトを作成するCreate an extension project

  1. 自分の好みの場所に新しいプロジェクト ディレクトリを作成します。Create a new project directory in your favorite location.

    md app-extension
    
  2. プロジェクト ディレクトリへ移動します。Go to the project directory.

    cd app-extension
    
  3. Yeoman の SharePoint ジェネレーターを実行して、新しい HelloWorld の拡張機能を作成します。Create a new HelloWorld extension by running the Yeoman SharePoint Generator.

    yo @microsoft/sharepoint
    
  4. ダイアログ ボックスが表示されたら、次の手順に従います。When prompted:

    • ソリューション名として、既定の app-extension を受け入れて、Enter キーを押します。Accept the default app-extension as your solution name, and select Enter.
    • [SharePoint Online のみ (最新)] を選択し、Enter キーを押します。Select SharePoint Online only (latest), and select Enter.
    • [現在のフォルダーを使用する] を選択して、Enter キーを押します。Select Use the current folder, and select Enter.
    • [N] を選択して、拡張機能が使用されている場合は各サイトに明示的にインストールするよう要求します。Select N to require the extension to be installed on each site explicitly when it's being used.
    • 作成するクライアント側コンポーネントの種類として [拡張機能] を選択します。Select Extension as the client-side component type to be created.
    • 作成する拡張機能の種類として [アプリケーション カスタマイザー] を選択します。Select Application Customizer as the extension type to be created.
  5. 次の一連のダイアログ ボックスでは、拡張機能の詳細情報について入力が求められます。The next set of prompts ask for specific information about your extension. ダイアログ ボックスが表示されたら、次の手順に従います。When prompted:

    • 拡張機能名として、既定の HelloWorld を受け入れて、Enter キーを押します。Accept the default HelloWorld as your extension name, and select Enter.
    • 拡張機能の説明として、既定の HelloWorld の説明を受け入れ、Enter キーを押します。Accept the default HelloWorld description as your extension description, and select Enter.


      Yeoman の SharePoint ジェネレーターにより、拡張機能のソリューションを作成するダイアログが表示されます

      注意

      拡張機能の名前が長すぎると、問題が発生することがあります。If you use a name for the extension that is too long, you might encounter issues. 指定したエントリは、アプリケーション カスタマイザーの manifest JSON ファイルの alias エントリを生成するために使用されます。The entries provided are used to generate an alias entry for the Application Customizer manifest JSON file. alias が 40 文字を超えると、gulp serve --nobrowser を使用して拡張機能を提供しようとしたときに例外が発生します。If the alias is longer than 40 characters, you get an exception when you try to serve the extension by using gulp serve --nobrowser. これは、alias エントリを後で更新することで解決できます。You can resolve this by updating the alias entry afterward.

      この時点で、Yeoman は必要な依存関係をインストールし、ソリューション ファイルを HelloWorld の拡張機能とともにスキャフォールディングします。At this point, Yeoman installs the required dependencies and scaffolds the solution files along with the HelloWorld extension. これには数分かかる場合があります。This might take a few minutes.

      スキャフォールディングが完了すると、スキャフォールディングが正常に行われたことを示す次のメッセージが表示されます。When the scaffold is complete, you should see the following message indicating a successful scaffold:

      SharePoint のクライアント側ソリューションが正常にスキャフォールディングされました

      エラーのトラブルシューティング方法の詳細については、既知の問題を参照してください。For information about troubleshooting any errors, see Known issues.

  6. スキャフォールディングが完了したら、次のコマンドを実行して、プロジェクトの依存関係のバージョンをロック ダウンします。After the scaffolding completes, lock down the version of the project dependencies by running the following command:

    npm shrinkwrap
    
  7. 次に、コンソールに次のように入力して Visual Studio Code を起動します。Next, type the following into the console to start Visual Studio Code.

    code .
    

    注意

    SharePoint のクライアント側ソリューションは HTML や TypeScript に基づいているため、クライアント側の開発をサポートしている任意のコード エディターを使用して拡張機能を構築できます。Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension.

    既定のソリューションの構造とクライアント側 Web パーツのソリューションの構造が類似していることに注目してください。これは、SharePoint Framework ソリューションの基本的な構造であり、すべての種類のソリューションで同様の構成オプションが使用されています。Notice how the default solution structure looks like the solution structure for client-side web parts. This is the basic SharePoint Framework solution structure, with similar configuration options across all solution types.

    最初のスキャフォールディングの後に開かれた SharePoint Framework ソリューション

  8. src\extensions\helloWorld フォルダーの HelloWorldApplicationCustomizer.manifest.json を開きます。Open HelloWorldApplicationCustomizer.manifest.json in the src\extensions\helloWorld folder.

    このファイルでは、拡張機能の種類と拡張機能の一意識別子を定義します。この ID は、拡張機能のデバッグ時および SharePoint への展開時に必要になります。This file defines your extension type and a unique identifier for your extension. You’ll need this ID later when you debug and deploy your extension to SharePoint.

    アプリケーション カスタマイザー manifest json の内容

アプリケーション カスタマイザーのコードを作成するCode your Application Customizer

src\extensions\helloWorld フォルダー内の HelloWorldApplicationCustomizer.ts ファイルを開きます。Open the HelloWorldApplicationCustomizer.ts file in the src\extensions\helloWorld folder.

アプリケーション カスタマイザーの基底クラスは、アプリケーション カスタマイザーで必要な SharePoint Framework コードを含む sp-application-base パッケージからインポートされます。Notice that base class for the Application Customizer is imported from the sp-application-base package, which contains SharePoint framework code required by the Application Customizer.

@microsoft/sp-application-base からの BaseApplicationCustomizer の import ステートメント

アプリケーション カスタマイザーのロジックは、onInit メソッドに含まれていて、クライアント側の拡張機能がページ上で最初にアクティブ化されるときに呼び出されます。The logic for your Application Customizer is contained in the onInit method, which is called when the client-side extension is first activated on the page. このイベントは、this.contextthis.properties が割り当てられた後で発生します。This event occurs after this.context and this.properties are assigned. Web パーツと同様に、onInit() は非同期操作の実行に使用できる Promise を返します。As with web parts, onInit() returns a promise that you can use to perform asynchronous operations.

注意

クラス コンストラクターは、this.context および this.properties が定義されていない初期段階で呼び出されます。ここでは、カスタムの開始ロジックはサポートされません。The class constructor is called at an early stage, when this.context and this.properties are undefined. Custom initiation logic is not supported here.

次に、既定のソリューションの onInit() の内容を示します。この既定のソリューションは、Dev Dashboard にログを書き込んでから、ページがレンダリングされるときに簡単な JavaScript の通知を表示します。The following are the contents of onInit() in the default solution. This default solution writes a log to the Dev Dashboard, and then displays a simple JavaScript alert when the page renders.

コード内の既定の onInit メソッド

アプリケーション カスタマイザーが ClientSideComponentProperties という JSON 入力を使用する場合、BaseExtension.properties オブジェクトに逆シリアル化されます。If your Application Customizer uses the ClientSideComponentProperties JSON input, it is deserialized into the BaseExtension.properties object. インターフェイスを定義してそのオブジェクトを記述することができます。You can define an interface to describe it. 既定のテンプレートは、testMessage と呼ばれるプロパティを探します。The default template is looking for a property called testMessage. そのプロパティが提供されている場合、通知メッセージに出力します。If that property is provided, it outputs it in an alert message.

アプリケーション カスタマイザーのデバッグDebug your Application Customizer

現時点では、ローカル ワークベンチを使用して SharePoint Framework の拡張機能をテストすることはできません。You cannot currently use the local Workbench to test SharePoint Framework Extensions. テストは、ライブの SharePoint Online サイトに対して実行する必要があります。You need to test them against a live SharePoint Online site. そのために、カスタマイズをアプリ カタログに展開する必要はありません (これにより、デバッグ操作が簡単で効率的になります)。You don't have to deploy your customization to the app catalog to do this, which makes the debugging experience simple and efficient.

  1. 次のコマンドを実行して、コードをコンパイルし、コンパイルしたファイルをローカル コンピューターからホストします。Compile your code and host the compiled files from your local computer by running the following command:

    gulp serve --nobrowser
    

    注意

    SPFx 開発者の証明書がインストールされていない場合、ワークベンチにより localhost からスクリプトを読み込むように構成されていないことが通知されます。If you do not have the SPFx developer certificate installed, Workbench notifies you that it is not configured to load scripts from localhost. このような場合、コンソール ウィンドウで現在実行中のプロセスを停止し、gulp trust-dev-cert コマンドをプロジェクト ディレクトリ コンソールで実行して、開発者証明書をインストールしてから、gulp serve --nobrowser コマンドを再度実行します。If this happens, stop the process that is currently running in the console window, run the gulp trust-dev-cert command in your project directory console to install the developer certificate, and then run the gulp serve --nobrowser command again.

    ワークベンチをローカルで起動する必要がないため、--nobrowser オプションを使用します (拡張機能はローカルでデバッグできません)。You use the --nobrowser option because you don't need to launch the local Workbench since you can't debug extensions locally.

    コードがエラーなしでコンパイルされると、https://localhost:4321 から結果のマニフェストが提供されます。When the code compiles without errors, it serves the resulting manifest from https://localhost:4321.

    Gulp serve

  2. 拡張機能をテストするには、SharePoint 環境の最新のリスト ビュー ページに移動し、URL に次のクエリ文字列パラメーターを追加します。To test your extension, go to a modern list view page in your SharePoint environment and append the following query string parameters to the URL. 独自の拡張機能 ID と一致するように ID の更新が必要であることに注意してください。Notice that you need to update the ID to match your own extension identifier. これは、HelloWorldApplicationCustomizer.manifest.json ファイル内にあります。This is available in the HelloWorldApplicationCustomizer.manifest.json file.

        ?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"e5625e23-5c5a-4007-a335-e6c2c3afa485":{"location":"ClientSideExtension.ApplicationCustomizer","properties":{"testMessage":"Hello as property!"}}}
    

    URL クエリ パラメーターの詳細:More detail about the URL query parameters:

    • loadSPFX=trueloadSPFX=true. SharePoint Framework が確実にページに読み込まれるようにします。Ensures that the SharePoint Framework is loaded on the page. パフォーマンス上の理由から、少なくとも 1 つの拡張機能が登録されていないとフレームワークは読み込まれません。For performance reasons, the framework does not load unless at least one extension is registered. 登録されているコンポーネントがないため、フレームワークを明示的に読み込む必要があります。Because no components are registered, you must explicitly load the framework.

    • debugManifestsFiledebugManifestsFile. ローカルに提供されている SPFx コンポーネントを読み込むように指定します。Specifies that you want to load SPFx components that are locally served. ローダーはアプリ カタログ (展開したソリューション用) と SharePoint マニフェスト サーバー (システム ライブラリ用) のコンポーネントのみを検索します。The loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries).

    • customActionscustomActions. カスタム アクションをシミュレートします。Simulates a custom action. このコンポーネントをサイトに展開して登録するときに、この CustomAction オブジェクトを作成して、そのオブジェクトに設定できる各種プロパティをすべて記述します。When you deploy and register this component in a site, you'll create this CustomAction object and describe all the different properties you can set on it.

      • KeyKey. カスタム アクションに関連付けるキーとして拡張機能の GUID を使用します。Use the GUID of the extension as the key to associate with the custom action. これは、拡張機能の ID 値と一致する必要があります。この ID 値は、拡張機能の manifest.json ファイルにあります。This has to match the ID value of your extension, which is available in the extension manifest.json file.
      • LocationLocation. カスタム アクションの種類。The type of custom action. アプリケーション カスタマイザー拡張機能には、ClientSideExtension.ApplicationCustomizer を使用します。Use ClientSideExtension.ApplicationCustomizer for the Application Customizer extension.
      • PropertiesProperties. this.properties メンバーを介して利用できるプロパティを含む、オプションの JSON オブジェクトです。An optional JSON object that contains properties that are available via the this.properties member. この HelloWorld の例では、testMessage プロパティを定義しました。In this HelloWorld example, it defined a testMessage property.
  3. SharePoint Online の最新のリストに移動します。Go to a modern list in SharePoint Online. これはリストまたはライブラリのどちらかです。This can be either a list or a library. アプリケーション カスタマイザーはモダン ページとサイト コンテンツ ページでもサポートされています。Application Customizers are also supported in modern pages and on the Site Contents page.

  4. 前述した追加のクエリ パラメーターで URL を拡張します。Extend the URL with the additional query parameters described. カスタムのアプリケーション カスタマイザーの ID と一致するように GUID を更新する必要がある点に注意してください。Notice that you need to update the GUID to match the ID of your custom Application Customizer.

    完全な URL は、次のようになります。The full URL should look similar to the following:

    contoso.sharepoint.com/Lists/Contoso/AllItems.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"e5625e23-5c5a-4007-a335-e6c2c3afa485":{"location":"ClientSideExtension.ApplicationCustomizer","properties":{"testMessage":"Hello as property!"}}}
    
  5. [デバッグ スクリプトを読み込む] を選択して、ローカル ホストからのスクリプトの読み込みを続行します。Select Load debug scripts to continue loading scripts from your local host.

    ページからのデバッグ マニフェストの質問を許可する


    ページにダイアログ メッセージが表示されます。You should now see the dialog message on your page.

    プロパティ通知メッセージとしての Hello

    このダイアログは、SharePoint Framework 拡張機能によりスローされます。This dialog is thrown by your SharePoint Framework Extension. デバッグ クエリ パラメーターの一部として testMessage プロパティを指定したので、これも通知メッセージに含まれていることに注意してください。Note that because you provided the testMessage property as part of the debug query parameters, it's included in the alert message. ランタイム モードでインスタンスに渡されるクライアント コンポーネント プロパティに基づいて、拡張機能インスタンスを構成できます。You can configure your extension instances based on the client component properties, which are passed for the instance in runtime mode.

注意

デバッグ時に問題が発生した場合は、クエリに使用している URL クエリ パラメーターをダブルクリックします。一部のブラウザーはパラメーターをエンコードするため、これが動作に影響することがあります。If you have issues with debugging, double-check the URL query parameters used for the query. Some browsers encode the parameters and in some scenarios this affects the behavior.

次の手順Next steps

これで完了です。SharePoint Framework の最初の拡張機能が動作するようになりました。Congratulations, you got your first SharePoint Framework Extension running!

引き続き拡張機能を構築するには、「アプリケーション カスタマイザーからページ プレースホルダーを使用する (Hello World パート 2)」を参照してください。To continue building out your extension, see Using page placeholders from Application Customizer (Hello World part 2). 同じプロジェクトを使用し、SharePoint の UI を変更するために特定のコンテンツ プレース ホルダーを活用します。You use the same project and take advantage of specific content placeholders for modifying the UI of SharePoint. gulp serve コマンドは、コンソール ウィンドウ内 (または、エディターを使用している場合は Visual Studio Code 内) で実行中であることに注意してください。Notice that the gulp serve command is still running in your console window (or in Visual Studio Code if you are using the editor). それを実行しながら、次の記事に移動します。You can continue to let it run while you go to the next article.

注意

ドキュメントまたは SharePoint Framework に問題が見つかった場合は、sp-dev-docs リポジトリの懸案事項リストを使用して SharePoint エンジニアリングに報告してください。If you find an issue in the documentation or in the SharePoint Framework, report that to SharePoint engineering by using the issue list at the sp-dev-docs repository. よろしくお願いします。Thanks for your input in advance.