Web パーツのプロパティ値を検証するValidate web part property values

ユーザーは SharePoint Framework のクライアント側 Web パーツで作業するとき、自分のニーズを満たすために、プロパティを使用してパーツを構成できます。When working with SharePoint Framework client-side web parts, users can configure them to meet their needs by using their properties. 指定された構成値を検証すると、Web パーツの構成がユーザーにとってより容易になり、Web パーツの操作の全体的なユーザー エクスペリエンスが向上します。By validating the provided configuration values, you can make it easier for users to configure the web part and improve the overall user experience of working with your web part.

注意

この記事の手順を実行する前に、SharePoint Framework ソリューションをビルドするための開発環境を設定してください。Before following the steps in this article, be sure to set up your development environment for building SharePoint Framework solutions.

新しい Web パーツ プロジェクトの作成Create a new web part project

  1. まず、プロジェクト用の新しいフォルダーを作成します。Start by creating a new folder for your project.

    md react-listinfo
    
  2. プロジェクト フォルダーに移動します。Go to the project folder.

    cd react-listinfo
    
  3. プロジェクト フォルダーで SharePoint Framework Yeoman ジェネレーターを実行し、新しい SharePoint Framework プロジェクトをスキャホールディングします。In the project folder, run the SharePoint Framework Yeoman generator to scaffold a new SharePoint Framework project.

    yo @microsoft/sharepoint
    
  4. ダイアログ ボックスが表示されたら、次の値を入力します。When prompted, enter the following values:

    • react-listinfo: ソリューション名react-listinfo as your solution name
    • Use the current folder: ファイルの配置場所Use the current folder for the location to place the files
    • React: Web パーツをビルドする開始点React as the starting point to build the web part
    • List info: Web パーツ名List info as your web part name
    • Shows information about the selected list: Web パーツの説明Shows information about the selected list as your web part description

    既定の選択肢を指定した SharePoint Framework Yeoman ジェネレーター

  5. スキャフォールディングが完了したら、次のコマンドを実行して、プロジェクトの依存関係のバージョンをロック ダウンします。After the scaffolding completes, lock down the version of the project dependencies by running the following command:

    npm shrinkwrap
    
  6. コード エディターでプロジェクト フォルダーを開きます。Next, open your project folder in your code editor. この記事の手順とスクリーンショットでは Visual Studio Code を使用していますが、お好きなエディターをどれでも使用できます。This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer.

    Visual Studio Code で開いた SharePoint Framework プロジェクト


Web パーツのプロパティを検証するためのオプションOptions for validating web part properties

SharePoint Framework では、開発者が Web パーツのプロパティの値を検証する方法が 2 つ用意されています。SharePoint Framework offers developers two ways to validate values of web part properties. Web パーツのコード内で値を直接検証する方法と、外部 API を呼び出してそこで検証を実行する方法です。You can validate the value directly, inside a web part's code, or you can call an external API to perform the validation there.

値のインライン検証は、最小/最大長、必須プロパティ、または郵便番号のような単純なパターン認識などの、単純な検証を実行する場合に便利です。Validating values inline is useful for performing simple validations such as minimal/maximum length, required properties, or simple pattern recognition, like a zip code. 社会保障番号やセキュリティ グループのメンバーシップのチェックなどのビジネス ロジックに基づく検証の場合は、外部 API を呼び出すほうが優れています。Whenever the validation is based on business logic, such as checking a social security number or a security group membership, calling external APIs is a better approach.

Web パーツのプロパティの値を検証するには、その特定のプロパティの onGetErrorMessage イベントのイベント ハンドラーを実装する必要があります。To validate the value of a web part property, you have to implement the event handler for the onGetErrorMessage event of that particular property. インライン検証の場合、イベント ハンドラーは検証エラーを含む文字列か、空の文字列 (指定された値が有効な場合) を返す必要があります。For inline validation, the event handler should return a string with the validation error or an empty string if the provided value is valid.

リモート API を使用する検証では、イベント ハンドラーは文字列の Promise を返します。For validation using remote APIs, the event handler returns a promise of string. 指定された値が無効の場合、Promise はエラー メッセージに解決されます。If the provided value is invalid, the promise resolves with the error message. 指定された値が有効な場合、Promise は空の文字列に解決されます。If the provided value is valid, the promise resolves with an empty string.

Web パーツのプロパティ値をインライン検証するValidate web part property values inline

