Microsoft Graph Toolkit でのピッカーコンポーネントのPeople

[アーティクル]
02/14/2024

Web コンポーネントを mgt-people-picker 使用して、ユーザー、グループ、またはその両方を検索できます。既定では、コンポーネントはorganization内のすべてのユーザーとユーザーを検索しますが、動作を変更してグループを検索することも、グループのみを検索することもできます。また、特定のグループに絞り込んで検索することもできます。また、ユーザーが任意のメールアドレスを入力して選択できるようにすることもできます。

例

次の使用例では mgt-people-picker コンポーネントを表示します。名前の検索を開始してレンダリングされた結果を表示し、コードエディターを使用して、プロパティがコンポーネントの動作をどのように変更させるかを確認することができます。

HTML
React

mgt.dev でこの例を開きます。

プロパティ

既定値では、mgt-people-picker コンポーネントは /me/people および /users エンドポイントからユーザーを取得します。次の属性を使用して、この動作を変更します。

属性	プロパティ	説明
show-max	showMax	表示するユーザーの最大数を示す数値。既定値は 6 です。
group-id	groupId	検索結果をさらにフィルター処理するために、Microsoft Graph で定義されたグループに属する文字列値。
transitive-search	transitiveSearch	入れ子になったすべてのメンバーのフラットリストを返す推移的検索を実行するためのブール値。既定では推移的検索は使用されません。
type	型	検索するメールメッセージの種類。使用可能なオプションは、`person`、`group`、および `any` です。既定値は、`person` です。この属性がに`group`設定され、または `group-ids` が`group-id`設定されている場合、および `peopleFiltersuserFilters` 効果はありません。
user-type	userType	検索するユーザーの種類。使用可能なオプションは、`anyuser`組織のユーザーの場合、または連絡先の場合`contact`です。既定値は、`any` です。
group-type	groupType	検索するグループの種類。使用可能なオプションは、`unified`、`security`、`mailenabledsecurity`、`distribution`、および `any` です。既定値は、`any` です。この属性は、`type` プロパティが `person` に設定されている場合は影響を受けません。この属性は、値のコンマ区切りのリストを受け入れます。プロパティは配列または値を受け入れます。
selected-people	selectedPeople	選択済みのユーザーの配列。この値を設定すると、プログラムでユーザーを選択することができます。
people	people	検索結果に表示されるユーザーの配列
placeholder	placeholder	コンポーネントの使用方法を説明するために表示される既定のテキスト。既定値は、`Start typing a name` です。
default-selected-user-ids	defaultSelectedUserIds	カンマで区切られた Microsoft Graph のユーザー ID の文字列が指定されると、コンポーネントは初期化時に選択されたとおりのユーザーを表示します。
default-selected-group-ids	defaultSelectedGroupIds	既定の selected-user-ids と同様に、コンマ区切りの Microsoft Graph グループ ID の文字列を指定すると、コンポーネントは初期化時に選択された各グループをレンダリングします。
selection-mode	selectionMode	複数の項目 (ユーザーやグループ) を選択できるようにするか、単一の項目だけを選択できるようにするかを指定するために使用します。使用可能なオプションは、`single`、および `multiple` です。既定値は、`multiple` です。
無効	無効	ユーザー選択ウィンドウを無効にするかどうかを設定します。無効にすると、ユーザーはユーザーを検索または選択できません。既定値は `false` です。
disable-images	disableImages	人物画像のフェッチと表示を無効にするかどうかを設定します。に `true`設定すると、代わりにユーザーのイニシャルが表示されます。既定値は `false` です。
person-card	personCardInteraction	選択したユーザーのカードを表示する動作を設定します。使用できる値は、 `none`、 `hover` または `click`です。既定値は `none` です。
allow-any-email	allowAnyEmail	ユーザー選択ウィンドウで、ユーザーを選択せずにメールアドレスを受け入れられるかどうかを示します。既定値は、`false` です。メールアドレスの入力が完了したら、コンマ ()、セミコロン (`,;`)、タブ、キーを入力して追加できます。
user-ids	UserIds	コンマ区切りのユーザー ID の文字列。クエリを入力した場合にのみ、ドロップダウンメニューまたは検索結果に表示されます。たとえば、 `48d31887-5fad-4d73-a9f5-3c356e68a038,24fcbca3-c3e2-48bf-9ffc-c7f81b81483d` 入力にフォーカスがある場合、ドロップダウンに 2 人のユーザーのみが表示されます。検索テキストを入力すると、2 つのユーザー ID のユーザーにのみ一致する結果が返されます。
user-filters	userFilters	ユーザーのエンドポイントに対してクエリを実行するときに使用するフィルター条件を指定します。またはに設定する`usercontact`必要`user-type`があります。既定では、は `any` であり、`user-type`エンドポイントブロックでクエリが`people`実行されます。例: `user-filters="startsWith(displayName,'a')"`。この属性は省略可能です。ディレクトリオブジェクトのユーザープロパティに対するフィルター処理のサポートの詳細について説明します。アクセス許可のみを `User.ReadBasic.All` 使用すると、使用可能なプロパティの一覧が制限され、コンポーネントがそれに応じて調整されます。 User.ReadBasic.All スコープでは、、および `userPrincipalName`の各プロパティ`mailsurnameiddisplayNamegivenNamesecurityIdentifier`に制限されます。既定では、このコンポーネントではと `department` プロパティが`jobTitle`使用されます。プロパティは`mail`、が使用中であり、他のプロパティがレンダリングされない場合`User.ReadBasic.All`のフォールバック`jobTitle`として機能します。アクセス許可を `User.Read.All` 使用して、その他のプロパティに対してクエリを実行します。
group-filters	groupFilters	エンドポイントのクエリに使用するフィルター条件を `groups` 指定します。をに設定する`group`必要`type`があります。例: `group-filters="startsWith(displayName,'a')"`。この属性は省略可能です。
people-filters	peopleFilters	エンドポイントのクエリに使用するフィルター条件を `people` 指定します。そのまま使用されます。例: `people-filters="jobTitle eq 'Web Marketing Manager'"`。この属性は省略可能です。ユーザーリソースでのフィルター処理とサポートされている機能の詳細について説明します。
group-ids	groupIds	コンマ区切りのグループ ID の文字列。使用可能な結果は、指定したグループに限定する必要があります。ドロップダウンメニューと検索エクスペリエンスを介して表示されるユーザーは、指定されたグループ ID からのみ取得する必要があります。たとえば、 `02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23` これらのグループに属するユーザーのみが表示されます。検索テキストを入力すると、2 つのグループ ID のユーザーにのみ一致する結果が返されます。が定義されている場合 `group-id` 、このプロパティは使用されません。プロパティが設定されている場合、 `type` は `group` 既定で、 `transitive-search` 既定ではです `true` 。 `group-type`がプロパティで設定されている場合は、 `type` またはを指定`group`できます`any`。 `type`が `person`の場合、プロパティは使用されません。
aria-label	ariaLabel	支援技術がユーザー選択ウィンドウのコンテキストを提供するのに役立つ文字列。

