最初の ListView Command Set の拡張機能をビルドする

[アーティクル]
04/08/2023

拡張機能は、SharePoint ページのコンテキスト内で実行されるクライアント側コンポーネントです。拡張機能を SharePoint Online に展開することができ、最新の JavaScript ツールとライブラリを使用してそれらを構築できます。

Microsoft 365 Platform Communtiy (PnP) YouTube チャネルでビデオを見ると、次の手順に従うことができます。

拡張機能のプロジェクトを作成する

自分の好みの場所に新しいプロジェクトディレクトリを作成します。
```
md command-extension
```
プロジェクトディレクトリへ移動します。
```
cd command-extension
```
Yeoman の SharePoint ジェネレーターを実行して、新しい HelloWorld の拡張機能を作成します。
```
yo @microsoft/sharepoint
```
プロンプトが表示されたら、以下の値を入力します (以下で省略されたすべてのプロンプトに対して既定のオプションを選択します)。
- ソリューション名は何ですか?: command-extension
- どの種類のクライアント側コンポーネントを作成しますか?: 拡張機能
- どの種類のクライアント側拡張機能を作成しますか? リストビューコマンドセット
- コマンドセット名は何ですか? HelloWorld
この時点で、Yeoman は必要な依存関係をインストールし、ソリューションファイルを HelloWorld の拡張機能とともにスキャフォールディングします。これは、通常 1 - 3 分かかります。
次に、コンソールに次のように入力して Visual Studio Code を起動します。
```
code .
```

./src/extensions/helloWorld/HelloWorldCommandSet.manifest.json ファイルを開きます。

このファイルは、拡張機能の種類と拡張機能の一意識別子 id を定義します。後で拡張機能をデバッグして SharePoint に展開するときに、この一意識別子が必要になります。

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/command-set-extension-manifest.schema.json",

  "id": "95688e19-faea-4ef1-8394-489bed1de2b4",
  "alias": "HelloWorldCommandSet",
  "componentType": "Extension",
  "extensionType": "ListViewCommandSet",

  "version": "*",
  "manifestVersion": 2,

  "requiresCustomScript": false,

  "items": {
    "COMMAND_1": {
      "title": { "default": "Command One" },
      "iconImageUrl": "icons/request.png",
      "type": "command"
    },
    "COMMAND_2": {
      "title": { "default": "Command Two" },
      "iconImageUrl": "icons/cancel.png",
      "type": "command"
    }
  }
}

マニフェストファイル内の実際のコマンド定義に注意してください。これらは、登録対象に基づいて公開される実際のボタンです。既定のテンプレートには、Command One と Command Two の 2 つの異なるボタンがあります。

注:

マニフェスト内の CDN 内の絶対場所から参照しない限り、イメージは適切に参照されません。

ListView Command Set のコーディング

ファイル ./src/extensions/helloWorld/HelloWorldCommandSet.ts を開きます。

ListView コマンドセットの基本クラスが、listView コマンドセットで必要なSharePoint Framework (SPFx) コードを含む @microsoft/sp-listview-extensibility パッケージからインポートされていることに注意してください。

import { override } from '@microsoft/decorators';
import { Log } from '@microsoft/sp-core-library';
import {
  BaseListViewCommandSet,
  Command,
  IListViewCommandSetListViewUpdatedParameters,
  IListViewCommandSetExecuteEventParameters
} from '@microsoft/sp-listview-extensibility';
import { Dialog } from '@microsoft/sp-dialog';

カスタムボタンの動作は、メソッドと OnExecute() メソッドにonListViewUpdated()含まれています。

イベントは onListViewUpdated() 、ListView で変更が行われ、UI を再レンダリングする必要がある場合は常に、コマンド (メニュー項目など) ごとに個別に発生します。 event 関数パラメーターは、表示されるコマンドに関する情報を表します。ハンドラーは、リストビューで一定数の項目が選択されたときにのみコマンドを表示する場合など、この情報を使用してタイトルをカスタマイズしたり表示を調整したりすることができます。これは既定の実装です。

メソッド tryGetCommand() を使用するときは、UI に表示されるコマンドの表記である Command オブジェクトを取得します。 title や visible などの値を変更して UI 要素を変更することができます。 SPFx はコマンドを再表示するときにこの情報を使用します。これらのオブジェクトは最後の表示から状態を保持するので、コマンドが visible = false に設定されている場合、コマンドは visible = true に戻されるまで非表示のままです。

