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

完了

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

重要

下記の手順では、SharePoint Framework Yeoman ジェネレーターの v1.12.1 を使用していることを前提としています。

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

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

yo @microsoft/sharepoint

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

  • ソリューション名は何ですか?: SPFxAppCustomizer
  • どのベースライン パッケージをコンポーネントのターゲットにしたいですか?: SharePoint Online のみ (最新)
  • ファイルをどこに保存しますか?: 現在のフォルダーを使用する
  • テナント管理者が、サイトで機能を展開したり、アプリを追加したりせず、すぐにすべてのサイトでソリューションを展開できるようにしたいですか?: はい
  • ソリューションのコンポーネントには、テナント内の他のコンポーネントと共有されていない一意の Web API にアクセスするためのアクセス許可が必要ですか?: いいえ
  • どの種類のクライアント側コンポーネントを作成しますか?: 拡張機能
  • どの種類のクライアント側拡張機能を作成しますか?: アプリケーション カスタマイザー
  • アプリケーション カスタマイザー名は何ですか?: HelloAppCustomizer
  • アプリケーション カスタマイザーの説明: 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 サーバーです。

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

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

スクリプトが読み込まれると、次のような SharePoint 警告ダイアログが表示されます。

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

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

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

コンソールまたはターミナル ウィンドウで CTRL+C を押してローカル Web サーバーを停止します。

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

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

カスタマイザーを 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 プロパティを設定します。

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

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

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

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

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

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

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

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

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

新しいファイル 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 ステートメントを検索します。 インポートのリストを更新して、次の参照を追加します。 PlaceholderContent および PlaceholderName です。

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();

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

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

gulp serve

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

ページが読み込まれると、パブリック プロパティで定義されたテキストがページのヘッダーとフッターに表示されることに注意してください。

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

コンソールまたはターミナル ウィンドウで CTRL+C を押してローカル Web サーバーを停止します。

アプリケーション カスタマイザーを 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 のテナント アプリ カタログ サイトに移動します。

左側のナビゲーションで [SharePoint 用アプリ] リストを選択します。

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

[spfx-app-customizer-client-side-solution を信頼しますか?] ダイアログで、以下の操作を行います。

  • チェックボックス [このソリューションを組織内のすべてのサイトで使用可能にする] を選択する
  • メッセージ "このパッケージには、サイト間で自動的に有効になる拡張機能が含まれています..." を確認します
  • [展開] を選択します

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

左側のナビゲーションで [サイト コンテンツ] を選択します。

[テナント全体の拡張機能] を選択します。 テナントが作成された時期によっては [テナント全体の拡張機能] リストが表示されない場合があります。 サイト コンテンツにリストが表示されない場合は、アプリカタログサイトの URL に /Lists/TenantWideExtensions/AllItems.aspx を追加することで、手動で移動する必要があります。

アプリ カタログ サイトのコンテンツを表示するスクリーンショット

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

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

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

概要

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

自分の知識をテストする

1.

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

2.

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