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

  • [アーティクル]

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

例

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

この例を 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-id プロパティが設定されている場合は影響を受けません。
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 です。
無効 無効 ユーザー 選択ウィンドウを無効にするかどうかを設定します。 無効にすると、ユーザーはユーザーを検索または選択できません。
disable-images disableImages 人物画像のフェッチと表示を無効にするかどうかを設定します。 に true設定すると、代わりにユーザーのイニシャルが表示されます。
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')"。 この属性は省略可能です。 Azure AD ディレクトリ オブジェクトのユーザー プロパティに対するフィルター処理のサポートの詳細について説明します。
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 ユーザー選択ウィンドウのコンテキストを提供するために、assitive テクノロジを支援するために提供される文字列。

次に show-max の例を示します。

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

選択済みのユーザー

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

mgt-people-picker

以下のいずれかを行うことで、選択済みのユーザー データを入力することができます。

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

    // personObject = User or Person 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 Graph グループ ID の配列を受け入れて、関連付けられているユーザーとのグループを検索します。

    // groupid = Microsoft graph group "id"
document.querySelector('mgt-people-picker').selectGroupsById(["groupid","groupid"])

イベント

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

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

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

CSS カスタム プロパティ

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

mgt-people-picker {
    --input-border: 2px rgba(255, 255, 255, 0.5) solid; /* sets all input area border */

      /* OR individual input border sides */
    --input-border-bottom: 2px rgba(255, 255, 255, 0.5) solid;
    --input-border-right: 2px rgba(255, 255, 255, 0.5) solid;
    --input-border-left: 2px rgba(255, 255, 255, 0.5) solid;
    --input-border-top: 2px rgba(255, 255, 255, 0.5) solid;

    --input-background-color: #1f1f1f; /* input area background color */
    --input-border-color--hover: #008394; /* input area border hover color */
    --input-border-color--focus: #0f78d4; /* input area border focus color */

    --dropdown-background-color: #ca00ca; /* selection area background color */
    --dropdown-item-hover-background: purple; /* person background color on hover */
    --dropdown-item-text-color: white; /* person item text color */
    --dropdown-item-text-hover-color: gold; /* person item text color on hover */
    --selected-person-background-color: #f1f1f1; /* person item background color */
    
    --color: white; /* input area border focus color */
    --placeholder-color: #f1f1f1; /* placeholder text color */
    --placeholder-color--focus: rgba(255, 255, 255, 0.8); /* placeholder text focus color */
}

テンプレート

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 とアクセス許可を使用します。

構成 アクセス許可 API
group-id 設定 People。読み取り、User.Read.All、GroupMember.Read.All /groups/${groupId}/members
typeまたは に設定するPersonany People.Read /me/people
type を に Group 設定するか、ユーザーを検索し、 type または に設定します Group 。 any Group.Read.All /groups
default-selected-user-ids 設定 User.ReadBasic.All /users
ユーザーを検索し、 type または に設定しますPersonany People。Read、User.ReadBasic.All /me/people, /users

認証

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

キャッシュ

オブジェクト ストア キャッシュされたデータ 注釈
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 個々のユーザーの検索結果を表示します。