事前構成済みのエントリを使用して Web パーツの追加を簡略化する
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 パーツ プロジェクトの作成
まず、プロジェクト用の新しいフォルダーを作成します。
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 パーツが表示されるようになったことを確認できます。