composant sélecteur de Personnes dans le Kit de ressources Microsoft Graph

Article
03/15/2023
8 minutes de lecture

Vous pouvez utiliser le mgt-people-picker composant web pour rechercher des personnes et/ou des groupes. Par défaut, le composant recherche toutes les personnes et tous les utilisateurs de l’organisation, mais vous pouvez modifier le comportement pour rechercher également des groupes, ou uniquement des groupes. Vous pouvez également filtrer la recherche sur un groupe spécifique. En outre, vous pouvez autoriser l’utilisateur à entrer et à sélectionner n’importe quelle adresse e-mail.

Exemple

L’exemple suivant montre le mgt-people-picker composant . Commencez à rechercher un nom pour voir le rendu des résultats et utilisez l’éditeur de code pour voir comment les propriétés modifient le comportement du composant.

Ouvrir cet exemple dans mgt.dev

Propriétés

Par défaut, le mgt-people-picker composant récupère des personnes à partir des /me/people points de terminaison et /users . Utilisez les attributs suivants pour modifier ce comportement.

Attribut	Propriété	Description
show-max	showMax	Valeur numérique pour indiquer le nombre maximal de personnes à afficher. la valeur par défaut est 6.
group-id	groupId	Valeur de chaîne qui appartient à un groupe défini par Microsoft Graph pour filtrer davantage les résultats de la recherche.
transitive-search	transitiveSearch	Une valeur booléenne permettant d’effectuer une recherche transitive retournant une liste plate de tous les membres imbriqués ( par défaut la recherche transitive n’est pas utilisée).
type	type	Type d’entités à rechercher. Les options disponibles sont les suivantes : `person`, `group`, `any`. La valeur par défaut est `person`. Cet attribut n’a aucun effet si `group-id` la propriété est définie.
user-type	userType	Type d’utilisateur à rechercher. Les options disponibles sont les suivantes : `any`, `user` pour les utilisateurs de l’organisation ou `contact` pour les contacts. La valeur par défaut est `any`.
group-type	groupType	Type de groupe à rechercher. Les options disponibles sont les suivantes : `unified`, `security`, `mailenabledsecurity`, `distribution`, `any`. La valeur par défaut est `any`. Cet attribut n’a aucun effet si la `type` propriété a la valeur `person`.
personnes sélectionnées	selectedPeople	Tableau de personnes sélectionnées. Définissez cette valeur pour sélectionner des personnes par programmation.
contacts	contacts	Tableau de personnes trouvées et affichées dans le résultat de la recherche
Espace réservé	Espace réservé	Texte par défaut qui s’affiche pour expliquer comment utiliser le composant. La valeur par défaut est `Start typing a name`.
default-selected-user-ids	defaultSelectedUserIds	Lorsqu’une chaîne d’ID utilisateur Microsoft Graph séparés par des virgules est fournie, le composant affiche les utilisateurs respectifs comme sélectionnés lors de l’initialisation.
default-selected-group-ids	defaultSelectedGroupIds	À l’instar des id utilisateur sélectionnés par défaut, lorsqu’une chaîne d’ID de groupe Microsoft Graph séparés par des virgules est fournie, le composant affiche les groupes respectifs comme sélectionnés lors de l’initialisation.
mode sélection	selectionMode	Permet d’indiquer s’il faut autoriser la sélection de plusieurs éléments (utilisateurs ou groupes) ou d’un seul élément. Les options disponibles sont : `single`, `multiple`. La valeur par défaut est `multiple`.
désactivé	désactivé	Définit si le sélecteur de personnes est désactivé. Lorsqu’il est désactivé, l’utilisateur n’est pas en mesure de rechercher ou de sélectionner des personnes.
disable-images	disableImages	Définit s’il faut désactiver l’extraction et l’affichage des images de personne. Quand la valeur `true`est définie sur , les initiales de l’utilisateur sont affichées à la place.
allow-any-email	allowAnyEmail	Indique si le sélecteur de personnes peut accepter des adresses e-mail sans sélectionner une personne. La valeur par défaut est `false`. Lorsque vous avez fini de taper une adresse e-mail, vous pouvez appuyer sur les touches virgule (`,`), point-virgule (`;`), tabulation ou entrer pour l’ajouter.
user-ids	userIds	Chaîne d’ID utilisateur séparés par des virgules. Ils s’affichent uniquement dans le menu déroulant ou dans les résultats de votre recherche lorsque vous tapez une requête. Par exemple `48d31887-5fad-4d73-a9f5-3c356e68a038,24fcbca3-c3e2-48bf-9ffc-c7f81b81483d` , affiche uniquement les deux utilisateurs dans la liste déroulante lorsque l’entrée est prioritaire. Lorsque vous tapez un texte de recherche, il retourne des résultats qui correspondent aux utilisateurs dans les deux ID utilisateur uniquement.
filtres utilisateur	userFilters	Spécifie les critères de filtre à utiliser lors de l’interrogation du point de terminaison des utilisateurs. Il doit être défini sur `user-typeuser` ou `contact`. Par défaut, le `user-type` est `any` et cela conduit l’interrogation à avoir lieu dans le bloc de point de `people` terminaison. Exemple : `user-filters="startsWith(displayName,'a')"`. Cet attribut est facultatif. En savoir plus sur la prise en charge du filtre sur les propriétés utilisateur des objets d’annuaire Azure AD.
group-filters	groupFilters	Spécifie les critères de filtre à utiliser lors de l’interrogation du point de `groups` terminaison. Il nécessite que le `type` soit défini sur `group`. Exemple : `group-filters="startsWith(displayName,'a')"`. Cet attribut est facultatif.
people-filters	peopleFilters	Spécifie les critères de filtre à utiliser lors de l’interrogation du point de `people` terminaison. Il est utilisé tel qu’il est. Exemple : `people-filters="jobTitle eq 'Web Marketing Manager'"`. Cet attribut est facultatif. En savoir plus sur le filtrage et les fonctionnalités prises en charge sur la ressource people.
group-ids	groupIds	Chaîne d’ID de groupe séparés par des virgules. Les résultats disponibles doivent être limités aux groupes spécifiés. Les utilisateurs qui apparaîtront dans le menu déroulant et via l’expérience de recherche doivent provenir uniquement des ID de groupe spécifiés. Par exemple, `02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23` affiche uniquement les utilisateurs appartenant à ces groupes. Lorsque vous tapez un texte de recherche, il retourne des résultats qui correspondent uniquement aux utilisateurs des deux ID de groupe. Cette propriété n’est pas utilisée si `group-id` est défini. Si la propriété est définie, est `group` par `type` défaut et `transitive-search` par `true` défaut. Si est `group-type` défini avec la propriété , peut `type` être `any` ou `group`. Si a la `type` valeur `person`, la propriété n’est pas utilisée.
aria-label	ariaLabel	Chaîne fournie pour aider les technologies assassitives à fournir un contexte pour le sélecteur de personnes.