この手順では、description Web パーツ プロパティが指定されていることと、その値が 40 文字を超えないことを確認します。In this step you verify that the description web part property is specified and its value is not longer than 40 characters. これをインライン検証プロセスを使用して行います。You do this by using the inline validation process.

  1. コード エディターで、./src/webparts/listInfo/ListInfoWebPart.ts ファイルを開きます。In the code editor, open the ./src/webparts/listInfo/ListInfoWebPart.ts file. 次のコードで ListInfoWebPart クラスに validateDescription メソッドを追加します。In the ListInfoWebPart class, add the validateDescription method with the following code:

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
     // ...
    
     private validateDescription(value: string): string {
       if (value === null ||
         value.trim().length === 0) {
         return 'Provide a description';
       }
    
       if (value.length > 40) {
         return 'Description should not be longer than 40 characters';
       }
    
       return '';
     }
    }
    

    validateDescription メソッドは、説明が指定されているかどうか、およびそれが 40 文字を超えていないかどうかを確認します。The validateDescription method checks if the description is provided, and if it isn't longer than 40 characters. 指定された説明が無効な場合、メソッドは検証エラーに対応するエラー メッセージを返します。If the provided description is invalid, the method returns an error message corresponding to the validation error. 指定された値が正しい場合、空の文字列を返します。If the provided value is correct, it returns an empty string.

  2. validateDescription メソッドを description Web パーツ プロパティと関連付けます。Associate the validateDescription method with the description web part property. ListInfoWebPart クラスの getPropertyPaneConfiguration メソッドの実装を次のように変更します。In the ListInfoWebPart class, change the implementation of the getPropertyPaneConfiguration method to:

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
     // ...
    
     protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
       return {
         pages: [
           {
             header: {
               description: strings.PropertyPaneDescription
             },
             groups: [
               {
                 groupName: strings.BasicGroupName,
                 groupFields: [
                   PropertyPaneTextField('description', {
                     label: strings.DescriptionFieldLabel,
                     onGetErrorMessage: this.validateDescription.bind(this)
                   })
                 ]
               }
             ]
           }
         ]
       };
     }
    
     // ...
    }
    

    validateDescription メソッドを onGetErrorMessage イベントのイベント ハンドラーとして定義して、description Web パーツの定義を拡張しました。You have extended the definition of the description web part by defining the validateDescription method as the event handler for the onGetErrorMessage event.

  3. 検証の結果を表示するには、次のコマンドを実行します。Run the following command to see the result of the validation:

    gulp serve
    
  4. ワークベンチで、キャンバスに Web パーツを追加して、そのプロパティを開きます。In the Workbench, add the web part to the canvas and open its properties. 説明を削除すると、最初の検証エラーが表示されます。If you remove the description, you should see the first validation error.

    値が指定されていない必須プロパティに対して表示される検証エラー

  5. 40 文字を超える値を指定します。Provide a value that's longer than 40 characters. テキスト フィールドの下に別の検証エラーが表示されます。You should see another validation error displayed under the text field.

    指定された値が許容文字数を超える場合に表示される検証エラー

  6. 無効な値を指定すると、有効だった最後の値が Web パーツに表示されることにご注意ください。Notice that when providing an invalid value, the web part is rendered showing the last valid value. さらに、非反応性プロパティ ウィンドウ モードでは、Web パーツのプロパティの 1 つが無効な場合、ユーザーが無効な構成を適用することを防ぐため、[適用] ボタンが無効になります。Additionally, in the non-reactive property pane mode, if one of the web part properties is invalid, the Apply button is disabled, preventing the user from applying the invalid configuration.

    Web パーツのプロパティの値が無効な場合、無効になった [適用] ボタンが表示される

リモート API を使用して Web パーツのプロパティ値を検証するValidate web part property values using remote APIs

シナリオによっては、Web パーツのプロパティ値の検証がより複雑で、特定のビジネス ロジックが必要になるものがあります。In some scenarios, validating web part property values can be more complex and may require specific business logic. そのような場合には、Web パーツにビジネス ロジックを実装して管理するよりも、既存の API を使用して値を検証するほうが効率的な可能性があります。In such cases, it might be more efficient for you to validate the value by using an existing API rather than implementing and maintaining the business logic in the web part.

この手順では、Web パーツのプロパティに指定された名前を持つリストが、現在の SharePoint サイトに存在するかどうかを確認する検証ロジックを実装します。In this step, you implement validation logic that checks if the list with the name specified in the web part properties exists in the current SharePoint site.

