演習 - アプリケーションカスタマイザー拡張機能を作成する - Training

14 分

この演習では、SharePoint Framework (SPFx) のアプリケーションカスタマイザー拡張機能を作成します。

前提条件

重要

ほとんどの場合、次のツールの最新バージョンをインストールすることをお勧めします。ここに記載されているバージョンのリストは、このモジュールが発行され、最後にテストしたときに使用されたものです。

新しい SharePoint Framework プロジェクトを作成する

コマンドプロンプトを開き、現在のディレクトリを、プロジェクトを作成するフォルダーに変更します。

次のコマンドを実行して、SharePoint Yeoman ジェネレーターを起動します。

yo @microsoft/sharepoint

プロンプトが表示されたら、次の情報を使用して応答します (他にもオプションが表示された場合は、既定の回答を使用します):

ソリューション名は何ですか?: SPFxAppCustomizer
どの種類のクライアント側コンポーネントを作成しますか?: 拡張機能
どの種類のクライアント側拡張機能を作成しますか?: アプリケーションカスタマイザー
アプリケーションカスタマイザー名は何ですか?: HelloAppCustomizer

プロジェクトに必要なフォルダーをプロビジョニングした後、ジェネレーターは npm install を自動的に実行することで、すべての依存関係パッケージをインストールします。 NPM がすべての依存関係のダウンロードを完了したら、ジェネレーターによってプロビジョニングされた既定のプロジェクトをテストします。

ホストされているワークベンチでテストできる Web パーツとは異なり、拡張機能は最新の SharePoint ページでテストする必要があります。拡張機能がローカル開発 Web サーバーから読み込まれたことを示すため、要求には特別なクエリ文字列パラメーターが含まれています。

拡張機能をテストする場合は、serve.json 構成ファイルを変更する必要があります。実際の SharePoint 環境で最新のページの URL を取得することから開始します。

次に、./config/serve.json ファイルを開き、最新の SharePoint ページの URL を serveConfigurations.default.pageUrl プロパティにコピーします。

注:

SPFx ビルドプロセスの Gulp サービス タスクはブラウザーを起動して、この URL に移動して、必要なクエリ文字列パラメーターを追加します。

次のコマンドを実行してプロジェクトを起動します。

gulp serve

SharePoint ページが読み込まれると、SharePoint は、デバッグスクリプトの読み込みを求めるメッセージを表示されます。これは、信頼されていないソースからスクリプトを読み込む必要があることを確認するための確認チェックです。信頼されていないソースは、https://localhost におけるローカル開発 Web サーバーです。

[デバッグスクリプトを読み込む] ボタンを選択します。

デバッグスクリプトを許可するダイアログのスクリーンショット。

この警告が表示された場合は、コマンドプロンプトに戻り、reload サブタスクの実行が完了するまで待ってから、ページを更新します:

マニフェストの読み込み警告のスクリーンショット。

ページが読み込まれると、SharePoint アラートダイアログが表示されます。

SharePoint 警告ダイアログのスクリーンショット。

この警告ダイアログは、アプリケーションカスタマイザーによって表示されます。 ./src/extensions/helloAppCustomizer/HelloAppCustomizerApplicationCustomizer.ts にあるアプリケーションカスタマイザーを開き、onInit() メソッドを検索します。ダイアログの表示をトリガーするメソッドの次の行に注意してください。

Dialog.alert(`Hello from ${strings.Title}:\n\n${message}`);

ローカル Web サーバーを停止するには、コマンドプロンプトで CTRL+C を押します。

アプリケーションカスタマイザーを更新して、ページにプレースホルダーを追加する

この手順では、アプリケーションカスタマイザーを変更して、ページの上下のプレースホルダーにいくつかの定義済みテキストを書き込みます。

カスタマイザーを 2 つの公開設定可能プロパティを持つように更新する

./src/extensions/helloAppCustomizer/HelloAppCustomizerApplicationCustomizer.ts ファイルを検索して開きます。

