事前構成済みのエントリを使用して Web パーツの追加を簡略化する

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

SharePoint Framework のクライアント側 Web パーツは、複雑になるほどユーザーが構成する必要のあるプロパティの数が多くなる傾向があります。具体的なシナリオに対応するように事前構成されたプロパティのエントリを追加することで、ユーザーを補助できます。事前構成済みのエントリにより、Web パーツは事前設定された値で初期化されることになります。

注:

この記事の手順を実行する前に、必ず SharePoint のクライアント側 Web パーツ開発環境を設定しておいてください。

警告

SharePoint Server 2016 を対象とする SPFx ソリューションは、構成済みエントリとして 1 つの Web パーツプロパティのみを設定することに制限されています。詳細については、「issue #5260」を参照してください。

Web パーツの事前構成済みのエントリ

SharePoint フレームワークのクライアント側 Web パーツはすべて、次の 2 つの要素で構成されます。

Web パーツを説明するマニフェスト
Web パーツコード

Web パーツのマニフェストで指定されるプロパティの 1 つに、preconfiguredEntries プロパティがあります。

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",

  "id": "6737645a-4443-4210-a70e-e5e2a219133a",
  "alias": "GalleryWebPart",
  "componentType": "WebPart",
  "version": "0.0.1",
  "manifestVersion": 2,

  "preconfiguredEntries": [{
    "groupId": "1edbd9a8-0bfb-4aa2-9afd-14b8c45dd489", // Discovery
    "group": { "default": "Under Development" },
    "title": { "default": "Gallery" },
    "description": { "default": "Shows items from the selected list" },
    "officeFabricIconFontName": "Page",
    "properties": {
      "description": "Gallery"
    }
  }]
}

preconfiguredEntries プロパティは、Web パーツツールボックスで使用する Web パーツについての情報を提供します。ユーザーが Web パーツをページに追加するときに、preconfiguredEntries プロパティの情報が、ツールボックスに Web パーツを表示するために使用されます。また、この情報によってページに Web パーツが追加されたときの既定の設定を定義します。

完全信頼ソリューションを使用してクラシック Web パーツを構築した場合、配列内 preconfiguredEntries の各エントリは *.webpart ファイルに対応すると考えることができます。 *.webpart ファイルと同様に、プロパティ内のpreconfiguredEntries各エントリは Web パーツコードにリンクされ、Web パーツに関する基本情報 (タイトルや説明など) とそのプロパティの既定値を指定します。

`preconfiguredEntries` 配列の項目のプロパティ

preconfiguredEntries 配列の各項目は、複数のプロパティで構成されています。次の表では、各プロパティの用途について説明します。

プロパティ名	値の型	必須かどうか	用途	サンプル値
`title`	ILocalizedString	はい	ツールボックスに表示される Web パーツのタイトル。	`"title": { "default": "Weather", "nl-nl": "Weerbericht" }`
`description`	ILocalizedString	はい	ツールボックスのヒントに表示される web パーツの説明。	`"description": { "default": "Shows weather in the given location", "nl-nl": "Toont weerbericht voor de opgegeven locatie" }`
`officeFabricIconFontName`	string	いいえ	ツールボックスに表示される Web パーツのアイコン。この値は、Office UI Fabric アイコン名のいずれかにする必要があります。このプロパティに値を指定すると、`iconImageUrl` プロパティは無視されます。	`"officeFabricIconFontName": "Sunny"`
`iconImageUrl`	string	いいえ	ツールボックスに表示される Web パーツのアイコン。イメージの URL で表されます。 URL にあるイメージは、正確に 40 x 28 ピクセルにする必要があります。 `officeFabricIconName` プロパティに値を設定していない場合は、このプロパティに値を設定する必要があります。	`"iconImageUrl": "https://cdn.contoso.com/weather.png"`
`groupId`	string	はい	モダンサイトページで、Web パーツがどのモダングループに含まれるかを特定するグループ ID です。 SharePoint Framework は、定義済みのグループ用にグループ ID を予約しています。開発者は、これに該当するグループから 1 つを採用できます。開発者が、定義済みのグループにない ID を入力した場合、その他のグループにフォールバックされます。	`"groupId": "1edbd9a8-0bfb-4aa2-9afd-14b8c45dd489"`
`group`	ILocalizedString	いいえ	従来のページで、Web パーツが含まれる Web パーツピッカーでのグループ名です。値が指定されていない場合、Web パーツはその他 (Miscellaneous) のグループに表示されます。	`"group": { "default": "Content", "nl-nl": "Inhoud" }`
`properties`	TProperties	はい	Web パーツプロパティの既定値を保持するキー/値のペアのオブジェクト。	`"properties": { "location": "Redmond", "numberOfDays": 3, "showIcon": true }`

