JSLink から SharePoint Framework 拡張機能への移行

[アーティクル]
03/21/2023

Microsoft SharePoint 2013 以降、Microsoft 365 および SharePoint Online 上に構築されたほとんどのエンタープライズソリューションは、フィールドとリストビューの JSLink プロパティを使用して、フィールドの表示をカスタマイズしていました。

SharePoint Online と SharePoint Server 2019 の "モダン" UI では、これらのカスタマイズのほとんどが使用できなくなりました。幸い、SharePoint Framework 拡張機能を使用すると、"モダン" UI で同様の機能を提供できます。

このチュートリアルでは、以前の "クラシック" カスタマイズから SharePoint Framework 拡張機能に基づく新しいモデルに移行する方法について説明します。

注:

SharePoint Framework 拡張機能の構築方法の詳細については、「SharePoint Framework 拡張機能の概要」を参照してください。

最初に、SharePoint Framework 拡張機能を開発するときに使用できるオプションを紹介します。

アプリケーションカスタマイザー: "モダン" ページの事前定義されたプレースホルダーにカスタム HTML 要素とクライアント側コードを追加することによって、SharePoint のネイティブ "モダン"UI を拡張します。アプリケーションカスタマイザーの詳細については、「SharePoint Framework の最初の拡張機能をビルドする (Hello World パート 1)」を参照してください。
コマンドセット: カスタムの編集コントロールブロック (ECB) のメニュー項目またはカスタムボタンを、リストまたはライブラリのリストビューのコマンドバーに追加します。これらのコマンドには、任意のクライアント側アクションを関連付けることができます。コマンドセットの詳細については、「最初の ListView コマンドセット拡張機能をビルドする」を参照してください。
フィールドカスタマイザー: カスタム HTML 要素とクライアント側コードを使用して、リストビュー内のフィールドの表示をカスタマイズします。フィールドカスタマイザーの詳細については、「最初のフィールドカスタマイザー拡張機能をビルドする」を参照してください。

このコンテキストで最も便利なオプションは、フィールドカスタマイザー拡張機能です。

SharePoint Online を利用しており、"Color" と呼ばれるカスタムフィールドを含むカスタムリストがあるとします。このカスタムフィールドは種類が Choice で、値が Red、Green、Blue、Yellow です。カスタムリストの Web パーツを表示するリストビューの JSLink プロパティにカスタム値があるとします。

次のコードスニペットでは、JSLink プロパティによって参照される JavaScript コードを示します (customColorRendering.js)。

// Define a namespace for the custom rendering code
var customJSLinkRendering = customJSLinkRendering || {};

// Define a function that declare the custom rendering rules for the target list view
customJSLinkRendering.CustomizeFieldRendering = function () {

  // Define a custom object to configure the rendering template overrides
  var customRenderingOverride = {};
  customRenderingOverride.Templates = {};
  customRenderingOverride.Templates.Fields =
  {
    // Declare the custom rendering function for the 'View' of field 'Color'
    'Color':
    {
      'View': customJSLinkRendering.RenderColorField
    }
  };

  // Register the custom rendering template
  SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customRenderingOverride);
};

// Declare the custom rendering function for the 'View' of field 'Color'
customJSLinkRendering.RenderColorField = function (context)
{
  var colorField = context.CurrentItem.Color;

  // Declare a local variable to hold the output color
  var color = '';

  // Evaluate the values of the 'Color' field and render it accordingly
  switch (colorField)
  {
    case 'Red':
      color = 'red';
      break;
    case 'Green':
      color = 'green';
      break;
    case 'Blue':
      color = 'blue';
      break;
    case 'Yellow':
      color = 'yellow';
      break;
    default:
      color = 'white';
      break;
  }

  // Render the output for the 'Color' field
  return "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />";
};

// Invoke the custom rendering function
customJSLinkRendering.CustomizeFieldRendering();

次のスクリーンショットでは、リストビューの Web パーツ内で JSLink プロパティがどのように構成されているかを確認できます。

リストビュー Web パーツでの JSLink プロパティの構成

JavaScript ファイルを Site Assets ライブラリにアップロードすると、JSLink プロパティの値は "~site/SiteAssets/customColorRendering.js" となります。

リストのカスタム表示のしくみを確認できます。

カスタムリストにおける

ご覧のように、"Color" フィールドには、アイテムレベルで選択した色で塗りつぶされた色付きのボックスが表示されます。

注:

この種のソリューションを "クラシック" サイトでプロビジョニングするには、カスタムフィールドのあるリストと JSLink プロパティを同時にプロビジョニングできる PnP プロビジョニングテンプレートを最終的に使用します。

