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 検索するメール メッセージの種類。 使用可能なオプションは、persongroup、および any です。 既定値は、any です。 この属性が にgroup設定され、または group-idsgroup-id設定されている場合、および peopleFiltersuserFilters 効果はありません。
user-type userType 検索するユーザーの種類。 使用可能なオプションは、anyuser組織のユーザーの場合、または連絡先の場合contactです。 既定値は、any です。
group-type groupType 検索するグループの種類。 使用可能なオプションは、unifiedsecuritymailenabledsecuritydistribution、および 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 選択したユーザーの人物カードを表示する動作を設定します。 使用できる値は、 nonehover または 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 、このプロパティは使用されません。 プロパティが設定されている場合、 typegroup 既定で、 transitive-search 既定では です truegroup-typeが プロパティで設定されている場合は、 type または を指定groupできますanytypepersonの場合、 プロパティは使用されません。
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
typegroup であり、設定も設定もgroup-idsされていませんgroup-id GroupMember.Read.All、Group.Read.All、Directory.Read.All、Group.ReadWrite.All、Directory.ReadWrite.All /groups
typeまたは anyperson設定され、 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または anyperson設定され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または anyperson設定され、設定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 が または anyperson設定され、 user-type が にanygroup-ids設定されていない GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All /groups/${groupId}/members typeperson/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 typeperson/microsoft.graph.user要求パスに追加されると、$filterパラメーターはユーザー入力値で構成されます
typeを または anyperson設定し、 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 が設定されておらず、 typegroup または 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 が設定され、 typegroup または 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 ユーザーの一覧 が または に設定されている場合 typePersonType.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