一部の Web パーツプロパティは ILocalizedString 型の値を保持します。この型は、開発者が、さまざまなロケールの文字列を指定できるキー/値ペアのオブジェクトです。少なくとも、型 ILocalizedString には default の値が含まれている必要があります。

オプションとして、開発者は Web パーツがサポートする別のロケールに翻訳した値を指定することもできます。ローカライズされた設定にリストされていないロケールのページに Web パーツが配置されると、default の値が代用されます。

有効な ILocalizedString 値:

"title": {
  "default": "Weather",
  "nl-nl": "Weerbericht"
}

"title": {
  "default": "Weather"
}

default キーがないために無効になる ILocalizedString 値は次のとおりです。

"title": {
  "en-us": "Weather"
}

定義済みのモダングループ

次の表に示すとおり、すぐに使えるグループは 7 つ用意されています。グループ ID は、groupId プロパティで使用します。

グループ名	ID	グループには次のものが含まれます。
テキスト、メディア、およびコンテンツ	`cf066440-0614-43d6-98ae-0b31cf14c7c3`	テキスト、マルチメディア、ドキュメント、Web からの情報、その他のリッチコンテンツを表示する Web パーツ。
検出	`1edbd9a8-0bfb-4aa2-9afd-14b8c45dd489`	ユーザーが情報を見つけやすくするように、コンテンツを編成、グループ化、フィルターする Web パーツ。
コミュニケーションおよびコラボレーション	`75e22ed5-fa14-4829-850a-c890608aca2d`	情報の共有、チームワーク、ソーシャルの交流を促進する Web パーツ。
計画およびプロセス	`1bc7927e-4a5e-4520-b540-71305c79c20a`	計画ツールおよびプロセスツールの使用によってチームの生産性を向上させる Web パーツ。
ビジネスおよびインテリジェンス	`4aca9e90-eff5-4fa1-bac7-728f5f157b66`	データを追跡および分析するための Web パーツと、ビジネスフローをページに統合するための Web パーツ。
サイトツール	`070951d7-94da-4db8-b06e-9d581f1f55b1`	サイトの情報と管理に向けた Web パーツ。
その他	`5c03119e-3074-46fd-976b-c60198311f70`	他のグループに含まれない Web パーツ。

開発者が、上記のリストにない ID を入力した場合、Web パーツはその他のグループにフォールバックされます。

Web パーツの作成時に、事前構成済みのエントリを使用する方法を確認するために、サンプルのギャラリー Web パーツを作成します。ユーザーは、いくつかのプロパティを使用することで、この Web パーツに特定の方法で選択したリストからの項目を表示するように構成できます。簡潔にするために、実際の Web パーツロジックの実装は省略して、事前構成済みバージョンのギャラリー Web パーツを提供するために preconfiguredEntries プロパティを使用する方法に注目します。

Web パーツが動作するために、ユーザーが構成する必要のある各種プロパティが表示されている Web パーツプロパティのウィンドウ

新しい Web パーツプロジェクトの作成

まず、プロジェクト用の新しいフォルダーを作成します。
```
md react-preconfiguredentries
```
プロジェクトフォルダーに移動します。
```
cd react-preconfiguredentries
```
作成した新しいディレクトリから Yeoman の SharePoint ジェネレーターを実行して、新しいプロジェクトを作成します。
```
yo @microsoft/sharepoint
```
Yeoman の SharePoint ジェネレーターにより、一連の質問メッセージが表示されます。次の質問以外のすべての質問について、既定のオプションをそのまま受け入れます。
- どの種類のクライアント側コンポーネントを作成しますか? WebPart
- Web パーツ名は何ですか? ギャラリー
- どのテンプレートを使用しますか? React
コードエディターでプロジェクトフォルダーを開きます。この記事の手順とスクリーンショットでは Visual Studio Code を使用していますが、実際は任意のエディターを使用できます。