@override
public onListViewUpdated(event: IListViewCommandSetListViewUpdatedParameters): void {
  const compareOneCommand: Command = this.tryGetCommand('COMMAND_1');
  if (compareOneCommand) {
    // This command should be hidden unless exactly one row is selected.
    compareOneCommand.visible = event.selectedRows.length === 1;
  }
}

メソッドは onExecute() 、コマンドの実行時の動作を定義します (メニュー項目が選択されている場合など)。既定の実装では、選択されるボタンに応じて異なるメッセージが表示されます。

@override
public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
  switch (event.itemId) {
    case 'COMMAND_1':
      Dialog.alert(`${this.properties.sampleTextOne}`);
      break;
    case 'COMMAND_2':
      Dialog.alert(`${this.properties.sampleTextTwo}`);
      break;
    default:
      throw new Error('Unknown command');
  }
}

ListView Command Set のデバッグ

現時点では、ローカルワークベンチを使用して SharePoint Framework の拡張機能をテストすることはできません。テストと開発は、ライブの SharePoint Online サイトに対して直接実行する必要があります。そのために、カスタマイズをアプリカタログに展開する必要はありません (これにより、デバッグ操作が簡単で効率的になります)。

モダンエクスペリエンスを使用して SharePoint Online サイト内の SharePoint リストに移動するか、新しいリストを作成します。リストの URL をクリップボードにコピーします。後の手順でこれが必要になります。

ListView Command Set は localhost でホストされ、実行されているので、固有のデバッグクエリパラメーターを使ってリストビューでコードを実行することができます。

./config/serve.json ファイルを開きます。ソリューションを pageUrl テストするリストの URL と一致するように属性を更新します。編集後、serve.json は次のようになります。

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "customActions": {
        "bf232d1d-279c-465e-a6e4-359cb4957377": {
          "location": "ClientSideExtension.ListViewCommandSet.CommandBar",
          "properties": {
            "sampleTextOne": "One item is selected in the list",
            "sampleTextTwo": "This command is always visible."
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "customActions": {
        "bf232d1d-279c-465e-a6e4-359cb4957377": {
          "location": "ClientSideExtension.ListViewCommandSet.CommandBar",
          "properties": {
            "sampleTextOne": "One item is selected in the list",
            "sampleTextTwo": "This command is always visible."
          }
        }
      }
    }
  }
}

このコマンドを実行して、コードをコンパイルし、コンパイルしたファイルをローカルコンピューターからホストします。
```
gulp serve
```
コードがエラーなしでコンパイルされると、https://localhost:4321 から結果のマニフェストが提供されます。

これにより、 ./config/serve.json ファイルで定義されている URL 内で既定のブラウザーも開始されます。なお、少なくとも Windows では、このコマンドの実行前に優先ブラウザーをアクティブ化することにより、どのブラウザーウィンドウを使用するかを制御できます。
ダイアログが表示されたら、[デバッグスクリプトを読み込む] を選択して、デバッグマニフェストの読み込みを承諾します。
新しい [Command Two] ボタンがツールバーに表示されていることに注目してください。そのボタンを選択して、sampleTextTwo プロパティのプロパティとして提供されたテキストを表示します。
ドキュメントライブラリで 1 行選択されるまで、[Command One] ボタンはコードに基づいて表示されません。ライブラリにドキュメントをアップロードまたは作成し、2 番目のボタンが表示されていることを確認します。
ListView Command Set が拡張機能の種類として選択されている場合の、ソリューションスキャフォールディングの既定の出力で使用されるダイアログコントロールの動作を確認するには、[Command Two] を選択します。

serve.json オプションの詳細

customActions: カスタムアクションをシミュレートします。この CustomAction オブジェクトには、ボタンの外観、使い勝手、位置に影響する多くのプロパティを設定できます。以下にそれらをすべて説明します。
- GUID: 拡張機能の GUID。
- Location: コマンドが表示される場所。値は次のいずれかです。
  - ClientSideExtension.ListViewCommandSet.ContextMenu: 項目のコンテキストメニュー。
  - ClientSideExtension.ListViewCommandSet.CommandBar: リストまたはライブラリ内の最上位コマンドセットメニュー。
  - ClientSideExtension.ListViewCommandSet: コンテキストメニューとコマンドバーの両方 (SPUserCustomAction.Location="CommandUI.Ribbon"に対応します)。