IHelloAppCustomizerApplicationCustomizerProperties インターフェイスを見つけて、2 つのプロジェクトのみを持つように編集します。

header: string;
footer: string;

テストおよび展開用の構成を更新する

変更をテストする場合は、serve.json ファイルをhwン港して、これら 2 つのプロパティを含めます。

./config/serve.json ファイルを検索して開きます。 serveConfigurations.default.properties オブジェクトを検索して、properties オブジェクトの値を次のように変更します。

"properties": {
  "header": "Header area of the page",
  "footer": "Footer area of the page"
}

この変更は、アプリケーションカスタマイザーをテストするときにのみアプリケーションカスタマイザーを更新します。コンポーネントが展開されたときにこれらのプロパティが設定されていることを確認するには、展開中に使用する要素マニフェストファイルを変更する必要があります。

./sharepoint/assets/elements.xml ファイルを検索して開きます。

パブリックプロパティ値を含む次の HTML エンコードされた JSON 文字列に ClientSideComponentProperties プロパティを設定します。

{&quot;header&quot;:&quot;Header area of the page&quot;,&quot;footer&quot;:&quot;Footer area of the page&quot;}

ここで、拡張機能が SharePoint Online のテナントのすべてのサイトに展開されているときに、使用するファイルに同じ変更を加えます。

./sharepoint/assets/ClientSideInstance.xml ファイルを検索して開きます。

パブリックプロパティ値を含む次の HTML エンコードされた JSON 文字列に Properties プロパティを設定します。

{&quot;header&quot;:&quot;Header area of the page&quot;,&quot;footer&quot;:&quot;Footer area of the page&quot;}

アプリケーションカスタマイザーに CSS スタイルを追加する

この次の手順では、プレーン <div> 要素よりも、ヘッダーとフッターのユーザーエクスペリエンスを向上させるために CSS を変更します。

コマンドラインで次のコマンドを実行して、Office UI Fabric Core CSS ファイルの SPFx バージョンをインストールすることから開始します。

npm install @microsoft/sp-office-ui-fabric-core -SE

新しいファイル HelloAppCustomizerApplicationCustomizer.module.scss を ./src/extensions/helloAppCustomizer フォルダーに作成して、次の SCSS コードを追加します。

@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

.app {
  .top {
    height:60px;
    text-align:center;
    line-height:2.5;
    font-weight:bold;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: $ms-color-themePrimary;
    color: $ms-color-white;
  }

  .bottom {
    height:40px;
    text-align:center;
    line-height:2.5;
    font-weight:bold;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: $ms-color-themePrimary;
    color: $ms-color-white;
  }
}

./src/extensions/helloAppCustomizer/HelloAppCustomizerApplicationCustomizer.ts ファイルを検索して開きます。

次の import ステートメントを、ファイルの先頭にある既存の import ステートメントの後に追加します。

import styles from './HelloAppCustomizerApplicationCustomizer.module.scss';
import { escape } from '@microsoft/sp-lodash-subset';

ヘッダーとフッターのプレースホルダーを更新する

./src/extensions/helloAppCustomizer/HelloAppCustomizerApplicationCustomizer.ts ファイルを検索して開きます。

@microsoft/sp-application-base ライブラリの既存importのステートメントを見つけます。インポートの一覧を更新して、次の参照を追加します。 PlaceholderContentPlaceholderName

import {
  BaseApplicationCustomizer,
  PlaceholderContent,
  PlaceholderName
} from '@microsoft/sp-application-base';

HelloAppCustomizerApplicationCustomizer クラスに次の 2 つのプライベートメンバーを追加します。

private _topPlaceholder: PlaceholderContent | undefined;
private _bottomPlaceholder: PlaceholderContent | undefined;

次のメソッドを HelloAppCustomizerApplicationCustomizer クラスに追加します。このメソッドは、プレースホルダーが破棄された場合に使用されます。

private _onDispose(): void {
  console.log('[HelloWorldApplicationCustomizer._onDispose] Disposed custom top and bottom placeholders.');
}