Web パーツプロパティを追加する

Web パーツのマニフェストに、Web パーツプロパティを追加して、ユーザーがギャラリー Web パーツを構成できるようにします。

コードエディターで、./src/webparts/gallery/GalleryWebPart.manifest.json ファイルを開きます。
properties セクションを次の JSON に置き換えます。
```
{
  //...
  "preconfiguredEntries": [{
    //...
    "properties": {
      "listName": "",
      "order": "",
      "numberOfItems": 10,
      "style": ""
    }
  }]
}
```
このコードについては、次の点に注意してください。
- listName: リストの名前を指定します (このリストのリスト項目が表示されます)。
- order: 項目の表示順序 (日付の昇順または日付の降順) を指定します。
- numberOfItems: 表示する項目数を指定します。
- style: 項目の表示方法 (イメージの表示に便利なサムネイルやドキュメントに適したリストなど) を指定します。
マニフェストで指定した Web パーツプロパティは、Web パーツのプロパティインターフェイスにも追加する必要があります。
コードエディタで、./src/webparts/gallery/IGalleryWebPartProps.ts ファイルを開きます。次に示すように、コードを変更します
```
export interface IGalleryWebPartProps {
  listName: string;
  order: string;
  numberOfItems: number;
  style: string;
}
```
SharePoint Framework のクライアント側 Web パーツの作成に React を使用している場合は、Web パーツプロパティのインターフェイスを変更した後で、そのインターフェイスを使用してメインの React コンポーネントのインスタンスを作成するように、Web パーツの render() メソッドを更新する必要があります。

コードエディターで、./src/webparts/gallery/GalleryWebPart.ts ファイルを開きます。次に示すように、Web パーツの render() メソッドを変更します。

export default class GalleryWebPart extends BaseClientSideWebPart<IGalleryWebPartProps> {
  // ...
  public render(): void {
    const element: React.ReactElement<IGalleryProps> = React.createElement(Gallery, {
      listName: this.properties.listName,
      order: this.properties.order,
      numberOfItems: this.properties.numberOfItems,
      style: this.properties.style
    });

    ReactDom.render(element, this.domElement);
  }
  // ...
}

プロパティの値を表示するように、メインの React コンポーネントを更新します。 Web パーツの構成が済んでいない場合は、標準の Web パーツプレースホルダーが表示されます。コードエディターで、./src/webparts/gallery/components/Gallery.tsx ファイルを開き、次に示すようにコードを変更します。

import * as React from 'react';
import styles from './Gallery.module.scss';
import { IGalleryProps } from './IGalleryProps';

export default class Gallery extends React.Component<IGalleryProps, void> {
  public render(): JSX.Element {
    if (this.needsConfiguration()) {
      return <div className="ms-Grid" style={{ color: "#666", backgroundColor: "#f4f4f4", padding: "80px 0", alignItems: "center", boxAlign: "center" }}>
        <div className="ms-Grid-row" style={{ color: "#333" }}>
          <div className="ms-Grid-col ms-u-hiddenSm ms-u-md3"></div>
          <div className="ms-Grid-col ms-u-sm12 ms-u-md6" style={{ height: "100%", whiteSpace: "nowrap", textAlign: "center" }}>
            <i className="ms-fontSize-su ms-Icon ms-Icon--ThumbnailView" style={{ display: "inline-block", verticalAlign: "middle", whiteSpace: "normal" }}></i><span className="ms-fontWeight-light ms-fontSize-xxl" style={{ paddingLeft: "20px", display: "inline-block", verticalAlign: "middle", whiteSpace: "normal" }}>Gallery</span>
          </div>
          <div className="ms-Grid-col ms-u-hiddenSm ms-u-md3"></div>
        </div>
        <div className="ms-Grid-row" style={{ width: "65%", verticalAlign: "middle", margin: "0 auto", textAlign: "center" }}>
          <span style={{ color: "#666", fontSize: "17px", display: "inline-block", margin: "24px 0", fontWeight: 100 }}>Show items from the selected list</span>
        </div>
        <div className="ms-Grid-row"></div>
      </div>;
    }
    else {
      return (
        <div className={styles.gallery}>
          <div className={styles.container}>
            <div className={`ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}`}>
              <div className='ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1'>
                <span className="ms-font-xl ms-fontColor-white">
                  Welcome to SharePoint!
                </span>
                <p className='ms-font-l ms-fontColor-white'>
                  Customize SharePoint experiences using web parts.
                </p>
                <p className='ms-font-l ms-fontColor-white'>
                  List: {this.props.listName}<br />
                  Order: {this.props.order}<br />
                  Number of items: {this.props.numberOfItems}<br />
                  Style: {this.props.style}
                </p>
                <a href="https://aka.ms/spfx" className={styles.button}>
                  <span className={styles.label}>Learn more</span>
                </a>
              </div>
            </div>
          </div>
        </div>
      );
    }
  }