Voici un show-max exemple.

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

Personnes sélectionnées

La section personnes sélectionnées du composant affiche chaque personne choisie par le développeur ou l’utilisateur.

mgt-people-picker

Vous pouvez remplir les données de personnes sélectionnées en effectuant l’une des opérations suivantes :

Définition directe de la selectedPeople propriété, comme illustré dans l’exemple suivant.

// personObject = User or Person from Microsoft Graph
document.querySelector('mgt-people-picker').selectedPeople.push(personObject);

Utilisation de la selectUsersById() méthode , qui accepte un tableau d’ID utilisateur Microsoft Graph pour rechercher les détails de l’utilisateur associé à la sélection.

Note: Si aucun utilisateur n’est trouvé pour un id, aucune donnée n’est rendue pour ce id.
```
// id = Microsoft graph User "id"
document.querySelector('mgt-people-picker').selectUsersById(["id","id"])
```
Utilisation de la selectGroupsById() méthode , qui accepte un tableau d’ID de groupe Microsoft Graph pour rechercher le ou les groupes avec les utilisateurs associés.
```
// groupid = Microsoft graph group "id"
document.querySelector('mgt-people-picker').selectGroupsById(["groupid","groupid"])
```

Événements

Les événements suivants sont déclenchés à partir du composant .