- Properties: メンバーを介して this.properties 使用できるプロパティを含む省略可能な JSON オブジェクト。

ListView Command Set の表示の強化

既定のソリューションは、新しいダイアログ API を利用して、コードから簡単にモーダルダイアログを表示することができます。次の手順では、ダイアログ API の使用例を示すために、既定のエクスペリエンスを少し変更します。

Visual Studio Code (または任意のエディター) に戻ります。
ファイル ./src/extensions/helloWorld/HelloWorldCommandSet.ts ファイルを開きます。

メソッドを onExecute() 次のように更新します。

@override
public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
  switch (event.itemId) {
    case 'COMMAND_1':
      Dialog.alert(`Clicked ${strings.Command1}`);
      break;
    case 'COMMAND_2':
      Dialog.prompt(`Clicked ${strings.Command2}. Enter something to alert:`).then((value: string) => {
        Dialog.alert(value);
      });
      break;
    default:
      throw new Error('Unknown command');
  }
}

コンソールウィンドウで、例外がないことを確認します。ソリューションを localhost で実行していない場合は、次のコマンドを実行します。
```
gulp serve
```
ダイアログが表示されたら、[デバッグスクリプトを読み込む] を選択して、デバッグマニフェストの読み込みを承諾します。

ツールバーには同じボタンがありますが、1 つずつ選択すると、それらのボタンの動作が異なることがわかります。複雑なシナリオの場合でも、ソリューションで簡単に使用できる新しいダイアログ API を使用しています。

展開するソリューションパッケージに ListView Command Set を追加する

Visual Studio Code (またはお使いのエディター) で、ソリューションに戻ります。
./sharepoint/assets/elements.xml ファイルを開きます。

elements.xml 内の次の XML 構造に注意してください。プロパティが ClientSideComponentId 、 ./src/extensions/helloWorld/HelloWorldCommandSet.manifest.json ファイルで使用できる ListView コマンドセットの一意の ID に更新されました。

これが ListView Command Set であることを定義するために ClientSideExtension.ListViewCommandSet.CommandBar の特定の位置の値を使用することに注意してください。コマンドバーに表示する必要があります。また、このカスタムアクションをジェネリックリストに自動的に関連付けるには、と RegistrationType と List を定義RegistrationId100します。 ClientSideComponentProperties は、インスタンス固有の構成を提供するために使用できます。この例では、sampleTextOne と sampleTextTwo という既定のプロパティを使用しています。

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <CustomAction
        Title="SPFxListViewCommandSet"
        RegistrationId="100"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
        ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
    </CustomAction>
</Elements>

注:

localhost から実行している間、カスタムアクションはリストとドキュメントライブラリの両方で機能しますが、 elements.xml が更新されない限り、一度デプロイされることはありません。 RegistrationId=100 により、ドキュメントライブラリではなく、リストにカスタムアクションが関連付けられるだけです。

カスタムアクションをドキュメントライブラリに関連付けるには、 RegistrationId をに設定する 101必要があります。リストとドキュメントライブラリの両方でアクションを実行する場合は、別の CustomAction アクションを elements.xml ファイルに追加する必要があります

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <CustomAction
        Title="SPFxListViewCommandSet"
        RegistrationId="100"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
        ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
    </CustomAction>
    <CustomAction
        Title="SPFxListViewCommandSet"
        RegistrationId="101"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
        ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
    </CustomAction>
</Elements>

ListView Command Set で使用できる可能性のある場所の値:

ClientSideExtension.ListViewCommandSet.CommandBar: リストまたはライブラリのツールバー
ClientSideExtension.ListViewCommandSet.ContextMenu: リストまたはライブラリ項目のコンテキストメニュー
ClientSideExtension.ListViewCommandSet: ツールバーとコンテキストメニューの両方にコマンドを登録します

定義がビルドパイプライン内で使用されていることを確認する

ファイル ./config/package-solution.json を開きます。