  private needsConfiguration(): boolean {
    return Gallery.isEmpty(this.props.listName) ||
      Gallery.isEmpty(this.props.order) ||
      Gallery.isEmpty(this.props.style);
  }

  private static isEmpty(value: string): boolean {
    return value === undefined ||
      value === null ||
      value.length === 0;
  }
}

すべての Web パーツプロパティをこのコンポーネントにバイパスするため、React の主要コンポーネントインターフェイスが Web パーツプロパティインターフェイスと一致するように更新します。コードエディターで、./src/webparts/gallery/components/IGalleryProps.ts ファイルを開き、次のようにコードを変更します。
```
import { IGalleryWebPartProps } from '../IGalleryWebPartProps';

export interface IGalleryProps extends IGalleryWebPartProps { }
```

Web パーツプロパティをプロパティウィンドウに表示する

新しく定義した Web パーツを構成するためのプロパティをユーザーが使用するようにするには、そうしたプロパティを Web パーツプロパティのウィンドウに表示する必要があります。

コードエディターで、./src/webparts/gallery/GalleryWebPart.ts ファイルを開きます。ファイルの最上部のセクションで、次に示すように @microsoft/sp-webpart-base の import ステートメントを変更します。
```
import {
  BaseClientSideWebPart
} from '@microsoft/sp-webpart-base';
import {
  IPropertyPaneConfiguration,
  PropertyPaneDropdown,
  PropertyPaneSlider,
  PropertyPaneChoiceGroup
} from '@microsoft/sp-property-pane';
```

propertyPaneSettings を次のように変更します。

export default class GalleryWebPart extends BaseClientSideWebPart<IGalleryWebPartProps> {
  // ...
  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: {
            description: strings.PropertyPaneDescription
          },
          groups: [
            {
              groupName: strings.BasicGroupName,
              groupFields: [
                PropertyPaneDropdown('listName', {
                  label: strings.ListNameFieldLabel,
                  options: [{
                    key: 'Documents',
                    text: 'Documents'
                  },
                  {
                    key: 'Images',
                    text: 'Images'
                  }]
                }),
                PropertyPaneChoiceGroup('order', {
                  label: strings.OrderFieldLabel,
                  options: [{
                    key: 'chronological',
                    text: strings.OrderFieldChronologicalOptionLabel
                  },
                  {
                    key: 'reversed',
                    text: strings.OrderFieldReversedOptionLabel
                  }]
                }),
                PropertyPaneSlider('numberOfItems', {
                  label: strings.NumberOfItemsFieldLabel,
                  min: 1,
                  max: 10,
                  step: 1
                }),
                PropertyPaneChoiceGroup('style', {
                  label: strings.StyleFieldLabel,
                  options: [{
                    key: 'thumbnails',
                    text: strings.StyleFieldThumbnailsOptionLabel
                  },
                  {
                    key: 'list',
                    text: strings.StyleFieldListOptionLabel
                  }]
                })
              ]
            }
          ]
        }
      ]
    };
  }
}

現実のシナリオでは、現在の SharePoint サイトからリストのリストを取得することになるでしょう。簡潔にするために、この例では固定されたリストを使用することにします。

ローカライズしたラベルを追加する

コードエディタで、./src/webparts/gallery/loc/mystrings.d.ts ファイルを開きます。次に示すように、コードを変更します