次のメソッドを HelloAppCustomizerApplicationCustomizer クラスに追加します。このメソッドは、プレースホルダーが表示されるときに呼び出されます。

private _renderPlaceHolders(): void {
  console.log('Available application customizer placeholders: ',
    this.context.placeholderProvider.placeholderNames
      .map((name) => PlaceholderName[name])
      .join(', ')
  );
}

_renderPlaceHolders() メソッドに、次のコードを追加します。このコードは、ページの一番上のプレースホルダーのハンドルを取得します。次に、パブリックプロパティで定義されたメッセージを使用して、プレースホルダーにいくつかのマークアップを追加します。

if (!this._topPlaceholder) {
  this._topPlaceholder = this.context.placeholderProvider.tryCreateContent(
    PlaceholderName.Top,
    { onDispose: this._onDispose }
  );

  if (!this._topPlaceholder) {
    console.error('The expected placeholder (Top) was not found.');
    return;
  }

  if (this.properties) {
    let headerMessage: string = this.properties.header;
    if (!headerMessage) {
      headerMessage = '(header property was not defined.)';
    }

    if (this._topPlaceholder.domElement) {
      this._topPlaceholder.domElement.innerHTML = `
        <div class="${styles.app}">
          <div class="${styles.top}">
            <i class="ms-Icon ms-Icon--Info" aria-hidden="true"></i> ${escape(headerMessage)}
          </div>
        </div>`;
    }
  }
}

次のコードを _renderPlaceHolders() に追加して、一番下のプレースホルダーを更新します。

if (!this._bottomPlaceholder) {
  this._bottomPlaceholder = this.context.placeholderProvider.tryCreateContent(
    PlaceholderName.Bottom,
    { onDispose: this._onDispose }
  );

  if (!this._bottomPlaceholder) {
    console.error('The expected placeholder (Bottom) was not found.');
    return;
  }

  if (this.properties) {
    let footerMessage: string = this.properties.footer;
    if (!footerMessage) {
      footerMessage = '(footer property was not defined.)';
    }

    if (this._bottomPlaceholder.domElement) {
      this._bottomPlaceholder.domElement.innerHTML = `
        <div class="${styles.app}">
          <div class="${styles.bottom}">
            <i class="ms-Icon ms-Icon--Info" aria-hidden="true"></i> ${escape(footerMessage)}
          </div>
        </div>`;
    }
  }
}

onInit() メソッドのすべてのコードを次のコードに置き換えます。

Log.info(LOG_SOURCE, `Initialized ${strings.Title}`);

this.context.placeholderProvider.changedEvent.add(this, this._renderPlaceHolders);

return Promise.resolve();

最後に、インポートを使用 Dialog しなくなったため、ファイルから次の行を削除します。

import { Dialog } from '@microsoft/sp-dialog';

アプリケーションカスタマイザーをテストします。

次のコマンドを実行してプロジェクトを起動します。

gulp serve

メッセージが表示されたら、[デバッグスクリプトの読み込み] ボタンを選択します。

ページが読み込まれると、パブリックプロパティで定義されたテキストがページのヘッダーとフッターに表示されることに注意してください。ヘッダーとフッターがページに表示されない場合は、コマンドプロンプトに戻り、reload サブタスクの実行が完了するまで待ってから、更新します。

アプリケーションカスタマイザーのプレースホルダーが表示されたスクリーンショット。

ローカル Web サーバーを停止するには、コマンドプロンプトで CTRL+C を押します。

アプリケーションカスタマイザーを SharePoint Online テナントのすべてのサイトに展開する

この手順では、アプリケーションカスタマイザーを SharePoint テナント全体に展開します。

./config/package-solution.json ファイルを検索して開きます。 solution オブジェクトに skipFeatureDeployment という名前のプロパティがあることを確認し、このプロパティの値が true に設定されていることを確認します。

./sharepoint/assets/ClientSideInstance.xml ファイルを検索して開きます。このファイルには、パッケージが展開されるときに SharePoint Online テナントのアプリカタログサイトのテナント全体の拡張機能 リストに自動的に設定される値が含まれます。