listName Web パーツのプロパティを追加するAdd the listName web part property

  1. コード エディターで、./src/webparts/listInfo/ListInfoWebPart.manifest.json ファイルを開きます。In the code editor, open the ./src/webparts/listInfo/ListInfoWebPart.manifest.json file. properties プロパティに listName という名前の新しいプロパティを追加し、その既定値を空の文字列に設定します。In the properties property, add a new property named listName with the default value set to an empty string:

    {
     "$schema": "https://dev.office.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
     "id": "1ec8f92d-ea55-4584-bf50-bac435c916bf",
     "alias": "ListInfoWebPart",
     "componentType": "WebPart",
    
     // The "*" signifies that the version should be taken from the package.json
     "version": "*",
     "manifestVersion": 2,
    
     // If true, the component can only be installed on sites where Custom Script is allowed.
     // Components that allow authors to embed arbitrary script code should set this to true.
     // https://support.office.com/ja-JP/article/Turn-scripting-capabilities-on-or-off-1f2c515f-5d7e-448a-9fd7-835da935584f
     "requiresCustomScript": false,
    
     "preconfiguredEntries": [{
       "groupId": "1ec8f92d-ea55-4584-bf50-bac435c916bf",
       "group": { "default": "Under Development" },
       "title": { "default": "List info" },
       "description": { "default": "Shows information about the selected list" },
       "officeFabricIconFontName": "Page",
       "properties": {
         "description": "List info",
         "listName": ""
       }
     }]
    }
    
  2. コード エディターで、./src/webparts/listInfo/IListInfoWebPartProps.ts ファイルを開き、文字列型の listName プロパティでインターフェイスの定義を拡張します。In the code editor, open the ./src/webparts/listInfo/IListInfoWebPartProps.ts file, and extend the interface definition with the listName property of type string.

    export interface IListInfoWebPartProps {
     description: string;
     listName: string;
    }
    
  3. コード エディターで ./src/webparts/listInfo/ListInfoWebPart.ts ファイルを開き、getPropertyPaneConfiguration メソッドの実装を次のように変更すれば、新しい Web パーツのプロパティの追加は終了です。Finish adding the new web part property by opening the ./src/webparts/listInfo/ListInfoWebPart.ts file in the code editor, and changing the implementation of the getPropertyPaneConfiguration method to:

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
     // ...
    
     protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
       return {
         pages: [
           {
             header: {
               description: strings.PropertyPaneDescription
             },
             groups: [
               {
                 groupName: strings.BasicGroupName,
                 groupFields: [
                   PropertyPaneTextField('description', {
                     label: strings.DescriptionFieldLabel,
                     onGetErrorMessage: this.validateDescription.bind(this)
                   }),
                   PropertyPaneTextField('listName', {
                     label: strings.ListNameFieldLabel
                   })
                 ]
               }
             ]
           }
         ]
       };
     }
    
     // ...
    }
    
  4. ./src/webparts/listInfo/loc/mystrings.d.ts ファイルのコードを次のように変更して、欠落している ListNameFieldLabel リソース文字列を追加します。Add the missing ListNameFieldLabel resource string by changing the code of the ./src/webparts/listInfo/loc/mystrings.d.ts file to:

    declare interface IListInfoStrings {
     PropertyPaneDescription: string;
     BasicGroupName: string;
     DescriptionFieldLabel: string;
     ListNameFieldLabel: string;
    }
    
    declare module 'listInfoStrings' {
     const strings: IListInfoStrings;
     export = strings;
    }
    
  5. ./src/webparts/listInfo/loc/en-us.js ファイルのコードを次のように変更します。Change the code of the ./src/webparts/listInfo/loc/en-us.js file to:

    define([], function() {
     return {
       "PropertyPaneDescription": "Description",
       "BasicGroupName": "Group Name",
       "DescriptionFieldLabel": "Description Field",
       "ListNameFieldLabel": "List name"
     }
    });
    
  6. 次のコマンドを実行して、プロジェクトが実行中であること、および新しく追加されたリスト名のプロパティが Web パーツのプロパティ ウィンドウに表示されていることを確認します。Run the following command to verify that the project is running and that the newly added list name property is displayed in the web part property pane:

    gulp serve
    


    Web パーツのプロパティ ウィンドウに表示されるリスト名プロパティ