従来のソリューションを SharePoint Framework に移行するには、次の手順を参照してください。

新しい SharePoint Framework ソリューションの作成

コンソールから、プロジェクト用の新しいフォルダーを作成します。
```
md spfx-custom-field-extension
```
プロジェクトフォルダーに移動します。
```
cd spfx-custom-field-extension
```
プロジェクトフォルダーで SharePoint Framework Yeoman ジェネレーターを実行して、新しい SharePoint Framework プロジェクトをスキャホールディングします。
```
yo @microsoft/sharepoint
```
プロンプトが表示されたら、以下の値を入力します (以下で省略されたすべてのプロンプトに対して既定のオプションを選択します)。
- ソリューション名は何ですか?: spfx-custom-field-extension
- どの種類のクライアント側コンポーネントを作成しますか?: 拡張機能
- どの種類のクライアント側拡張機能を作成しますか? フィールドカスタマイザー
- フィールドカスタマイザーの名前は何ですか? CustomColorField
- どのテンプレートを使用しますか?: JavaScript なしのフレームワーク
Visual Studio Code (または選択した他のコードエディター) を起動し、ソリューションの開発を開始します。 Visual Studio Code を開始するには、次のステートメントを実行します。
```
code .
```

JavaScript で新しいフィールドカスタマイザーを定義する

JSLink カスタムフィールドの表示と同じ動作を再現するには、新しい SharePoint Framework ソリューション内で、クライアント側のコードを使用して同じロジックを実装する必要があります。このタスクを実現するには、次の操作を行います。

ファイル ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.manifest.json を開きます。 id プロパティの値をコピーします。この値は後で必要になるため、安全な場所に保存します。

ファイル ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.ts を開き、次のコードスニペットに従ってコンテンツを編集します。

import { Log } from '@microsoft/sp-core-library';
import { override } from '@microsoft/decorators';
import {
  BaseFieldCustomizer,
  IFieldCustomizerCellEventParameters
} from '@microsoft/sp-listview-extensibility';

import * as strings from 'CustomColorFieldFieldCustomizerStrings';
import styles from './CustomColorFieldFieldCustomizer.module.scss';

/**
* If your field customizer uses the ClientSideComponentProperties JSON input,
* it will be deserialized into the BaseExtension.properties object.
* You can define an interface to describe it.
*/
export interface ICustomColorFieldFieldCustomizerProperties {
  // This is an example; replace with your own property
  sampleText?: string;
}

const LOG_SOURCE: string = 'CustomColorFieldFieldCustomizer';

export default class CustomColorFieldFieldCustomizer
extends BaseFieldCustomizer<ICustomColorFieldFieldCustomizerProperties> {

  @override
  public onInit(): Promise<void> {
    // Add your custom initialization to this method.  The framework will wait
    // for the returned promise to resolve before firing any BaseFieldCustomizer events.
    Log.info(LOG_SOURCE, 'Activated CustomColorFieldFieldCustomizer with properties:');
    Log.info(LOG_SOURCE, JSON.stringify(this.properties, undefined, 2));
    Log.info(LOG_SOURCE, `The following string should be equal: "CustomColorFieldFieldCustomizer" and "${strings.Title}"`);
    return Promise.resolve();
  }

  @override
  public onRenderCell(event: IFieldCustomizerCellEventParameters): void {

    var colorField = event.fieldValue;

    // Declare a local variable to hold the output color
    var color = '';

    // Evaluate the values of the 'Color' field and render it accordingly
    switch (colorField)
    {
      case 'Red':
        color = 'red';
        break;
      case 'Green':
        color = 'green';
        break;
      case 'Blue':
        color = 'blue';
        break;
      case 'Yellow':
        color = 'yellow';
        break;
      default:
        color = 'white';
        break;
    }

    // Render the output for the 'Color' field
    event.domElement.innerHTML = "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />";
  }

  @override
  public onDisposeCell(event: IFieldCustomizerCellEventParameters): void {
    // This method should be used to free any resources that were allocated during rendering.
    // For example, if your onRenderCell() called ReactDOM.render(), then you should
    // call ReactDOM.unmountComponentAtNode() here.
    super.onDisposeCell(event);
  }
}

ご覧のとおり、メソッド onRenderCell() のコンテンツは JSLink 実装のこれまでの RenderColorField() とほぼ同じです。違いは次の点のみです。