次のコマンドを 1 つずつ実行して、ソリューションをビルドしてパッケージ化します。

gulp build
gulp bundle --ship
gulp package-solution --ship

ブラウザーで SharePoint Online のテナント アプリカタログ サイトに移動します。

Microsoft は、従来の App Catalog ユーザーエクスペリエンスから最新の App Catalog ユーザーエクスペリエンスに移行中です。クラシックアプリカタログが表示されている場合は、ページの上部に [ 新しいアプリの管理] ページ リンクを選択するか、アプリカタログサイト URL の末尾に /_layouts/15/tenantAppCatalog.aspx を追加できます。どちらのオプションでも、最新のアプリカタログ (つまり、[ アプリの管理 ] ページ) に移動する必要があります。

クラシックアプリカタログのスクリーンショット。

最新のアプリカタログのスクリーンショット。

生成された ./sharepoint/solution/sp-fx-app-customizer.sppkg ファイルを [SharePoint 用アプリ] リストにドラッグします。

[アプリを有効にする] パネルで、[このアプリを有効にしてすべてのサイトに追加する] ラジオボタンが選択されていることを確認し、[アプリを有効にする] を選択します。

テナント全体に拡張機能を展開するスクリーンショット。

[このアプリは有効になっています] パネルで、[閉じる] を選択します。

左側のナビゲーションで [その他の機能] を選択し、[テナント全体の拡張機能] の下にある [開く] ボタンを選択します。

指定したプロパティを含むアプリケーションカスタマイザーがリストに表示されることに注意してください。

テナント全体の拡張機能リストが表示されたスクリーンショット。

別のブラウザーウィンドウで、SharePoint Online テナント内の任意の最新のサイト内のいずれかの最新ページに移動します。テナントに拡張機能が表示されます。

概要

この演習では、SharePoint Framework (SPFx) のアプリケーションカスタマイザー拡張機能を作成します。

自分の知識をテストする

ローカル Web サーバーを使用して拡張機能をテストするとき、アプリケーションカスタマイザーのパブリックプロパティはどのように設定されますか?

ページが編集モードの場合は、既定のプロパティウィンドウに設定される。

serve.json 構成ファイルに設定されている HTML でエンコードされた文字列を使用して設定される。

serve.json 構成ファイルに設定されている JSON でエンコードされた文字列を使用して設定される。

拡張機能が運用環境に展開されるとき、アプリケーションカスタマイザーのパブリックプロパティはどのように設定されますか?

ページが編集モードの場合は、既定のプロパティウィンドウに設定される。

elements.xml およびオプションで ClientSideInstance.xml ファイルに設定されている JSON でエンコードされた文字列を使用して設定される。

elements.xml およびオプションで ClientSideInstance.xml ファイルに設定されている HTML でエンコードされた文字列を使用して設定される。

作業を確認する前にすべての問題に回答する必要があります。

続行

演習 - アプリケーション カスタマイザー拡張機能を作成する

前提条件

新しい SharePoint Framework プロジェクトを作成する

アプリケーション カスタマイザーを更新して、ページにプレースホルダーを追加する

カスタマイザーを 2 つの公開設定可能プロパティを持つように更新する

テストおよび展開用の構成を更新する

アプリケーション カスタマイザーに CSS スタイルを追加する

ヘッダーとフッターのプレースホルダーを更新する

アプリケーション カスタマイザーをテストします。

アプリケーション カスタマイザーを SharePoint Online テナントのすべてのサイトに展開する

概要

自分の知識をテストする

フィードバック

演習 - アプリケーションカスタマイザー拡張機能を作成する

アプリケーションカスタマイザーを更新して、ページにプレースホルダーを追加する

アプリケーションカスタマイザーに CSS スタイルを追加する

アプリケーションカスタマイザーをテストします。

アプリケーションカスタマイザーを SharePoint Online テナントのすべてのサイトに展開する