declare interface IGalleryStrings {
  PropertyPaneDescription: string;
  BasicGroupName: string;
  ListNameFieldLabel: string;
  OrderFieldLabel: string;
  OrderFieldChronologicalOptionLabel: string;
  OrderFieldReversedOptionLabel: string;
  NumberOfItemsFieldLabel: string;
  StyleFieldLabel: string;
  StyleFieldThumbnailsOptionLabel: string;
  StyleFieldListOptionLabel: string;
}

declare module 'galleryStrings' {
  const strings: IGalleryStrings;
  export = strings;
}

不足しているリソース文字列を追加するために、./src/webparts/gallery/loc/en-us.js ファイルを開いて、次に示すようにコードを変更します。

define([], function() {
  return {
    "PropertyPaneDescription": "Description",
    "BasicGroupName": "Group Name",
    "ListNameFieldLabel": "List",
    "OrderFieldLabel": "Items order",
    "OrderFieldChronologicalOptionLabel": "chronological",
    "OrderFieldReversedOptionLabel": "reversed chronological",
    "NumberOfItemsFieldLabel": "Number of items to show",
    "StyleFieldLabel": "Items display style",
    "StyleFieldThumbnailsOptionLabel": "thumbnails",
    "StyleFieldListOptionLabel": "list"
  }
});

次のコマンドを実行し、プロジェクトがビルドされていることを確認します。
```
gulp serve
```
Web ブラウザーで、キャンバスに Web パーツを追加して、その Web パーツのプロパティウィンドウを開きます。ユーザーが構成に使用できるプロパティがすべて表示されます。

Web パーツの既定値を一切指定していないため、ユーザーは、Web パーツをページに追加するたびに、まず、その Web パーツの構成が必要になります。この操作は、最も一般的なシナリオに対応した既定値を指定することで簡略化できます。

Web パーツの既定値を指定する

ユーザーは、ほとんどの場合、最近追加された 5 つのイメージを表示するためにギャラリー Web パーツを使用すると想定します。ユーザーに Web パーツを毎回手動で構成するように求めるのではなく、正しい設定を使用した事前構成済みのバージョンを提供するようにします。

コードエディターで、./src/webparts/gallery/GalleryWebPart.manifest.json ファイルを開きます。次に示すように、preconfiguredEntries プロパティの既存のエントリを変更します。

{
  // ...
  "preconfiguredEntries": [{
    "groupId": "6737645a-4443-4210-a70e-e5e2a219133a",
    "group": { "default": "Content" },
    "title": { "default": "Recent images" },
    "description": { "default": "Shows 5 most recent images" },
    "officeFabricIconFontName": "Picture",
    "properties": {
      "listName": "Images",
      "order": "reversed",
      "numberOfItems": 5,
      "style": "thumbnails"
    }
  }]
}

次に示すコマンドを実行して、プロジェクトのデバッグを開始します。
```
gulp serve
```
注:

既にプロジェクトをデバッグしている場合は、デバッグを停止してから再開してください。ワークベンチでは、Web パーツのマニフェストに加えた変更がデバッグ中に自動的に反映されることはありません。そうした変更を確認するには、プロジェクトを再ビルドする必要があります。
Web パーツをキャンバスに追加するために、Web パーツツールボックスを開くと、Web パーツの名前とアイコンが、事前構成済みの設定を反映するように変更されることが確認できます。
ページに Web パーツを追加すると、その Web パーツは事前構成済みの設定を使用して、すぐに動作します。

Web パーツの事前構成済みエントリを複数指定する

別のユーザーのグループは、ほとんどの場合、サイトに最近追加されたドキュメントを表示するためにギャラリー Web パーツを使用するとします。こうしたユーザーが Web パーツを簡単に使用できるようにするために、その構成ニーズに対応する別の事前設定のセットを追加できます。

コードエディターで、./src/webparts/gallery/GalleryWebPart.manifest.json ファイルを開きます。 preconfiguredEntries プロパティを次のように変更します。