現在のフィールド値を取得するには、onRenderCell() メソッドの入力引数の event.fieldValue プロパティを読み取る必要があります。
カスタムの HTML コードに戻ってフィールドを表示するには、フィールド表示の出力 HTML コンテナーを表す event.domElement オブジェクトの innerHTML プロパティに値を割り当てる必要があります。

これらのわずかな変更の他は、今までとほぼ同じ JavaScript コードを再利用できます。

次の図では、出力結果を確認できます。

デバッグモードでソリューションをテストする

コンソールウィンドウに戻り、次のコマンドを実行してソリューションを構築し、それをホストするローカル Node.js サーバーを実行します。
```
gulp serve --nobrowser
```
お気に入りのブラウザーを開いて "モダン" なリストに移動すると、名前が "Color" で、種類が Choice のカスタムフィールドと、これまでと同じ値のオプション (Red、Green、Blue、Yellow) が表示されます。最終的には、新しい "モダン" なエクスペリエンスで "クラシック" サイトで作成したリストを表示し、使用することができます。ここで、以下のクエリ文字列パラメーターを AllItems.aspx ページの URL に追加します。
```
?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Color":{"id":"c3070978-d85e-4298-8758-70b5b5933076"}}
```
このクエリ文字列では、GUID を CustomColorFieldFieldCustomizer.manifest.json ファイルから保存した id 値と置き換え、Color プロパティ名はカスタマイズするフィールドの名前を参照します。必要な場合は、フィールドカスタマイザーを構築するための追加パラメーターとして、JSON 形式でシリアル化したカスタム構成オブジェクトを提供できます。

ページ要求を実行すると、セキュリティ上の理由から、"デバッグスクリプトを許可しますか?" という警告メッセージボックスが表示され、ローカルホストからのコード実行への同意を求められます。ソリューションをローカルでデバッグしてテストする場合は、"デバッグスクリプトを読み込む" ことをそれに許可する必要があります。

注:

または、プロジェクトの config/serve.json ファイルに serve 構成エントリを作成して、「SharePoint のモダンページでの SharePoint Framework ソリューションのデバッグ」で説明されているように、デバッグクエリ文字列パラメーターの作成を自動化することもできます。

TypeScript で新しいフィールドカスタマイザーを定義する

これで、JavaScript コードを TypeScript に置き換えて、TypeScript の完全に型指定された手法を活用できるようになりました。

ファイル ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.module.scss を開きます。このファイルは Sass CSS であり、フィールドカスタマイザーの UI 形式を表します。 SCSS ファイルの内容を次のように置き換えます。

.CustomColorField {
  .cell {
    float: left;
    width: 20px;
    height: 20px;
    margin: 5px;
    border: 1px solid rgba(0,0,0,.2);
  }

  .cellRed {
    background: red;
  }

  .cellGreen {
    background: green;
  }

  .cellBlue {
    background: blue;
  }

  .cellYellow {
    background: yellow;
  }

  .cellWhite {
    background: white;
  }
}

onRenderCell() メソッドの実装を次のコードの抜粋と置き換えます。

@override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  // Read the current field value
  let colorField: String = event.fieldValue;

  // Add the main style to the field container element
  event.domElement.classList.add(styles.CustomColorField);

  // Get a reference to the output HTML
  let fieldHtml: HTMLDivElement = event.domElement.firstChild as HTMLDivElement;

  // Add the standard style
  fieldHtml.classList.add(styles.cell);

  // Add the colored style
  switch(colorField)
  {
    case "Red":
      fieldHtml.classList.add(styles.cellRed);
      break;
    case "Green":
      fieldHtml.classList.add(styles.cellGreen);
      break;
    case "Blue":
      fieldHtml.classList.add(styles.cellBlue);
      break;
    case "Yellow":
      fieldHtml.classList.add(styles.cellYellow);
      break;
    default:
      fieldHtml.classList.add(styles.cellWhite);
      break;
  }
}

新しいメソッド実装では、完全に型指定された手法を使用し、cell CSS クラスを現在のフィールド要素の DIV 要素の子に割り当てます。同時に、別のカスタム CSS クラスでは現在選択しているフィールドの値に基づき、DIV のターゲットの色を定義します。

フィールドカスタマイザーをデバッグモードでもう一度実行し、結果を確認します。

ソリューションをパッケージ化してホストする

結果に問題がなければ、ソリューションをパッケージ化して実際のホスティングインフラストラクチャでホストする準備が整ったことになります。バンドルとパッケージを構築する前に、拡張機能をプロビジョニングするために XML フィーチャーフレームワークファイルを宣言する必要があります。

フィーチャーフレームワーク要素を確認する