次の例は、属性を show-max 示しています。

<mgt-people-picker show-max="4"> </mgt-people-picker>

選択済みのユーザー

コンポーネントの選択済みのユーザーセクションは、開発者またはユーザーによって選ばれた各ユーザーを表示します。

mgt-people-picker

選択したユーザーデータに次のオプションを設定できます。

以下の例のように、selectedPeople プロパティを直接設定します。

// personObject is the User or Person object from Microsoft Graph
document.querySelector("mgt-people-picker").selectedPeople.push(personObject);

selectUsersById() Microsoft Graph ユーザー ID の配列を受け入れるメソッドを使用して、選択に関連するユーザーの詳細を検索します。

注：id のユーザーが見つからない場合、その id のデータはレンダリングされません。
```
// id = Microsoft graph User "id"
document.querySelector("mgt-people-picker").selectUsersById(["id", "id"]);
```
selectGroupsById() Microsoft グラフグループ ID の配列を受け入れるメソッドを使用して、関連付けられているユーザーのグループを検索します。
```
// groupid = Microsoft graph group "id"
document
  .querySelector("mgt-people-picker")
  .selectGroupsById(["groupid", "groupid"]);
```

CSS カスタムプロパティ

mgt-people-picker コンポーネントは、以下の CSS カスタムプロパティを定義します。

