Composant sélecteur de personnes dans Microsoft Graph Toolkit

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 extrait les personnes des points de terminaison et /users des /me/people points de terminaison. 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.
iD de groupe groupId Valeur de chaîne qui appartient à un groupe microsoft Graph défini pour un filtrage supplémentaire des résultats de la recherche.
transitive-search transitiveSearch 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.
type de groupe 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é est définie sur person.
selected-people 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 semble 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 d’utilisateur Microsoft Graph séparés par des virgules est fournie, le composant affiche les utilisateurs respectifs comme sélectionné lors de l’initialisation.
default-selected-group-ids defaultSelectedGroupIds Comme pour les ID d’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é 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 les suivantes : 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 d’images de personne. Lorsque la valeur est truedéfinie sur , les initiales 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 de personne. La valeur par défaut est false. Lorsque vous avez fini de taper une adresse e-mail, vous pouvez appuyer sur des virgules (,), des points-virgules (;), tabulation ou entrer des clés pour l’ajouter.
user-ids userIds Chaîne d’ID d’utilisateur séparés par des virgules. Elles apparaissent uniquement dans le menu déroulant ou vos résultats de 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 ciblée. Lorsque vous tapez un texte de recherche, il retourne des résultats qui correspondent aux utilisateurs des deux ID d’utilisateur uniquement.
filtres utilisateur userFilters Spécifie les critères de filtre à utiliser lors de l’interrogation du point de terminaison utilisateur. Il requiert la user-type valeur à user définir sur ou contact. Par défaut, cette user-type any opération entraîne l’interrogation dans le bloc de people point de 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.
filtres de groupe groupFilters Spécifie les critères de filtre à utiliser lors de l’interrogation du point de groups terminaison. Il requiert que la type valeur soit définie groupsur . Exemple : group-filters="startsWith(displayName,'a')". Cet attribut est facultatif.
filtres de personnes 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 contacts.
ids de groupe 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 ne doivent provenir que 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 aux utilisateurs des deux ID de groupe uniquement. Cette propriété n’est pas utilisée si group-id elle est définie. Si la propriété est définie, elle type l’est group par défaut et trnsitive-search true par défaut. Si la group-type valeur est définie avec la propriété, la type valeur peut être any ou group. Si c’est le type cas person, la propriété n’est pas utilisée.

Voici un show-max exemple.

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

Personnes sélectionnées

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

mgt-people-picker

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

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

    // personObject = User or Person from Microsoft Graph
    document.querySelector('mgt-people-picker').selectedPeople.push(personObject);
    
  • À l’aide de la selectUsersById() méthode, qui accepte un tableau d’ID d’utilisateur Microsoft Graph pour rechercher les détails utilisateur associés à la sélection.

    Note: Si aucun utilisateur n’est trouvé pour un id, aucune donnée n’est rendue pour cela id.

    // id = Microsoft graph User "id"
    document.querySelector('mgt-people-picker').selectUsersById(["id","id"])
    
  • À l’aide 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 dans 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 les é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: #1f1f1f; /* selection area background color */
    --dropdown-item-hover-background: #333d47; /* person background 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 la demande de graphe.
error Null : aucune donnée Modèle utilisé si la recherche utilisateur ne retourne aucun utilisateur.
no-data Null : aucune donnée Autre modèle utilisé si la recherche utilisateur ne retourne aucun utilisateur.
selected-person person: The person details object Modèle pour afficher les personnes sélectionnées.
person person: The person details object 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 People.Read, User.Read.All, GroupMember.Read.All /groups/${groupId}/members
type défini sur Person ou any People.Read /me/people
type``Group définir ou rechercher des utilisateurs et type définir sur Group ouany Group.Read.All /groups
default-selected-user-ids Ensemble User.ReadBasic.All /users
rechercher des utilisateurs et type définir sur Person ou any People.Read, User.ReadBasic.All /me/people, /users

Authentification

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

Cache

Magasin d’objets Données mises en cache Remarques
groups Liste des groupes Utilisé quand type est défini sur PersonType.group
people Liste des personnes Utilisé quand 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 la mise en cache.

Étendre pour plus de contrôle

Pour des scénarios plus complexes ou une expérience utilisateur réellement 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 individuelle.
renderFlyout Affiche le chrome de 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 recherche.
renderPersonResult Affiche un résultat de recherche de personne individuelle.