SharePoint の REST API を使用してリストの名前を検証するValidate the name of the list by using the SharePoint REST API

この手順では、指定されたリスト名を検証し、現在の SharePoint サイトの既存のリストに対応するかどうかを確認します。In this step, you validate the provided list name and check if it corresponds to an existing list on the current SharePoint site.

  1. コード エディターで、./src/webparts/listInfo/ListInfoWebPart.ts ファイルを開き、次の参照を追加します。In the code editor, open the ./src/webparts/listInfo/ListInfoWebPart.ts file, and add the following references:

    import { SPHttpClient, SPHttpClientResponse } from '@microsoft/sp-http';
    import { escape } from '@microsoft/sp-lodash-subset';
    
  2. 次のコードで ListInfoWebPart クラスに validateListName メソッドを追加します。In the ListInfoWebPart class, add the validateListName method with the following code:

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
     // ...
    
     private validateListName(value: string): Promise<string> {
       return new Promise<string>((resolve: (validationErrorMessage: string) => void, reject: (error: any) => void): void => {
         if (value === null ||
           value.length === 0) {
           resolve('Provide the list name');
           return;
         }
    
         this.context.spHttpClient.get(this.context.pageContext.web.absoluteUrl + `/_api/web/lists/getByTitle('${escape(value)}')?$select=Id`, SPHttpClient.configurations.v1)
           .then((response: SPHttpClientResponse): void => {
             if (response.ok) {
               resolve('');
               return;
             }
             else if (response.status === 404) {
               resolve(`List '${escape(value)}' doesn't exist in the current site`);
               return;
             }
             else {
               resolve(`Error: ${response.statusText}. Please try again`);
               return;
             }
           })
           .catch((error: any): void => {
             resolve(error);
           });
       });
     }
    }
    

    まず、validateListName メソッドは、リスト名が指定されているかどうか確認します。指定されていなければ、Promise は関連する検証エラーに解決されます。ユーザーがリスト名を指定していた場合、validateListName メソッドは SPHttpClient を使用して SharePoint REST API を呼び出し、指定された名前のリストが存在するかどうか確認します。First, the validateListName method checks if a list name has been provided. If not, it resolves the promise with a relevant validation error. If the user has provided a list name, the validateListName method uses the SPHttpClient to call the SharePoint REST API and check if the list with the specified name exists.

    指定された名前のリストが現在のサイトに存在する場合、応答は「200 OK」という状態コードを返します。validateListName メソッドは、指定された値が有効なリストを表すことを確認して、Promise を空の文字列に解決します。If the list with the specified name exists on the current site, the response returns a 200 OK status code, and the validateListName method resolves the promise with an empty string, confirming that the provided value represents a valid list.

    指定された名前のリストが存在しない場合には、応答は異なるコードを返します。If the list with the specified name doesn't exist, the response returns a different code. 通常は「404 見つかりません」という応答ですが、他の理由で要求が失敗した場合、別の状態コードが返される可能性があります。Typically, it is a 404 Not Found response, but if the request failed in some other way, a different status code can be returned. どちらの場合にも、validateListName メソッドは、関連したエラー メッセージをユーザーに表示します。In both cases, the validateListName method displays a relevant error message to the user.

    リスト名の検証メソッドを定義したら、次に、listName Web パーツ プロパティの検証ハンドラーとしてそれを構成します。With the list name validation method defined, the next step is to configure it as the validation handler for the listName web part property.

  3. ListInfoWebPart クラスの getPropertyPaneConfiguration メソッドのコードを以下と置き換えます。In the ListInfoWebPart class, replace the code of the getPropertyPaneConfiguration method with:

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
     // ...
    
     protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
       return {
         pages: [
           {
             header: {
               description: strings.PropertyPaneDescription
             },
             groups: [
               {
                 groupName: strings.BasicGroupName,
                 groupFields: [
                   PropertyPaneTextField('description', {
                     label: strings.DescriptionFieldLabel,
                     onGetErrorMessage: this.validateDescription.bind(this)
                   }),
                   PropertyPaneTextField('listName', {
                     label: strings.ListNameFieldLabel,
                     onGetErrorMessage: this.validateListName.bind(this)
                   })
                 ]
               }
             ]
           }
         ]
       };
     }
    
     // ...
    }
    
  4. 検証の結果を表示するには、次のコマンドを実行します。Run the following command to see the result of the validation:

    gulp serve --nobrowser
    

    リスト名の検証メソッドは SharePoint REST API とやり取りを行うので、ホストされるバージョンの SharePoint ワークベンチで Web パーツをテストする必要があります。Because the list name validation method communicates with the SharePoint REST API, you have to test the web part in the hosted version of the SharePoint workbench.

  5. キャンバスに Web パーツを追加して、そのプロパティを開きます。Add the web part to the canvas and open its properties. リスト名は必須プロパティですが、既定値を指定していないので、検証エラーが表示されます。Because you haven't specified a default value for the list name, which is a required property, you see a validation error.

    値が指定されていない必須プロパティに対して表示される検証エラー


    存在していないリストの名前を指定すると、指定されたリストが現在のサイトに存在しないことを示す検証エラーが Web パーツに表示されます。If you provide the name of a list that doesn't exist, the web part displays a validation error stating that the list you specified doesn't exist in the current site.

    現在のサイトに存在していないリストの名前を指定したときに表示される検証エラー


    既存のリストの名前を指定すると、検証エラーは表示されなくなります。If you specify the name of an existing list, the validation error disappears.

    リスト名が有効な場合には検証エラーは表示されない