<mgt-people-picker class="people-picker"></mgt-people-picker>

.people-picker {
  --people-picker-selected-option-background-color: orange;
  --people-picker-selected-option-highlight-background-color: red;
  --people-picker-dropdown-background-color: blue;
  --people-picker-dropdown-result-background-color: yellow;
  --people-picker-dropdown-result-hover-background-color: gold;
  --people-picker-dropdown-result-focus-background-color: green;
  --people-picker-no-results-text-color: orange;
  --people-picker-input-background: gray;
  --people-picker-input-border-color: yellow;
  --people-picker-input-hover-background: green;
  --people-picker-input-hover-border-color: red;
  --people-picker-input-focus-background: purple;
  --people-picker-input-focus-border-color: orange;

  --people-picker-input-placeholder-focus-text-color: yellow;
  --people-picker-input-placeholder-hover-text-color: gold;
  --people-picker-input-placeholder-text-color: white;
  --people-picker-search-icon-color: yellow;
  --people-picker-remove-selected-close-icon-color: blue;

  /** Style for the avatar-size in the people-picker **/
  --people-picker-result-person-avatar-size: 50px;
  --people-picker-selected-person-avatar-size: 30px;

  /** You can also change the person tokens **/
  --person-line1-text-color: blue;
  --person-line2-text-color: red;
}

詳細については、「コンポーネントのスタイリング」を参照してください。

イベント

コンポーネントから次のイベントが発生します。

イベント	いつ出力されるか	カスタムデータ	キャンセル	泡	カスタムテンプレートを使用する
`selectionChanged`	ユーザーが選択または選択したユーザーの一覧からユーザーを追加または削除した	ユーザーが Graph ユーザー、ユーザー、またはユーザーの写真の URL を含む別`personImage`のプロパティと接触できる、選択したユーザーの配列	いいえ	いいえ	はい(既定のテンプレートをオーバーライドしない限り)

イベントの処理の詳細については、「イベント」を参照してください。

テンプレート

mgt-people-picker は、いくつかのテンプレートをサポートしており、コンポーネントの特定の部分を置き換えることができます。テンプレートを指定するには、コンポーネント内に要素を <template> 含め、を data-type 次のいずれかの値に設定します。

データ型	データコンテキスト	説明
既定	null: データなし	コンポーネント全体の表示をオーバーライドするために使用されるテンプレートです。
読み込み中	null: データなし	グラフへの要求が行われている間、ピッカーの状態を表示するために使用されるテンプレートです。
エラー	null: データなし	ユーザー検索でユーザーが見つからない場合に使用されるテンプレート。
no-data	null: データなし	ユーザー検索でユーザーが見つからない場合に使用されるテンプレート。
選択済みのユーザー	ユーザー: ユーザー詳細オブジェクト	選択済みのユーザーを表示するためのテンプレート。
ユーザー	ユーザー: ユーザー詳細オブジェクト	ドロップダウンでユーザーを表示するテンプレート。

次の例では、テンプレートの使用方法を error 示します。

<mgt-people-picker>
  <template data-type="error">
    <p>Sorry, no people were found</p>
  </template>
</mgt-people-picker>

Microsoft Graph のアクセス許可

このコンポーネントは、構成と状態に応じて多くのクエリを実行する場合があります。次の表では、わかりやすくするために必要な Microsoft Graph API とアクセス許可を 3 つのセクションに分割します。呼び出される API ごとに、ユーザーには少なくとも 1 つのアクセス許可が一覧表示されている必要があります。

ユーザー入力状態に関係なく

