Personenauswahlkomponente im Microsoft Graph-Toolkit
Sie können die mgt-people-picker
Webkomponente verwenden, um nach Personen, Gruppen oder beidem zu suchen. Standardmäßig sucht die Komponente nach allen Personen und Benutzern in der Organisation, aber Sie können das Verhalten ändern, um auch nach Gruppen oder nur nach Gruppen zu suchen. Sie können die Suche auch nach einer bestimmten Gruppe filtern. Sie können dem Benutzer auch erlauben, eine beliebige E-Mail-Adresse einzugeben und auszuwählen.
Beispiel
Das folgende Beispiel zeigt die mgt-people-picker
-Komponente. Beginnen Sie mit der Suche nach einem Namen, um das Rendern der Ergebnisse anzuzeigen, und verwenden Sie den Code-Editor, um zu sehen, wie Eigenschaften das Verhalten der Komponente ändern.
Eigenschaften
Standardmäßig ruft die mgt-people-picker
Komponente Personen aus den /me/people
Endpunkten und /users
ab. Verwenden Sie die folgenden Attribute, um dieses Verhalten zu ändern.
Attribut | Eigenschaft | Beschreibung |
---|---|---|
show-max | showMax | Ein Zahlenwert, der die maximale Anzahl der anzuzeigenden Personen angibt. Der Standardwert ist 6. |
group-id | groupId | Ein Zeichenfolgenwert, der zu einer von Microsoft Graph definierten Gruppe zum weiteren Filtern der Suchergebnisse gehört. |
transitive-search | transitiveSearch | Ein boolescher Wert zum Ausführen einer transitiven Suche, die eine flache Liste aller geschachtelten Elemente zurückgibt – standardmäßig wird keine transitive Suche verwendet. |
type | type | Der Typ der Entitäten, nach denen gesucht werden soll. Verfügbare Optionen: person , group , any . Der Standardwert ist any . Wenn dieses Attribut auf group festgelegt ist und entweder group-id oder group-ids festgelegt sind, userFilters haben und peopleFilters keine Auswirkung. |
user-type | userType | Der Typ des zu suchden Benutzers. Verfügbare Optionen sind: any , user für Organisationsbenutzer oder contact für Kontakte. Der Standardwert ist any . |
group-type | groupType | Der bzw. die zu suchden Gruppentypen. Verfügbare Optionen sind: unified , security , mailenabledsecurity , distribution , any . Der Standardwert ist any . Dieses Attribut hat keine Auswirkung, wenn die type -Eigenschaft auf person festgelegt ist. Dieses Attribut akzeptiert eine durch Trennzeichen getrennte Liste von Werten. Die -Eigenschaft akzeptiert ein Array oder Werte. |
ausgewählte Personen | selectedPeople | Ein Array ausgewählter Personen. Legen Sie diesen Wert fest, um Personen programmgesteuert auszuwählen. |
Kontakte | Kontakte | Ein Array von Personen, die im Suchergebnis gefunden und gerendert wurden |
Platzhalter | Platzhalter | Der Standardtext, der die Verwendung der Komponente erläutert. Der Standardwert ist Start typing a name . |
default-selected-user-ids | defaultSelectedUserIds | Wenn eine Zeichenfolge mit durch Trennzeichen getrennten Microsoft Graph-Benutzer-IDs bereitgestellt wird, rendert die Komponente die entsprechenden Benutzer bei der Initialisierung als ausgewählt. |
default-selected-group-ids | defaultSelectedGroupIds | Ähnlich wie bei default-selected-user-ids rendert die Komponente die entsprechenden Gruppen bei der Initialisierung, wenn eine Zeichenfolge aus durch Trennzeichen getrennten Microsoft Graph-Gruppen-IDs bereitgestellt wird. |
Auswahlmodus | selectionMode | Wird verwendet, um anzugeben, ob das Auswählen mehrerer Elemente (Benutzer oder Gruppen) oder nur ein einzelnes Element zulässig ist. Verfügbare Optionen sind: single , multiple . Der Standardwert ist multiple . |
deaktiviert | deaktiviert | Legt fest, ob die Personenauswahl deaktiviert ist. Wenn er deaktiviert ist, kann der Benutzer keine Personen suchen oder auswählen. Der Standardwert ist false . |
disable-images | disableImages | Legt fest, ob das Abrufen und Anzeigen von Personenbildern deaktiviert werden soll. Wenn auf true festgelegt ist, werden stattdessen Benutzerinitialen angezeigt. Der Standardwert ist false . |
Personenkarte | personCardInteraction | Legt das Verhalten fest, um die Personenkarte einer ausgewählten Person anzuzeigen. Die zulässigen Werte sind none , hover oder click . Der Standardwert ist none . |
allow-any-email | allowAnyEmail | Gibt an, ob die Personenauswahl E-Mail-Adressen akzeptieren kann, ohne eine Person auszuwählen. Der Standardwert ist false . Wenn Sie mit der Eingabe einer E-Mail-Adresse fertig sind, können Sie komma (, ), semikolon (; ), TAB drücken oder Tasten eingeben, um sie hinzuzufügen. |
Benutzer-IDs | UserIds | Eine Zeichenfolge von durch Trennzeichen getrennten Benutzer-IDs. Sie werden nur im Dropdownmenü oder in Ihren Suchergebnissen angezeigt, wenn Sie eine Abfrage eingeben. Beispielsweise zeigt nur die beiden Benutzer in der Dropdownliste an, 48d31887-5fad-4d73-a9f5-3c356e68a038,24fcbca3-c3e2-48bf-9ffc-c7f81b81483d wenn die Eingabe den Fokus hat. Wenn Sie einen Suchtext eingeben, werden nur Ergebnisse zurückgegeben, die den Benutzern in den beiden Benutzer-IDs entsprechen. |
Benutzerfilter | userFilters | Gibt die Filterkriterien an, die beim Abfragen des Benutzerendpunkts verwendet werden sollen. Hierfür muss auf user-type oder contact festgelegt user werden. Standardmäßig ist any und user-type führt dazu, dass die Abfrage im people Endpunktblock stattfindet. Beispiel: user-filters="startsWith(displayName,'a')" . Dieses Attribut ist optional. Erfahren Sie mehr über die Unterstützung für das Filtern nach Benutzereigenschaften von Verzeichnisobjekten. Wenn Sie nur die User.ReadBasic.All Berechtigung verwenden, ist die Liste der verfügbaren Eigenschaften begrenzt, und die Komponente passt sich entsprechend an. Im Bereich User.ReadBasic.All sind Sie auf die folgenden Eigenschaften beschränkt: id , displayName , givenName , , mail securityIdentifier , surname und userPrincipalName . Standardmäßig verwendet diese Komponente die jobTitle Eigenschaften und department . Die mail -Eigenschaft dient als Fallback für jobTitle den Fall, wenn User.ReadBasic.All verwendet wird und andere Eigenschaften nicht gerendert werden. Verwenden Sie die User.Read.All Berechtigung, um weitere Eigenschaften abzufragen. |
Gruppenfilter | groupFilters | Gibt die Filterkriterien an, die beim Abfragen des Endpunkts groups verwendet werden sollen. Es muss auf type festgelegt group werden. Beispiel: group-filters="startsWith(displayName,'a')" . Dieses Attribut ist optional. |
Personenfilter | peopleFilters | Gibt die Filterkriterien an, die beim Abfragen des Endpunkts people verwendet werden sollen. Es wird so verwendet, wie es ist. Beispiel: people-filters="jobTitle eq 'Web Marketing Manager'" . Dieses Attribut ist optional. Erfahren Sie mehr über das Filtern und die unterstützten Funktionen für die Ressource people. |
Gruppen-IDs | groupIds | Eine Zeichenfolge von durch Trennzeichen getrennten Gruppen-IDs. Die verfügbaren Ergebnisse sollten auf die angegebenen Gruppen beschränkt sein. Benutzer, die im Dropdownmenü und über die Suchoberfläche angezeigt werden, sollten nur von den angegebenen Gruppen-IDs stammen. Zeigt beispielsweise nur Benutzer an, 02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23 die zu diesen Gruppen gehören. Wenn Sie einen Suchtext eingeben, werden nur Ergebnisse zurückgegeben, die den Benutzern in den beiden Gruppen-IDs entsprechen. Diese Eigenschaft wird nicht verwendet, wenn group-id definiert ist. Wenn die -Eigenschaft festgelegt ist, ist group standardmäßig type und transitive-search true standardmäßig. Wenn mit group-type der -Eigenschaft festgelegt wird, kann oder type group seinany . Wenn ist type person , wird die -Eigenschaft nicht verwendet. |
aria-label | ariaLabel | Eine Zeichenfolge, die bereitgestellt wird, um Hilfstechnologien bei der Bereitstellung von Kontext für die Personenauswahl zu unterstützen. |
Das folgende Beispiel zeigt das show-max
-Attribut.
<mgt-people-picker show-max="4"> </mgt-people-picker>
Ausgewählte Personen
Der ausgewählte Personenabschnitt der Komponente rendert jede vom Entwickler oder Benutzer ausgewählte Person.
Sie können ausgewählte Personendaten mit den folgenden Optionen auffüllen:
Direktes Festlegen der
selectedPeople
Eigenschaft, wie im folgenden Beispiel gezeigt.// personObject is the User or Person object from Microsoft Graph document.querySelector("mgt-people-picker").selectedPeople.push(personObject);
selectUsersById()
Verwenden der -Methode, die ein Array von Microsoft Graph-Benutzer-IDs akzeptiert, um zugeordnete Benutzerdetails für die Auswahl zu finden.Anmerkung: Wenn kein Benutzer für
id
gefunden wird, werden keine Daten für diesenid
gerendert.// id = Microsoft graph User "id" document.querySelector("mgt-people-picker").selectUsersById(["id", "id"]);
Verwenden sie die
selectGroupsById()
-Methode, die ein Array von Microsoft Graph-Gruppen-IDs akzeptiert, um die Gruppen mit zugeordneten Benutzern zu finden.// groupid = Microsoft graph group "id" document .querySelector("mgt-people-picker") .selectGroupsById(["groupid", "groupid"]);
Benutzerdefinierte CSS-Eigenschaften
Die mgt-people-picker
Komponente definiert die folgenden benutzerdefinierten CSS-Eigenschaften.
<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;
}
Weitere Informationen finden Sie unter Formatieren von Komponenten.
Ereignisse
Die folgenden Ereignisse werden von der Komponente ausgelöst.
Ereignis | Wann wird es ausgegeben? | Benutzerdefinierte Daten | Annullierbar | Blasen | Funktioniert mit benutzerdefinierter Vorlage |
---|---|---|---|---|---|
selectionChanged |
Der Benutzer hat eine Person zur Liste ausgewählter/ausgewählter Personen hinzugefügt oder daraus entfernt. | Array ausgewählter Personen, wobei eine Person ein Graph-Benutzer, eine Person oder ein Kontakt mit einer anderen personImage Eigenschaft sein kann, die die URL des Fotos des Benutzers enthält |
Nein | Nein | Ja, es sei denn, Sie überschreiben die Standardvorlage. |
Weitere Informationen zum Behandeln von Ereignissen finden Sie unter Ereignisse.
Vorlagen
mgt-people-picker
unterstützt mehrere Vorlagen , mit denen Sie bestimmte Teile der Komponente ersetzen können. Um eine Vorlage anzugeben, schließen Sie ein <template>
Element in eine Komponente ein, und legen Sie auf data-type
einen der folgenden Werte fest.
Datentyp | Datenkontext | Beschreibung |
---|---|---|
Vorgabe | null: keine Daten | Die Vorlage, die verwendet wird, um das Rendering der gesamten Komponente zu überschreiben. |
Laden | null: keine Daten | Die Vorlage, die zum Rendern des Zustands der Auswahl verwendet wird, während die Anforderung an den Graph erfolgt. |
error | null: keine Daten | Die Vorlage, die verwendet wird, wenn die Benutzersuche keine Benutzer zurückgibt. |
Keine Daten | null: keine Daten | Eine alternative Vorlage, die verwendet wird, wenn die Benutzersuche keine Benutzer zurückgibt. |
ausgewählte Person | person: Das Objekt mit den Personendetails | Die Vorlage zum Rendern ausgewählter Personen. |
Person | person: Das Objekt mit den Personendetails | Die Vorlage zum Rendern von Personen in der Dropdownliste. |
In den folgenden Beispielen wird die Verwendung der error
Vorlage veranschaulicht.
<mgt-people-picker>
<template data-type="error">
<p>Sorry, no people were found</p>
</template>
</mgt-people-picker>
Microsoft Graph-Berechtigungen
Diese Komponente kann je nach Konfiguration und Zustand viele Abfragen durchführen. In der folgenden Tabelle sind die microsoft Graph-APIs und -Berechtigungen, die der Einfachheit halber erforderlich sind, in drei Abschnitte unterteilt. Für jede aufgerufene API muss der Benutzer mindestens über eine der aufgeführten Berechtigungen verfügen.
Unabhängig vom Benutzereingabezustand
Konfiguration | Berechtigung | API | Weitere Optionen |
---|---|---|---|
default-selected-user-ids Garnitur |
User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All | /users/$({userId} | Wenn user-filters festgelegt ist, wird dies $filter als Parameter zur Anforderung mit $count=true hinzugefügt, und der ConsistencyLevel: 'eventual' Header wird für die Anforderung festgelegt. |
default-selected-group-ids Garnitur |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All | /Gruppen | Wenn people-filters festgelegt ist, wird der Wert der Anforderung als $filter Parameter hinzugefügt. |
Wenn eine folgende Konfiguration davon abhängt user-ids , dass festgelegt wird, wenn ein Eintrag von me in vorhanden ist user-ids |
User.Read, User.ReadWrite | /Ich |
Wenn keine Benutzereingabe vorhanden ist
Konfiguration | Berechtigung | API | Weitere Optionen |
---|---|---|---|
group-id Garnitur |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All | /groups/${groupId}/members | Wenn type ist person oder group oder /microsoft.graph.user /microsoft.graph.group oder an den Anforderungspfad angefügt wird |
group-id Festlegen von AND transitive-search auf TRUE |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All | /groups/${groupId}/transitiveMembers | Wenn type ist person oder group oder /microsoft.graph.user /microsoft.graph.group oder an den Anforderungspfad angefügt wird |
group-ids Legen Sie AND type fest group |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All | /groups/${id} | |
group-ids
type AND ist NICHT festgelegt.group |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All | /groups/${groupId}/members | Wenn type ist person , wird dann /microsoft.graph.user an den Anforderungspfad angefügt. |
group-ids
type UND ist NICHT group FESTGELEGT UND transitive-search ist true. |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All | /groups/${groupId}/transitiveMembers | Wenn type ist person , wird dann /microsoft.graph.user an den Anforderungspfad angefügt. |
type ist group und weder group-id noch group-ids sind festgelegt |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All | /Gruppen | |
type auf person oder any festgelegt, und userIds ist festgelegt. |
User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All | /users/$({userId} | Wenn user-filters festgelegt ist, wird dies als $filter Parameter zur Anforderung mit $count=true hinzugefügt, und der ConsistencyLevel: 'eventual' Header wird für die Anforderung festgelegt. |
type auf person oder any festgelegt ist und user-filters auf oder festgelegt ist und user-type auf user oder festgelegt ist. contact |
User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All | /Benutzer | Wenn user-filters festgelegt ist, wird dies als $filter Parameter zur Anforderung mit $count=true hinzugefügt, und der ConsistencyLevel: 'eventual' Header wird für die Anforderung festgelegt. |
type legen Sie auf person oder any fest, und entweder user-filters nicht oder user-type ist auf weder user noch festgelegt. contact |
People.Read, People.Read.All | /me/people | Wenn people-filters festgelegt ist oder user-type kein any $filter Parameter zur Anforderung hinzugefügt wird. Wenn user-type nicht contact ist, wird der X-PeopleQuery-QuerySources: 'Mailbox,Directory' Header für die Anforderung festgelegt. |
Wenn ein Benutzer einen Suchbegriff angegeben hat
Konfiguration | Berechtigung | API | Weitere Optionen |
---|---|---|---|
group-id ist festgelegt. |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All | /groups/${groupId}/members | Wenn oder oder /microsoft.graph.user /microsoft.graph.group an den Anforderungspfad angefügt wird, wird ein $filter Parameter mit dem Benutzereingabewert zusammengesetzt.type person group |
group-id ist festgelegt und transitive-search ist true. |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All | /groups/${groupId}/transitiveMembers | Wenn oder oder /microsoft.graph.user /microsoft.graph.group an den Anforderungspfad angefügt wird, wird ein $filter Parameter mit dem Benutzereingabewert zusammengesetzt.type person group |
group-id ist nicht auf oder any festgelegt person und type user-type auf und auf festgelegt, und group-ids ist festgelegt.any |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All | /groups/${groupId}/members | Wenn type is person dann /microsoft.graph.user an den Anforderungspfad angefügt wird, wird ein $filter Parameter mit dem Benutzereingabewert zusammengesetzt. |
group-id ist nicht festgelegt und auf oder festgelegt und user-type auf any festgelegt, und group-ids ist auf festgelegt, und transitive-search ist true any person type |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All | /groups/${groupId}/transitiveMembers | Wenn type is person dann /microsoft.graph.user an den Anforderungspfad angefügt wird, wird ein $filter Parameter mit dem Benutzereingabewert zusammengesetzt. |
type auf person oder any user-type und nicht auf any und user-ids ist festgelegt. |
User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All | /users/$({userId} | Wenn user-filters festgelegt ist, wird dies als $filter Parameter zur Anforderung mit $count=true hinzugefügt, und der ConsistencyLevel: 'eventual' Header wird für die Anforderung festgelegt. |
type
person auf oder user-type any und auf any group-ids und ist nicht festgelegt und user-ids ist festgelegt. |
User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All | /users/$({userId} | Wenn user-filters festgelegt ist, wird dies als $filter Parameter zur Anforderung mit $count=true hinzugefügt, und der ConsistencyLevel: 'eventual' Header wird für die Anforderung festgelegt. |
group-id ist nicht festgelegt und type ist group oder type ist any und weniger Ergebnisse als show-max gefunden wurden |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All | /Gruppen | Ein $filter wird unter Verwendung der angegebenen Benutzereingaben, und group-type -Werte erstellt. group-filters |
group-id ist nicht festgelegt und group-ids ist festgelegt und type ist group oder type ist any und weniger Ergebnisse als show-max gefunden wurden |
GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All | /Gruppen | Ein $filter wird unter Verwendung der angegebenen Benutzereingaben, und group-type -Werte erstellt. user-filters |
Unterkomponenten
Die mgt-people-picker
Komponente besteht aus einem oder mehreren Unterkomponenten, die möglicherweise andere Als die zuvor aufgeführten Berechtigungen erfordern. Weitere Informationen finden Sie in der Dokumentation zu den einzelnen Unterkomponenten: mgt-person.
Authentifizierung
Das Steuerelement verwendet den in der Authentifizierungsdokumentation beschriebenen globalen Authentifizierungsanbieter.
Cache
Objektspeicher | Zwischengespeicherte Daten | Hinweise |
---|---|---|
groups |
Liste der Gruppen | Wird verwendet, wenn type auf festgelegt ist PersonType.group |
people |
Personenliste | Wird verwendet, wenn type auf PersonType.person oder festgelegt ist. PersonType.any |
users |
Liste der Benutzer | Wird verwendet, wenn groupId angegeben |
Weitere Informationen zum Konfigurieren des Caches finden Sie unter Zwischenspeichern.
Erweitern für mehr Kontrolle
Für komplexere Szenarien oder eine wirklich benutzerdefinierte Benutzeroberfläche macht diese Komponente mehrere protected render*
Methoden zum Überschreiben in Komponentenerweiterungen verfügbar.
Methode | Beschreibung |
---|---|
renderInput | Rendert das Eingabetextfeld. |
renderSelectedPeople | Rendert die ausgewählten Personentoken. |
renderSelectedPerson | Rendert ein Einzelnes Personentoken. |
renderFlyout | Rendert das Flyout-Chrom. |
renderFlyoutContent | Rendert den entsprechenden Zustand im Ergebnis-Flyout. |
renderLoading | Rendert den Ladezustand. |
renderNoData | Rendert den Zustand, wenn für die Suchabfrage keine Ergebnisse gefunden werden. |
renderSearchResults | Rendert die Liste der Suchergebnisse. |
renderPersonResult | Rendert ein Suchergebnis für eine einzelne Person. |
Lokalisierung
Das -Steuerelement macht die folgenden Variablen verfügbar, die lokalisiert werden können. Ausführliche Informationen zur Lokalisierung finden Sie unter Lokalisieren von Komponenten.
Zeichenfolgenname | Standardwert |
---|---|
inputPlaceholderText | Search for a name |
maxSelectionsPlaceHolder | Max contacts added |
maxSelectionsAriaLabel | Maximum contact selections reached |
noResultsFound | We didn't find any matches. |
loadingMessage | Loading... |
ausgewählt | selected |
removeSelectedUser | Remove |
selectContact | select a contact |
suggestionsTitle | Suggested contacts |