Événement	Quand est-il émis	Données personnalisées	Annulable	Bulles	Fonctionne avec un modèle personnalisé
`selectionChanged`	L’utilisateur a ajouté ou supprimé une personne de la liste des personnes sélectionnées/sélectionnées	Tableau de personnes sélectionnées, où une personne peut être un utilisateur Graph, une personne ou un contact avec une propriété supplémentaire `personImage` qui contient l’URL de la photo de l’utilisateur	Non	Non	Oui, sauf si vous remplacez le modèle par défaut

Pour plus d’informations sur la gestion des événements, consultez événements.

Propriétés personnalisées CSS

Le mgt-people-picker composant définit les propriétés personnalisées CSS suivantes.

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 */
}

Modèles

mgt-people-picker prend en charge plusieurs modèles que vous pouvez utiliser pour remplacer certaines parties du composant. Pour spécifier un modèle, incluez un <template> élément à l’intérieur d’un composant et définissez la data-type valeur sur l’une des valeurs suivantes.

Type de données	Contexte de données	Description
Valeur par défaut.	null : aucune donnée	Modèle utilisé pour remplacer le rendu de l’ensemble du composant.
Chargement	null : aucune donnée	Modèle utilisé pour afficher l’état du sélecteur lors de l’exécution de la requête au graphique.
error	null : aucune donnée	Modèle utilisé si la recherche utilisateur ne renvoie aucun utilisateur.
no-data	null : aucune donnée	Autre modèle utilisé si la recherche utilisateur ne renvoie aucun utilisateur.
selected-person	person : objet de détails de la personne	Modèle à afficher pour les personnes sélectionnées.
Personne	person : objet de détails de la personne	Modèle pour afficher les personnes dans la liste déroulante.

Les exemples suivants montrent comment utiliser le error modèle.

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

Autorisations de Microsoft Graph

Ce composant utilise les API et autorisations Microsoft Graph suivantes.

Configuration	Autorisation	API
`group-id` Ensemble	Personnes. Read, User.Read.All, GroupMember.Read.All	/groups/${groupId}/members
`type` défini sur `Person` ou `any`	People.Read	/me/people
`type` définir sur `Group` ou rechercher des utilisateurs et `type` définir sur `Group` ou `any`	Group.Read.All	/Groupes
`default-selected-user-ids` Ensemble	User.ReadBasic.All	/Utilisateurs
recherche d’utilisateurs et `type` définissez sur `Person` ou `any`	Personnes. Read, User.ReadBasic.All	/me/people, /users

Authentification

Le contrôle utilise le fournisseur d’authentification global décrit dans la documentation sur l’authentification.

Cache

Magasin d’objets	Données mises en cache	Remarques
`groups`	Liste des groupes	Utilisé lorsque `type` est défini sur `PersonType.group`
`people`	Liste de personnes	Utilisé lorsque `type` est défini sur `PersonType.person` ou `PersonType.any`
`users`	Liste des utilisateurs	Utilisé lorsqu’il `groupId` est spécifié

Pour plus d’informations sur la configuration du cache, consultez Mise en cache .

Étendre pour plus de contrôle

Pour les scénarios plus complexes ou une expérience utilisateur vraiment personnalisée, ce composant expose plusieurs protected render* méthodes de remplacement dans les extensions de composant.

Méthode	Description
renderInput	Affiche la zone de texte d’entrée.
renderSelectedPeople	Affiche les jetons de personnes sélectionnés.
renderSelectedPerson	Affiche un jeton de personne individuel.
renderFlyout	Affiche le chrome du menu volant.
renderFlyoutContent	Affiche l’état approprié dans le menu volant des résultats.
renderLoading	Affiche l’état de chargement.
renderNoData	Affiche l’état lorsqu’aucun résultat n’est trouvé pour la requête de recherche.
renderSearchResults	Affiche la liste des résultats de la recherche.
renderPersonResult	Affiche un résultat de recherche de personne individuelle.