リモート API を使用して検証を最適化するOptimize validation using remote APIs

リモート API を使用して Web パーツのプロパティを検証する場合、SharePoint Framework はプロパティ ウィンドウ コントロールで変更を監視し、更新された値を指定された検証ハンドラーに送って検証します。When validating web part properties using remote APIs, SharePoint Framework monitors changes in the property pane controls and sends updated values for validation to the specified validation handler. 既定では、SharePoint Framework は、検証プロセスをトリガーするまでに 200 ミリ秒待機します。By default, the SharePoint Framework waits 200 ms before triggering the validation process. 200 ミリ秒の間、ユーザーが特定の値を変更しないと、SharePoint Framework によって検証プロセスが開始されます。If the user hasn't changed the particular value for 200 ms, the SharePoint Framework starts the validation process. 検証ハンドラーがリモート API を使用する場合、検証プロセスが開始するたびに、そのメソッドは Web 要求を API に発行して、指定された値を検証します。When the validation handler uses a remote API, each time the validation process starts, that method issues a web request to the API to validate the specified value. ユーザーの入力速度が遅いと、入力途中の値が検証のために送信されて、ネットワークや API に不必要にストレスが加わります。If users don't type fast enough, this results in partially completed values being sent over for validation, unnecessarily stressing the network and the API. その場合、検証待ち時間を延ばすことをご検討ください。In such cases, you should consider increasing the validation delay.

Microsoft Edge のネットワーク ツールが、入力途中のリスト名を検証するための Web 要求が繰り返し送信されていることを示している

検証待ち時間は、ユーザーが指定する必要がある値の種類に応じて、プロパティごとに構成することができます。You can configure the validation delay for each property separately, depending on the type of value that users need to provide.

listName プロパティの検証待ち時間を延ばす方法To increase the validation delay for the listName property

  1. コード エディターで、./src/webparts/listInfo/ListInfoWebPart.ts ファイルを開きます。getPropertyPaneConfiguration メソッドのコードを次のように変更します。In the code editor, open the ./src/webparts/listInfo/ListInfoWebPart.ts file. Change the code of the getPropertyPaneConfiguration method to:

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
     // ...
    
     protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
       return {
         pages: [
           {
             header: {
               description: strings.PropertyPaneDescription
             },
             groups: [
               {
                 groupName: strings.BasicGroupName,
                 groupFields: [
                   PropertyPaneTextField('description', {
                     label: strings.DescriptionFieldLabel,
                     onGetErrorMessage: this.validateDescription.bind(this)
                   }),
                   PropertyPaneTextField('listName', {
                     label: strings.ListNameFieldLabel,
                     onGetErrorMessage: this.validateListName.bind(this),
                     deferredValidationTime: 500
                   })
                 ]
               }
             ]
           }
         ]
       };
     }
    
     // ...
    }
    
  2. deferredValidationTime プロパティは、検証プロセスを開始するまでに SharePoint Framework が待機するミリ秒数を指定します。The deferredValidationTime property specifies the number of milliseconds that the SharePoint Framework waits before starting the validation process.

  3. 次のコマンドを実行し、適用される待ち時間が正常に動作することを確認します。Run the following command to see that the applied delay is working as expected:

    gulp serve --nobrowser