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.



拡張機能のプロジェクトを作成する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.
    • 次の質問、テナント管理者がすべてのサイトにソリューションを展開可能にする選択を許可しますか? に [いいえ (N)]を選択し Enter キーを押します。For the next question Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites...., ensure you select No (N) , and select Enter. Yes (y) を選択すると、スキャフォールディングは Elements.xml フィーチャー展開ファイルを生成しません。If you select Yes (y), the scaffolding will not generate the Elements.xml feature deployment file.


      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. 次に、コンソールに次のように入力して 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 ソリューション

  7. 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 メソッド

注意

SharePoint フレームワーク開発者ダッシュボードは追加の UI ダッシュボードで、ctrl+F12 で起動できます。SharePoint Framework Dev Dashboard is additional UI dashboard, which can be started with ctrl+F12. これは開発者向けの情報で、開発者として利用できるものです。This is developer oriented logging information, which you can take advantage as developer. また、その中には多くのアウト オブ バンド ロギングがあります。It also has plenty of oob logging in it.

アプリケーション カスタマイザーが 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. Config フォルダーに serve.json ファイルを開きます。Open the server.json file in the config folder.

    プロジェクトに一致する既定の設定で、このファイルが更新されたことに確認してください。Notice that this file has been updated with the default settings matching your project. customActions 要素の下に記載されている特定の GUID があることを確認できます。Yuo can notice that there's a specific GUID mentioned under the customActions element. これは、プロジェクトがスキャフォールドされたときに、コンポーネントに一致するように自動的に更新されます。This is automatically updated to match your component when project was scaffold. 新しいコンポーネントを追加する場合、またはコンポーネントのプロパティを変更する場合には、テスト用にこのファイルを更新する必要があります。If you will add new components or change the properties for the component, you will need to update this file for testing.

  2. 独自のテナントに一致するように pageURL を更新し、テスト用に使用します。Update pageURL to match your own tenant, which you want to use for testing. モダン エクスペリエンスでは、どのような URL でも使用できます。You can use any URL with modern experience. * たとえば、チーム サイトに関連する新しいグループのウェルカム ページでもよく、その場合は以下のような URL になります。*This could be for example a welcome page of a new group associated team site, which would mean somewhat following URL:

    https://sppnp.sharepoint.com/sites/yoursite/SitePages/Home.aspx

    Serve.json ファイルは、以下のようになります (テナントの詳細で更新されたもの) 。Your serve.json file should look somewhat following (updated with your tenant details):

    更新されたサーバーの json ファイル

  3. コンソールに切り替え、まだ app-extension ディレクトリ内にいることを確認してから、以下のコマンドを入力します。Switch to your console, ensure that you are still in the helloworld-webpart directory, and then enter the following command:

    注意

    開発者証明書を開発環境で 1 回だけインストールする必要があります。そのため、お使いの環境ですでに実行済みの場合は、この手順をスキップできます。Developer certificate has to be installed ONLY once in your development environment, so you can skip this step, if you have already executed that in your environment.

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

    gulp serve
    

    注意

    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. このプロセスは、「開発環境のセットアップ」の資料に記載されています。This process is documented in the Set up your development environment article.

    コードがエラーなしにコンパイルされる場合は、このコードは https://localhost:4321 から結果のマニフェストを提供し、また、必要なクエリ パラメーターで既定のブラウザを起動します。When the code compiles without errors, it serves the resulting manifest from https://localhost:4321 and also starts your default browser with needed query parameters.

    ガルプ サーブ

  5. ブラウザに移動し、[デバッグ スクリプトを読み込む] を選択して、ローカル ホストからのスクリプトの読み込みを続行します。Move to your browser and 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.

注意

デバッグで問題があるときは、 server.json ファイル内の pageUrl 設定を再確認してください。If you have issues with debugging, double-check the pageUrl setting in the server.json file.

次の手順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. コマンドは、コンソール ウィンドウ内 (または、エディターを使用している場合は Visual Studio Code 内) で実行中であることに注意してください。gulp serveNotice 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, please report that to SharePoint engineering by using the issue list at the sp-dev-docs repository. よろしくお願いします。Thanks for your input in advance.