コードエディターで、/sharepoint/assets/elements.xml ファイルを開きます。次のコードの引用部分で、ファイルがどのようなものかを確認できます。
```
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Field ID="{40475661-efaf-447a-a220-c992b20ec1c3}"
           Name="SPFxColor"
           DisplayName="Color"
           Title="Color"
           Type="Choice"
           Required="FALSE"
           Group="SPFx Columns"
           ClientSideComponentId="c3070978-d85e-4298-8758-70b5b5933076">
    </Field>
</Elements>
```
ご覧のとおり、SharePoint フィーチャーフレームワークファイルを思い起こさせますが、これはフィールド種類を Choice としてカスタム Field 要素を定義します。この要素は ClientSideComponentId 属性を使用してフィールドカスタマイザーの id を参照します。また、拡張機能で必要なカスタム構成プロパティを構成する ClientSideComponentProperties 属性もあります。

ファイル ./config/package-solution.json を開きます。ファイル内の assets セクションに elements.xml ファイルへの参照があることがわかります。

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-custom-field-extension-client-side-solution",
    "id": "ab0fbbf8-01ba-4633-8498-46cfd5652619",
    "version": "1.0.0.0",
    "features": [{
      "title": "Application Extension - Deployment of custom action.",
      "description": "Deploys a custom action with ClientSideComponentId association",
      "id": "090dc976-878d-44fe-8f8e-ac603d094aa1",
      "version": "1.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml"
        ]
      }
    }]
  },
  "paths": {
    "zippedPackage": "solution/spfx-custom-field-extension.sppkg"
  }
}

ソリューションをバンドル、パッケージ化、および展開する

次に、アプリカタログへのソリューションバンドルをバンドルしてパッケージ化する必要があります。このタスクを実行するには、次の手順に従ってください。

SharePoint Online テナントのソリューションを準備して展開します。

次のタスクを実行して、ソリューションをバンドルします。これにより、プロジェクトのリリースビルドが実行されます。
```
gulp bundle --ship
```
次のタスクを実行して、ソリューションをパッケージ化します。このコマンドは、sharepoint/solution フォルダーに *.sppkg パッケージを作成します。
```
gulp package-solution --ship
```
新しく作成したクライアント側ソリューションパッケージを、テナント内のアプリカタログにアップロードまたはドラッグアンドドロップし、[展開] ボタンを選択します。

ソリューションのインストールと実行

ブラウザーを開き、任意の "モダン" ターゲットサイトに移動します。
[サイトコンテンツ] ページに移動し、新しいアプリの追加を選択します。
[組織から] でインストールする新しいアプリを選択して、アプリカタログで使用可能なソリューションを参照します。
spfx-custom-field-extension-client-side-solution というソリューションを選択し、ターゲットサイトにインストールします。
アプリケーションのインストールが完了した後、新しいカスタムリストを作成し、リストの設定を編集して、既存のサイト列から新しい列を追加します。 SPFx Columns と呼ばれる列のグループを選択し、Color フィールドを追加します。
ここで追加したフィールドを編集し、いくつかの色の値 (Red, Green, Blue, Yellow など) を構成し、フィールド設定を保存します。
いくつかの項目をリストに追加し、リストビューで出力を確認します。これは次のスクリーンショットのように表示されます。

SharePoint Framework 拡張機能を使用してビルドされた新しいフィールドカスタマイザーをお試しください。

次の方法で共有

JSLink から SharePoint Framework 拡張機能への移行

新しい SharePoint Framework ソリューションの作成

JavaScript で新しいフィールドカスタマイザーを定義する

デバッグモードでソリューションをテストする

TypeScript で新しいフィールドカスタマイザーを定義する

ソリューションをパッケージ化してホストする

フィーチャーフレームワーク要素を確認する

ソリューションをバンドル、パッケージ化、および展開する

ソリューションのインストールと実行

関連項目

その他のリソース

次の方法で共有

JSLink から SharePoint Framework 拡張機能への移行

新しい SharePoint Framework ソリューションの作成

JavaScript で新しいフィールド カスタマイザーを定義する

デバッグ モードでソリューションをテストする

TypeScript で新しいフィールド カスタマイザーを定義する

ソリューションをパッケージ化してホストする

フィーチャー フレームワーク要素を確認する

ソリューションをバンドル、パッケージ化、および展開する

ソリューションのインストールと実行

関連項目

その他のリソース

JavaScript で新しいフィールドカスタマイザーを定義する

デバッグモードでソリューションをテストする

TypeScript で新しいフィールドカスタマイザーを定義する

フィーチャーフレームワーク要素を確認する