{
  // ...
  "preconfiguredEntries": [{
    "groupId": "6737645a-4443-4210-a70e-e5e2a219133a",
    "group": { "default": "Content" },
    "title": { "default": "Recent images" },
    "description": { "default": "Shows 5 most recent images" },
    "officeFabricIconFontName": "Picture",
    "properties": {
      "listName": "Images",
      "order": "reversed",
      "numberOfItems": 5,
      "style": "thumbnails"
    }
  },
  {
    "groupId": "6737645a-4443-4210-a70e-e5e2a219133a",
    "group": { "default": "Content" },
    "title": { "default": "Recent documents" },
    "description": { "default": "Shows 10 most recent documents" },
    "officeFabricIconFontName": "Documentation",
    "properties": {
      "listName": "Documents",
      "order": "reversed",
      "numberOfItems": 10,
      "style": "list"
    }
  }]
}

前述の事前構成済みエントリを維持しながら、異なる値をプロパティに使用することにより、別の事前構成済みエントリを並べて追加する方法に注目してください。
結果を確認するには、次に示すコマンドを実行して、プロジェクトのデバッグを開始します。
```
gulp serve
```
キャンバスに Web パーツを追加するために、Web パーツツールボックスを開くと、選択肢として 2 つの Web パーツが表示されることを確認できます。
Recent documents Web パーツをページに追加すると、この Web パーツは固有の事前構成済みの設定を使用して、すぐに動作します。

構成されていない Web パーツのインスタンスを指定する

多くの場合、Web パーツを作成するときには、その Web パーツがサポートすることになる特定のシナリオが存在します。そうしたシナリオに対応する事前構成済みのエントリを指定することで、Web パーツはユーザーにとって扱いやすいものになります。

Web パーツの作成方法によっては、それとは別の想定外のシナリオをサポートできるようにすることも可能です。特定の事前構成済みのエントリのみを提供すると、ユーザーは、Web パーツを別のシナリオに使用できることに気づかないことがあります。構成されていない汎用的なバリエーションの Web パーツも用意することは優れたアイデアといえます。

コードエディターで、./src/webparts/gallery/GalleryWebPart.manifest.json ファイルを開きます。 preconfiguredEntries プロパティを次のように変更します。

{
  // ...
  "preconfiguredEntries": [{
    "groupId": "6737645a-4443-4210-a70e-e5e2a219133a",
    "group": { "default": "Content" },
    "title": { "default": "Recent images" },
  "description": { "default": "Shows 5 most recent images" },
    "officeFabricIconFontName": "Picture",
    "properties": {
      "listName": "Images",
      "order": "reversed",
      "numberOfItems": 5,
      "style": "thumbnails"
    }
  },
  {
    "groupId": "6737645a-4443-4210-a70e-e5e2a219133a",
    "group": { "default": "Content" },
    "title": { "default": "Recent documents" },
    "description": { "default": "Shows 10 most recent documents" },
    "officeFabricIconFontName": "Documentation",
    "properties": {
      "listName": "Documents",
      "order": "reversed",
      "numberOfItems": 10,
      "style": "list"
    }
  },
  {
    "groupId": "6737645a-4443-4210-a70e-e5e2a219133a",
    "group": { "default": "Content" },
    "title": { "default": "Gallery" },
    "description": { "default": "Shows items from the selected list" },
    "officeFabricIconFontName": "CustomList",
    "properties": {
      "listName": "",
      "order": "",
      "numberOfItems": 5,
      "style": ""
    }
  }]
}

汎用的な構成されていないバージョンの Web パーツが、特定のシナリオを対象とした構成に並べて追加されることに注目してください。これにより、ユーザーのニーズに対応する特定の構成がない場合は、常に汎用バージョンを使用し、要件に従って構成できます。
結果を確認するには、次に示すコマンドを実行して、プロジェクトのデバッグを開始します。
```
gulp serve
```
キャンバスに Web パーツを追加するために Web パーツツールボックスを開くと、選択肢として 3 つの Web パーツが表示されるようになったことを確認できます。

事前構成済みのエントリを使用して Web パーツの追加を簡略化する

Web パーツの事前構成済みのエントリ

preconfiguredEntries 配列の項目のプロパティ

定義済みのモダン グループ

新しい Web パーツ プロジェクトの作成

Web パーツ プロパティを追加する

Web パーツ プロパティをプロパティ ウィンドウに表示する