構成	アクセス許可	API	追加オプション
`default-selected-user-ids` 設定	User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All	/users/$({userId}	が設定されている場合`user-filters`、これはを使用して要求`$count=true`にパラメーターとして`$filter`追加され、要求で`ConsistencyLevel: 'eventual'`ヘッダーが設定されます
`default-selected-group-ids` 設定	GroupMember.Read.All、Group.Read.All、Directory.Read.All、Group.ReadWrite.All、Directory.ReadWrite.All	/groups	が設定されている場合 `people-filters` 、その値がパラメーターとして `$filter` 要求に追加されます
のエントリ`me`がある場合、以下の構成が設定に依存`user-ids`する場合`user-ids`	User.Read、User.ReadWrite	/me

ユーザー入力がない場合

構成	アクセス許可	API	追加オプション
`group-id` 設定	GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All	/groups/${groupId}/members	がまたはのいずれかである場合`type`、または `/microsoft.graph.group` が要求パスに追加されます`/microsoft.graph.usergroupperson`
`group-id` SET AND `transitive-search` が true	GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All	/groups/${groupId}/transitiveMembers	がまたはのいずれかである場合`type`、または `/microsoft.graph.group` が要求パスに追加されます`/microsoft.graph.usergroupperson`
`group-ids` SET AND `type` is `group`	GroupMember.Read.All、Group.Read.All、Directory.Read.All、Group.ReadWrite.All、Directory.ReadWrite.All	/groups/${id}
`group-ids` AND `type` が NOT に設定されている `group`	GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All	/groups/${groupId}/members	`person`が`/microsoft.graph.user`要求パスに追加される場合`type`
`group-ids` AND `type` が NOT `group` AND `transitive-search` の場合は true を設定します	GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All	/groups/${groupId}/transitiveMembers	`person`が`/microsoft.graph.user`要求パスに追加される場合`type`
`type`は `group` であり、設定も設定も`group-ids`されていません`group-id`	GroupMember.Read.All、Group.Read.All、Directory.Read.All、Group.ReadWrite.All、Directory.ReadWrite.All	/groups
`type`または `any` に`person`設定され、 `userIds` が設定されている	User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All	/users/$({userId}	が設定されている場合 `user-filters` 、これは $filter パラメーターとして要求 `$count=true` に追加され、要求に `ConsistencyLevel: 'eventual'` ヘッダーが設定されます
`type`または `any` に`person`設定され`user-filters`、がに設定され`user-type`、またはに`user`設定されます。`contact`	User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All	/users	が設定されている場合 `user-filters` 、これは $filter パラメーターとして要求 `$count=true` に追加され、要求に `ConsistencyLevel: 'eventual'` ヘッダーが設定されます
`type`または `any` に`person`設定され、設定`user-filters`されていないか、または `user-type` に設定されていない`user`か、`contact`	People.Read、People.Read.All	/me/people	が設定`user-type`されているか、$filterパラメーターでない`any`場合`people-filters`は、要求に追加されます。が要求に対してヘッダーが`X-PeopleQuery-QuerySources: 'Mailbox,Directory'`設定されていない`contact`場合`user-type`

ユーザーが検索語句を指定した場合

構成	アクセス許可	API	追加オプション
`group-id` が設定されている	GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All	/groups/${groupId}/members	が `person` または `group` 要求`/microsoft.graph.group/microsoft.graph.user`パスに追加された場合`type`、`$filter`パラメーターはユーザー入力値で構成されます
`group-id` が設定され、 `transitive-search` true である	GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All	/groups/${groupId}/transitiveMembers	が `person` または `group` 要求`/microsoft.graph.group/microsoft.graph.user`パスに追加された場合`type`、`$filter`パラメーターはユーザー入力値で構成されます
`group-id`がに設定され、 `type` がまたは `any` に`person`設定され、 `user-type` がに`anygroup-ids`設定されていない	GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All	/groups/${groupId}/members	`type`が`person/microsoft.graph.user`要求パスに追加されると、`$filter`パラメーターはユーザー入力値で構成されます
`group-id`がまたはに設定され`type`、がに`anypersonanyuser-typegroup-ids`設定され、が設定され、 `transitive-search` が true である	GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All	/groups/${groupId}/transitiveMembers	`type`が`person/microsoft.graph.user`要求パスに追加されると、`$filter`パラメーターはユーザー入力値で構成されます
`type`をまたは `any` に`person`設定し、 `user-type` がに`any`設定されていない場合`user-ids`	User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All	/users/$({userId}	が設定されている場合 `user-filters` 、これは $filter パラメーターとして要求 `$count=true` に追加され、要求に `ConsistencyLevel: 'eventual'` ヘッダーが設定されます
`type`またはに`person`設定され、 `user-type` がに`any`設定され`group-ids`、が設定`user-ids`されていない`any`	User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All	/users/$({userId}	が設定されている場合 `user-filters` 、これは $filter パラメーターとして要求 `$count=true` に追加され、要求に `ConsistencyLevel: 'eventual'` ヘッダーが設定されます
`group-id` が設定されておらず、 `type` が `group` または `type` であり `any` 、検出された結果よりも `show-max` 少ない	GroupMember.Read.All、Group.Read.All、Directory.Read.All、Group.ReadWrite.All、Directory.ReadWrite.All	/groups	は `$filter` 、指定されたユーザー入力、、 `group-filters`および `group-type` 値を使用して構成されます
`group-id` が設定されておらず、 `group-ids` が設定され、 `type` が `group` または `type` であり `any` 、検出された結果よりも `show-max` 少ない	GroupMember.Read.All、Group.Read.All、Directory.Read.All、Group.ReadWrite.All、Directory.ReadWrite.All	/groups	は `$filter` 、指定されたユーザー入力、、 `user-filters`および `group-type` 値を使用して構成されます

サブコンポーネント

コンポーネントは mgt-people-picker 1 つ以上のサブコンポーネントで構成され、前に一覧に示した権限以外のアクセス許可が必要な場合があります。詳細については、各サブコンポーネントのドキュメント mgt-person を参照してください。

認証

この制御は、認証ドキュメントに記述されているグローバル認証プロバイダーを使用します。

キャッシュ

オブジェクトストア	キャッシュされたデータ	注釈
`groups`	グループの一覧	がに設定されている場合 `type` に使用されます `PersonType.group`
`people`	ユーザーの一覧	がまたはに設定されている場合 `type` に `PersonType.person` 使用されます `PersonType.any`
`users`	ユーザーの一覧	指定時に `groupId` 使用されます

キャッシュを構成する方法の詳細については、「キャッシュ」を参照してください。

より制御を行うために拡張する

より複雑なシナリオや真にカスタムな UX のために、このコンポーネントは、コンポーネント拡張でオーバーライドするためのいくつかのprotected render* メソッドを公開しています。

メソッド	説明
renderInput	入力テキストボックスを表示します。
renderSelectedPeople	選択済みのユーザートークンを表示します。
renderSelectedPerson	個々のユーザートークンを表示します。
renderFlyout	ポップアップ Chrome を表示します。
renderFlyoutContent	結果のポップアップで適切な状態を表示します。
renderLoading	読み込み状態を表示します。
renderNoData	検索クエリの結果が見つからなかった場合の状態を表示します。
renderSearchResults	検索結果の一覧を表示します。
renderPersonResult	個々のユーザーの検索結果を表示します。

ローカリゼーション

コントロールは、ローカライズできる次の変数を公開します。ローカライズの詳細については、「コンポーネントのローカライズ」を参照してください。

文字列名	既定値
inputPlaceholderText	`Search for a name`
maxSelectionsPlaceHolder	`Max contacts added`
maxSelectionsAriaLabel	`Maximum contact selections reached`
noResultsFound	`We didn't find any matches.`
loadingMessage	`Loading...`
選択	`selected`
removeSelectedUser	`Remove`
selectContact	`select a contact`
suggestionsTitle	`Suggested contacts`

Microsoft Graph Toolkit でのピッカーコンポーネントのPeople

例

プロパティ

選択済みのユーザー

CSS カスタムプロパティ

イベント

テンプレート

Microsoft Graph のアクセス許可

ユーザー入力状態に関係なく

ユーザー入力がない場合

ユーザーが検索語句を指定した場合

サブコンポーネント

認証

キャッシュ

より制御を行うために拡張する

ローカリゼーション

フィードバック

フィードバック

その他のリソース

Microsoft Graph Toolkit でのピッカー コンポーネントのPeople

例

プロパティ

選択済みのユーザー

CSS カスタム プロパティ

イベント

テンプレート

Microsoft Graph のアクセス許可

ユーザー入力状態に関係なく

ユーザー入力がない場合

ユーザーが検索語句を指定した場合

サブコンポーネント

認証

キャッシュ

より制御を行うために拡張する

ローカリゼーション

フィードバック

フィードバック

その他のリソース

Microsoft Graph Toolkit でのピッカーコンポーネントのPeople

CSS カスタムプロパティ