package-solution.json ファイルは、次のコードに示されているようにパッケージメタデータを定義します。ソリューションパッケージの作成時に element.xml ファイルが考慮されるように、このファイルの既定のスキャフォールディングが更新され、機能定義の追加の詳細が含まれます。この機能定義は、 elements.xml ファイルのプロビジョニングと実行に使用されます。

注:

ClientSideInstance.xml を使用して、テナント内のすべてのサイトでの拡張を自動的に展開できます。このオプションの詳細については、「SharePoint Framework 拡張機能のテナント全体の展開」の記事を参照してください。このソリューションでは、テナントスコープオプションを使用しない構成を意図しているので、ソリューションがアプリカタログでアクティブ化されるときにこの xml ファイルは無視されます。

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "command-extension-client-side-solution",
    "id": "0abe5c73-1655-49d3-922b-7a47dd70e151",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    "features": [
      {
        "title": "Application Extension - Deployment of custom action.",
        "description": "Deploys a custom action with ClientSideComponentId association",
        "id": "25f8df47-61f2-4d75-bfe2-8d614f775219",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml",
            "clientsideinstance.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/command-extension.sppkg"
  }
}

SharePoint Online に拡張機能を展開する

ここまでで、ソリューションを SharePoint サイトに展開し、CustomAction をサイトレベルで自動的に関連付ける準備ができました。

ソリューションは既定でアセットパッケージ化機能を使用するので、JavaScript ファイルとその他のアセットは自動的に sppkg ファイルの内部にパッケージ化され、Office 365 CDN またはアプリカタログのサイトコレクションから自動的にホストされます。

コンソールウィンドウで次のコマンドを入力して、拡張機能を含むクライアント側のソリューションをパッケージ化すると、パッケージ化できる基本構造を取得できます。
```
gulp bundle --ship
```
次のコマンドを実行して、ソリューションパッケージを作成します。
```
gulp package-solution --ship
```
コマンドは、 ./sharepoint/solution/command-extension.sppkg フォルダーというパッケージを作成します。
生成されたパッケージをアプリカタログに展開します。そのためには、テナントのアプリカタログに移動し、SharePoint 用アプリ ライブラリを開きます。
./sharepoint/solution/command-extension.sppkg フォルダーをアプリカタログにアップロードします。 SharePoint はダイアログを表示し、クライアント側ソリューションを信頼するよう求めます。
[展開] ボタンを選択します。
SharePoint アセットのプロビジョニングをテストするサイトに移動します。このソリューションパッケージを展開したテナント内の任意のサイトコレクションに移動できます。
右側の上部のナビゲーションバーにある歯車アイコンを選択し、[ アプリの追加 ] を選択して [アプリ] ページに移動します。
[検索] ボックスで、「extension」と入力し、Enter キーを押して、アプリをフィルター処理します。
command-extension-client-side-solution アプリを選択して、サイトにソリューションをインストールします。インストールが完了したら。
アプリケーションが正常にインストールされたら、[サイトコンテンツ] ページのツールバーで [新規] を選択し、[リスト] を選択します。
名前を Sample とし、[作成] を選択します。

ListView Command Set のカスタマイズに基づいて、[Command One] および[Command Two] がツールバーに表示されていることを確認してください。新規のリストだけでなく、既存のリストでも拡張機能が自動的にレンダリングされることに注意してください。

Share via

最初の ListView Command Set の拡張機能をビルドする

拡張機能のプロジェクトを作成する

ListView Command Set のコーディング

ListView Command Set のデバッグ

serve.json オプションの詳細

ListView Command Set の表示の強化

展開するソリューションパッケージに ListView Command Set を追加する

定義がビルドパイプライン内で使用されていることを確認する

SharePoint Online に拡張機能を展開する

関連項目

その他のリソース

Share via

最初の ListView Command Set の拡張機能をビルドする

拡張機能のプロジェクトを作成する

ListView Command Set のコーディング

ListView Command Set のデバッグ

serve.json オプションの詳細

ListView Command Set の表示の強化

展開するソリューション パッケージに ListView Command Set を追加する

定義がビルド パイプライン内で使用されていることを確認する

SharePoint Online に拡張機能を展開する

関連項目

その他のリソース

展開するソリューションパッケージに ListView Command Set を追加する

定義がビルドパイプライン内で使用されていることを確認する