Microsoft Graph Toolkit の People ピッカー コンポーネント
Web コンポーネントを mgt-people-picker 使用して、ユーザー、グループ、またはその両方を検索できます。 既定では、コンポーネントは組織内のすべてのユーザーとユーザーを検索しますが、動作を変更してグループを検索することも、グループのみを検索することもできます。 また、特定のグループに絞り込んで検索することもできます。 また、ユーザーが任意のメール アドレスを入力して選択できるようにすることもできます。
例
次の使用例では 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-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>
選択済みのユーザー
コンポーネントの選択済みのユーザー セクションは、開発者またはユーザーによって選ばれた各ユーザーを表示します。
選択したユーザー データに次のオプションを設定できます。
以下の例のように、
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 |