注意
Microsoft Graph Toolkit は非推奨です。 2025 年 9 月 1 日から、2026 年 8 月 28 日に完全な退職が予定されています。 開発者は、Web エクスペリエンスを構築するために、Microsoft Graph SDK またはその他のサポートされている Microsoft Graph ツールを使用して移行する必要があります。 詳細については、 非推奨のお知らせを参照してください。
mgt-people-picker Web コンポーネントを使用して、ユーザー、グループ、またはその両方を検索できます。 既定では、コンポーネントはorganization内のすべてのユーザーとユーザーを検索しますが、動作を変更してグループを検索することも、グループのみを検索することもできます。 また、特定のグループに絞り込んで検索することもできます。 また、ユーザーが任意のメール アドレスを入力して選択できるようにすることもできます。
例
次の使用例では mgt-people-picker コンポーネントを表示します。 名前の検索を開始してレンダリングされた結果を表示し、コード エディターを使用して、プロパティ がコンポーネントの動作をどのように変更させるかを確認することができます。
プロパティ
既定値では、mgt-people-picker コンポーネントは /me/people および /users エンドポイントからユーザーを取得します。 次の属性を使用して、この動作を変更します。
| 属性 | プロパティ | 説明 |
|---|---|---|
| show-max | showMax | 表示するユーザーの最大数を示す数値。 既定値は 6 です。 |
| group-id | groupId | 検索結果をさらにフィルター処理するために、Microsoft Graph で定義されたグループに属する文字列値。 |
| transitive-search | transitiveSearch | 入れ子になったすべてのメンバーのフラット リストを返す推移的検索を実行するためのブール値 。既定では推移的検索は使用されません。 |
| type | 型 | 検索するメール メッセージの種類。 使用可能なオプションは、person、group、および any です。 既定値は、any です。 この属性が group に設定され、 group-id または group-ids が設定されている場合、 userFilters と peopleFilters は効果がありません。 |
| user-type | userType | 検索するユーザーの種類。 使用可能なオプションは、 any、組織ユーザーの user 、または連絡先の 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 | ユーザーのエンドポイントに対してクエリを実行するときに使用するフィルター条件を指定します。
user-typeをuserまたはcontactに設定する必要があります。 既定では、 user-type は any され、 people エンドポイント ブロックでクエリが実行されます。 例: user-filters="startsWith(displayName,'a')"。 この属性は省略可能です。
ディレクトリ オブジェクトのユーザー プロパティに対するフィルター処理のサポートの詳細について説明します。 User.ReadBasic.All権限のみを使用すると、使用可能なプロパティの一覧が制限され、コンポーネントはそれに応じて調整されます。
User.ReadBasic.All スコープでは、id、displayName、givenName、mail、securityIdentifier、surname、userPrincipalNameの各プロパティに制限されます。 既定では、このコンポーネントは jobTitle プロパティと department プロパティを使用します。
mail プロパティは、User.ReadBasic.Allが使用されていて、他のプロパティがレンダリングされない場合に、jobTitleのフォールバックとして機能します。
User.Read.Allアクセス許可を使用して、その他のプロパティに対してクエリを実行します。 |
| group-filters | groupFilters |
groups エンドポイントのクエリを実行するときに使用するフィルター条件を指定します。
typeを group に設定する必要があります。 例: 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はanyまたはgroupできます。
typeがpersonされている場合、プロパティは使用されません。 |
| aria-label | ariaLabel | 支援技術がユーザー選択ウィンドウのコンテキストを提供するのに役立つ文字列。 |
次の例は、 show-max 属性を示しています。
<mgt-people-picker show-max="4"> </mgt-people-picker>
選択済みのユーザー
コンポーネントの選択済みのユーザー セクションは、開発者またはユーザーによって選ばれた各ユーザーを表示します。
選択したユーザー データに次のオプションを設定できます。
以下の例のように、
selectedPeopleプロパティを直接設定します。// personObject is the User or Person object from Microsoft Graph document.querySelector("mgt-people-picker").selectedPeople.push(personObject);microsoft graph ユーザー ID の配列を受け入れて、選択に関連するユーザーの詳細を検索する
selectUsersById()メソッドを使用します。注：
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が設定されると、これは $filter パラメーターとして $count=true を使用して要求に追加され、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 パラメーターとして追加されます |
以下の構成が設定されている user-ids に依存する場合、に me のエントリがある場合 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がpersonまたはgroupされている場合、/microsoft.graph.userまたは/microsoft.graph.groupが要求パスに追加されます |
group-id AND transitive-search が true に設定されている |
GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All | /groups/${groupId}/transitiveMembers |
typeがpersonまたはgroupされている場合、/microsoft.graph.userまたは/microsoft.graph.groupが要求パスに追加されます |
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 |
typeがpersonされると、/microsoft.graph.userが要求パスに追加されます |
group-ids AND type が group ではなく、 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が要求パスに追加されます |
type が group され、 group-id も group-ids も設定されていません |
GroupMember.Read.All、Group.Read.All、Directory.Read.All、Group.ReadWrite.All、Directory.ReadWrite.All | /groups | |
type を person または any に設定し、 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 を person または any に設定し、 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 を person または any に設定し、 user-filters が設定されていないか、 user-type が user にも設定されていません contact |
People.Read、People.Read.All | /me/people |
people-filtersが設定されている場合、またはuser-typeがanyされていない場合は、$filter パラメーターが要求に追加されます。
user-typeがcontactされていない場合は、要求でX-PeopleQuery-QuerySources: 'Mailbox,Directory' ヘッダーが設定されます |
ユーザーが検索語句を指定した場合
| 構成 | アクセス許可 | API | 追加オプション |
|---|---|---|---|
group-id が設定されている |
GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All | /groups/${groupId}/members |
typeがpersonまたはgroup/microsoft.graph.userまたは/microsoft.graph.groupが要求パスに追加されると、$filter パラメーターはユーザー入力値で構成されます |
group-id が設定され、 transitive-search が true である |
GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All | /groups/${groupId}/transitiveMembers |
typeがpersonまたはgroup/microsoft.graph.userまたは/microsoft.graph.groupが要求パスに追加されると、$filter パラメーターはユーザー入力値で構成されます |
group-idが設定されておらず、personまたはanyに設定type、user-typeがanyに設定され、group-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が設定されておらず、personまたはanyに設定typeuser-typeanyに設定され、group-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を person または any に設定し、any に設定されていないuser-typeuser-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 または any に設定し、anyに設定user-typegroup-idsが設定されておらず、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' ヘッダーが設定されます |
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 |