Verwenden des experimentellen Personenauswahl-Widgets in SharePoint-Add-Ins
Sie können das Personenauswahl-Widget auf einer beliebigen Webseite verwenden, selbst dann, wenn die Seite nicht in SharePoint gehostet wird. Verwenden Sie das Personenauswahl-Widget in Ihren Add-Ins, damit Benutzer Personen und Gruppen leichter finden können.
Warnung
Die Office Web Widgets – Experimental werden nur zu Forschungs- und Feedback-Zwecken bereitgestellt. Verwenden Sie diese Widgets nicht in Produktionsszenarien. Das Verhalten der Office Web Widgets kann sich in zukünftigen Versionen signifikant ändern. Lesen und prüfen Sie die Lizenzbedingungen für Office Web Widgets – Experimental.
Sie können das experimentelle Personenauswahl-Widget in Add-Ins verwenden, um Ihren Benutzern zu helfen, Personen und Gruppen in einem Mandanten zu suchen und auszuwählen. Benutzer können beginnen, etwas in das Textfeld einzugeben, und das Widget ruft die Personen ab, deren Name oder E-Mail-Adresse mit dem Text übereinstimmt.
Personenauswahl-Widget beim Auflösen einer Abfrage
Ihr Add-In kann auf die ausgewählten Personen zugreifen, indem es die Eigenschaft selectedItems des Widgets liest. Die selectedItems-Eigenschaft ist ein Array von Objekten, die Personen oder Gruppen darstellen. Die folgende Tabelle zeigt die verfügbaren Eigenschaften des Benutzerobjekts.
| Eigenschaft | Beschreibung |
|---|---|
| department | Die Abteilung des Benutzers oder der Gruppe. |
| displayName | Der Anzeigename des Benutzers oder der Gruppe. |
| Die E-Mail-Adresse des Benutzers oder der Gruppe. | |
| isResolved | Gibt an, ob das Widget den Text im Widget für einen Benutzer oder eine Gruppe im Mandanten erfolgreich aufgelöst hat. |
| jobTitle | Die Position des Benutzers. |
| loginName | Der Anmeldename des Benutzers oder der Gruppe. |
| mobile | Die Mobiltelefonnummer des Benutzers oder der Gruppe. |
| principalId | Die Prinzipal-ID des Benutzers oder der Gruppe. |
| principalType | Gibt an, ob das Element ein Benutzer oder eine Gruppe ist. Weist den Wert 1 auf, wenn es ein Benutzer ist, und den Wert 4, wenn es eine Gruppe ist. |
| sipAddress | Die SIP-Adresse des Benutzers oder der Gruppe. |
| text | Der Texttitel des Benutzer- oder Gruppennamens. |
Das Personenauswahl-Widget weist einen Cache der zuletzt verwendeten Einträge (Most Recently Used, MRU) auf. Der Cache speichert die fünf letzten Einträge, die vom Widget aufgelöst wurden.
Voraussetzungen für die Verwendung der Beispiele in diesem Artikel
Um die Beispiele in diesem Artikel zu verwenden, benötigen Sie Folgendes:
- Visual Studio 2013 oder höher.
- NuGet-Paket-Manager Weitere Informationen finden Sie unter Installieren von NuGet.
- Eine SharePoint-Entwicklungsumgebung (für lokale Szenarios App-Isolierung erforderlich).
- Office Web Widgets – Experimental: NuGet-Paket Weitere Informationen dazu, wie Sie ein NuGet-Paket installieren, finden Sie unter Benutzeroberfläche des NuGet-Paket-Managers. Sie können auch die NuGet-Katalogseite durchsuchen.
Verwenden des Personenauswahl-Widgets in einem vom Anbieter gehosteten SharePoint-Add-In
In diesem Beispiel wird eine einfache Seite, die ein Personenauswahl-Widget mithilfe von Markup deklariert, außerhalb von SharePoint gehostet. Der Einfachheit halber werden in diesem Beispiel keine Optionen deklariert. Im Abschnitt Nächste Schritte finden Sie jedoch ein Beispiel mit Optionen.
Wenn Sie das Personenauswahl-Widget verwenden möchten, müssen Sie Folgendes tun:
Erstellen Sie SharePoint-Add-In- und Webprojekte.
Erstellen Sie im Add-In-Web ein Modul. Dieser Schritt stellt sicher, dass ein Add-In-Web erstellt wird, wenn Benutzer das Add-In bereitstellen.
Hinweis
Die domänenübergreifende Bibliothek erfordert das Vorhandensein eines Add-In-Webs. Das Personenauswahl-Widget kommuniziert mit SharePoint mithilfe der domänenübergreifenden Bibliothek.
Erstellen Sie eine Add-In-Seite, die mithilfe von Markup eine Personenauswahl-Widget-Instanz deklariert.
So erstellen Sie ein SharePoint-Add-In und Webprojekte
Öffnen Sie Visual Studio als Administrator. (Klicken Sie dazu im Menü Start auf das Symbol für Visual Studio, und wählen Sie Als Administrator ausführen aus.)
Erstellen Sie mithilfe der SharePoint-Add-In 2013-Vorlage ein neues Projekt. Die SharePoint-Add-In 2013 -Vorlage befindet sich unter Vorlagen>Visual C#, Office/SharePoint>Add-Ins.
Geben Sie die URL der SharePoint-Website an, die Sie für das Debugging verwenden möchten.
Wählen Sie als Hostingoption für Ihr Add-In Von Anbieter gehostet aus.
Hinweis
Sie können das Personenauswahl-Widget auch mit anderen Hostingoptionen oder sogar mit Add-Ins für Office auf Ihrer eigenen Website verwenden.
Wählen Sie als Typ des Webanwendungsprojekts ASP.NET Webformular-Anwendung aus.
Wählen Sie als Authentifizierungsoption Windows Azure-Zugriffssteuerungsdienst aus.
So erstellen Sie ein Modul im Web-Add-In
Klicken Sie im Projektmappen-Explorer auf das SharePoint-Add-In-Projekt. Wählen Sie Hinzufügen>Neues Element.
Wählen Sie Visual C#-Elemente>Office/SharePoint>Modul aus. Geben Sie einen Namen für das Modul ein.
Hinweis
Wenn Sie ein von SharePoint gehostetes Add-In erstellen, müssen Sie ein eigenes Modul erstellen.
So fügen Sie eine neue Seite hinzu, die das Personenauswahl-Widget verwendet
Wählen Sie im Projektmappen-Explorer im Webprojekt den Ordner Seiten aus.
Kopieren Sie den folgenden Code, und fügen Sie ihn in eine ASPX -Datei im Projekt ein. Der Code führt die folgenden Aufgaben durch:
Fügt Verweise auf die erforderlichen Office-Bibliotheken und -Ressourcen hinzu.
Initialisiert die Laufzeit der Steuerelemente.
Führt die Methode renderAll der Office-Steuerelementelaufzeit aus.
Deklariert einen Platzhalter für das Personenauswahl-Widget.
<!DOCTYPE html> <html> <head> <!-- IE9 or superior --> <meta http-equiv="X-UA-Compatible" content="IE=9" > <title>People Picker HTML Markup</title> <!-- Widgets Specific CSS File --> <link rel="stylesheet" type="text/css" href="../Scripts/Office.Controls.css" /> <!-- Ajax, jQuery, and utils --> <script src=" https://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js.js"> </script> <script src=" https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.9.1.min.js"> </script> <script type="text/javascript"> // Function to retrieve a query string value. // For production purposes you may want to use // a library to handle the query string. function getQueryStringParameter(paramToRetrieve) { var params = document.URL.split("?")[1].split("&"); var strParams = ""; for (var i = 0; i < params.length; i = i + 1) { var singleParam = params[i].split("="); if (singleParam[0] == paramToRetrieve) return singleParam[1]; } } </script> <!-- Cross-Domain Library and Office controls runtime --> <script type="text/javascript"> //Register namespace and variables used through the sample Type.registerNamespace("Office.Samples.PeoplePickerBasic"); //Retrieve context tokens from the querystring Office.Samples.PeoplePickerBasic.appWebUrl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl")); Office.Samples.PeoplePickerBasic.hostWebUrl = decodeURIComponent(getQueryStringParameter("SPHostUrl")); //Pattern to dynamically load JSOM and and the cross-domain library var scriptbase = Office.Samples.PeoplePickerBasic.hostWebUrl + "/_layouts/15/"; //Get the cross-domain library $.getScript(scriptbase + "SP.RequestExecutor.js", //Get the Office controls runtime and // continue to the createControl function function () { $.getScript("../Scripts/Office.Controls.js", createControl) } ); </script> <!--People Picker --> <script src="../Scripts/Office.Controls.PeoplePicker.js" type="text/javascript"> </script> </head> <body> Basic People Picker sample (HTML markup declaration): <div id="PeoplePickerDiv" data-office-control="Office.Controls.PeoplePicker"> </div> <script type="text/javascript"> function createControl() { //Initialize Controls Runtime Office.Controls.Runtime.initialize({ sharePointHostUrl: Office.Samples.PeoplePickerBasic.hostWebUrl, appWebUrl: Office.Samples.PeoplePickerBasic.appWebUrl }); //Render the widget, this must be executed after the //placeholder DOM is loaded Office.Controls.Runtime.renderAll(); } </script> </body> </html>
Hinweis
Im vorherigen Codebeispiel werden das Hostweb und Add-In-Web-URLs explizit angegeben, um die Office-Steuerelementelaufzeit zu initialisieren. Wenn das Add-In-Web und die Host-Web-URLs jedoch in den Abfragezeichenfolgenparametern SPAppWebUrl und SPHostUrl angegeben sind, können Sie ein leeres Objekt übergeben. Der Code versucht dann, die Parameter automatisch abzurufen. Die Parameter SPAppWebUrl und SPHostUrl sind in der Abfragezeichenfolge enthalten, wenn Sie das {StandardTokens}-Token verwenden.
Das folgende Beispiel zeigt, wie Sie ein leeres Objekt übergeben, um die Methode zu initialisieren:
// Initialize with an empty object and the code
// will attempt to get the tokens from the
// query string directly.
Office.Controls.Runtime.initialize({});
So erstellen Sie die Lösung und führen sie aus
Wählen Sie die F5-Taste.
Hinweis
Wenn Sie F5 wählen, erstellt Visual Studio die Lösung, stellt das Add-In bereit und öffnet die Berechtigungsseite für das Add-In.
Wählen Sie die Schaltfläche Vertrauen.
Wählen Sie auf der Seite Websiteinhalte das Add-In-Symbol aus.
Um dieses Beispiel aus der Codegalerie herunterladen, sehen Sie sich das Codebeispiel Verwenden des experimentellen Personenauswahl-Widgets in einem Add-In an.
Nächste Schritte
In diesem Artikel wird die Verwendung des Personenauswahl-Widgets in Ihrem Add-In mithilfe von HTML beschrieben. Sie können auch die folgenden Szenarios und Details zum Widget erkunden.
Verwenden von JavaScript, um das Personenauswahl-Widget zu deklarieren
In Abhängigkeit von Ihren Einstellungen möchten Sie vielleicht JavaScript anstelle von HTML zum Deklarieren des Widgets verwenden. Wenn dies der Fall ist, können Sie das folgende Markup als Platzhalter für das Widget verwenden.
<div id="PeoplePickerDiv"></div>
Verwenden Sie den folgenden JavaScript-Code, um die Personenauswahl zu instanziieren.
new Office.Controls.PeoplePicker(
document.getElementById("PeoplePickerDiv"), {});
Ein Codebeispiel, das zeigt, wie die Aufgaben durchgeführt werden, finden Sie auf der Seite JSSimple.html im Codebeispiel Verwenden des experimentellen Personenauswahl-Widgets in einem Add-In.
Angeben von Optionen für das Widget
ie können mithilfe des Attributs data-office-options in der Widget-Deklaration Optionen für das Widget festlegen. Der folgende HTML-Code zeigt, wie Sie Optionen für das Personenauswahl-Widget festlegen.
<div id="PeoplePickerDiv"
data-office-control="Office.Controls.PeoplePicker"
data-office-options='{
"allowMultipleSelections" : true,
"onChange" : handleChange,
"placeholder" : "Check the count message, it changes when you add names..."
}'>
</div>
Der folgende Code zeigt, wie Sie Optionen festlegen, wenn Sie das Personenauswahl-Widget mit JavaScript deklarieren.
new Office.Controls.PeoplePicker(
document.getElementById("PeoplePickerDiv"), {
allowMultipleSelections: true,
placeholder: "Check the count message, it changes when you add names...",
onChange: function (ctrl) {
document.getElementById("count").textContent =
ctrl.selectedItems.length.toString();
}
});
Sie können auch Ereignishandler für die Ereignisse onChange, onAdded und onRemoved angeben. Beachten Sie im vorherigen Code, dass der Ereignishandler für das onChange-Ereignis einen einzigen ctrl-Parameter empfängt, bei dem es sich um einen Verweis auf das Widget handelt.
Ein Beispiel dafür, wie Sie Optionen festlegen, finden Sie auf den Seiten MarkupOptions.html und JSOptions.html im Codebeispiel Verwenden des experimentellen Personenauswahl-Widgets in einem Add-In.
Abrufen von Personen oder Gruppen, die im Widget ausgewählt sind
Um die Personen im Widget abzurufen, müssen Sie die folgenden Aufgaben durchführen:
Abrufen eines Verweises auf das Widget.
Aufrufen der Eigenschaft selectedItems des Widgets.
ie können mithilfe der folgenden Syntax einen Verweis auf das Widget abrufen.
var pplPicker = document.getElementById("PeoplePickerDiv")._officeControl;
Sie können auch einen Verweis speichern, wenn Sie das Widget instanziieren.
var pplPicker = new Office.Controls.PeoplePicker(
document.getElementById("PeoplePickerDiv"), {});
Die selectedItems-Eigenschaft ist ein Array von Objekten, die Personen oder Gruppen darstellen. Personen oder Gruppen in der selectedItems-Array können entweder aufgelöst oder nicht aufgelöst sein; dies können Sie in der isResolved-Eigenschaft überprüfen. Im folgenden Beispiel wird gezeigt, wie Sie das Element i im Array aufrufen und den Namen der Person oder Gruppe verwenden.
var principal = pplPicker.selectedItems[i];
$("#msg").text(principal.text + " is selected in the control.");
Ein Beispiel dafür, wie Sie die ausgewählten Personen oder Gruppen im Widget abrufen, finden Sie auf der Seite demo.html des Codebeispiels Office Web Widgets - Experimentelle Demo.
Anpassen des Widget-Formats
Als Entwickler möchten Sie das Aussehen und Verhalten des Widgets anpassen. In der folgenden Abbildung ist die HTML-Hierarchie im Widget nach dem Rendern dargestellt. Das Widget definiert viele Klassen mit dem Präfix office-peoplepicker, die Sie im Stylesheet Office.Controls.css finden und anpassen können.
HTML-Hierarchie im Personenauswahl-Widget
Sie können das experimentelle Personenauswahl-Widget verwenden, um Personen und Gruppen in Ihrem Mandanten auszuwählen. Ihr Add-In kann dann die von Ihren Benutzern ausgewählten Prinzipale verwenden. Bitte geben Sie uns auf der Office Developer Platform UserVoice-Website weiterhin Feedback und Ideen.