Verwenden des clientseitigen Personenauswahl-Steuerelements in von SharePoint gehosteten Share Point-Add-InsUse the client-side People Picker control in SharePoint-hosted SharePoint Add-ins

Wichtig

In diesem Thema wird davon ausgegangen, dass Sie wissen, wie ein von SharePoint gehostetes SharePoint-Add-In erstellt wird.Important This topic assumes that you know how to create a SharePoint-hosted SharePoint Add-in. To learn how to create one, start at Get started creating provider-hosted SharePoint Add-ins. Um zu erfahren, wie man ein solches erstellt, lesen Sie Erste Schritte beim Erstellen von SharePoint-gehosteten SharePoint-Add-Ins.To learn how to create one, see Get started creating SharePoint-hosted SharePoint Add-ins.

Was ist das clientseitige Personenauswahl-Steuerelement in SharePoint?What is the client-side People Picker control in SharePoint?

Mit dem clientseitigen Personenauswahl-Steuerelement können Benutzer schnell nach gültigen Benutzerkonten von Personen, Gruppen und Ansprüchen in ihrer Organisation suchen und diese auswählen.Learn how to use the client-side People Picker control in SharePoint Add-ins. The client-side People Picker control lets users quickly search for and select valid user accounts for people, groups, and claims in their organization. The picker is an HTML and JavaScript control that provides cross-browser support. Bei der Auswahl handelt es sich um ein HTML- und JavaScript-Steuerelement mit browserübergreifendem Support.The picker is an HTML and JavaScript control that provides cross-browser support.

Das Hinzufügen der Personenauswahl zu Ihrem Add-In ist einfach:Adding the picker to your add-in is easy:

  1. Fügen Sie in Ihrem Markup ein Containerelement für das Steuerelement sowie Referenzen für das Steuerelement und seine Abhängigkeiten hinzu.In your markup, add a container element for the control and references for the control and its dependencies.

  2. Rufen Sie in Ihrem Skript die globale Funktion SPClientPeoplePicker_InitStandaloneControlWrapper auf, um die Auswahl zu rendern und zu initialisieren.In your script, call the SPClientPeoplePicker_InitStandaloneControlWrapper global function to render and initialize the picker.

Die Auswahl wird durch das Objekt SPClientPeoplePicker repräsentiert, das Methoden bereitstellt, mit denen andere clientseitige Steuerelemente Informationen von der Auswahl erhalten oder andere Operationen ausführen können.The picker is represented by the SPClientPeoplePicker object, which provides methods that other client-side controls can use to get information from the picker or to perform other operations. Sie können die Eigenschaften SPClientPeoplePicker verwenden, um die Auswahl mit bestimmten Einstellungen für das Steuerelement zu konfigurieren, wie beispielsweise das Zulassen mehrerer Benutzer oder die Angabe von Cache-Optionen.You can use SPClientPeoplePicker properties to configure the picker with control-specific settings, such as allowing multiple users or specifying caching options.

Die Auswahl verwendet auch Konfigurationseinstellungen für Webanwendungen wie Active Directory-Domänendienste-Parameter oder ausgewählte Gesamtstrukturen.The picker also uses web application configuration settings such as Active Directory Domain Services parameters or targeted forests. Die Konfigurationseinstellungen der Webanwendung werden automatisch übernommen (aus der Eigenschaft SPWebApplication.PeoplePickerSettings).Web application configuration settings are picked up automatically (from the SPWebApplication.PeoplePickerSettings property).

Die Auswahl besteht aus den folgenden Komponenten:The picker has the following components:

  • Ein Textfeld zum Eingeben von Namen für Benutzer, Gruppen und Ansprüche.An input text box to enter names for users, groups, and claims.
  • Ein Span-Steuerelement, das die Namen aufgelöster Benutzer, Gruppen und Ansprüchen anzeigt.A span control that shows the names of resolved users, groups, and claims.
  • Ein ausgeblendetes div-Element, das automatisch ein Dropdownfeld mit übereinstimmenden Abfrageergebnissen ausfüllt.A hidden div element that autofills a drop-down box with matching query results.
  • Ein AutoAusfüllen-Steuerelement.An autofill control.

Hinweis

Die Auswahl und ihre Funktionalität sind in den Skriptdateien clientforms.js, clientpeoplepicker.js und autofill.js definiert, die sich im Ordner %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS auf dem Server befinden.Note The picker and its functionality are defined in the clientforms.js, clientpeoplepicker.js, and autofill.js script files, which are located in the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS folder on the server.

Voraussetzungen für das Einrichten der Entwicklungsumgebung für die Verwendung des clientseitiges Personenauswahl-Steuerelements in einem SharePoint-Add-InPrerequisites for setting up your development environment to use the client-side People Picker control in a SharePoint Add-in 2013

In diesem Artikel wird davon ausgegangen, dass Sie die SharePoint-Add-In mithilfe einer Napa- oder Office 365-Entwicklerwebsite erstellen.This article assumes that you create the SharePoint Add-in by using Napa on an Office 365 Developer Site. If you're using this development environment, you've already met the prerequisites. Wenn Sie diese Entwicklungsumgebung verwenden, sind die Voraussetzungen bereits erfüllt.If you're using this development environment, you've already met the prerequisites.

Hinweis

Wie Sie sich für eine Entwicklerseite anmelden und Napa verwenden können, erfahren Sie unter Einrichten einer Entwicklungsumgebung für SharePoint-Add-ins in Office 365.To find out how to sign up for a developer site and start using Napa, see Set up a development environment for SharePoint Add-ins on Office 365.

Wenn Sie nicht mit Napa auf einer Entwicklerwebseite arbeiten, benötigen Sie Folgendes:If you're not using Napa on a Developer Site, you'll need the following:

  • SharePoint mit mindestens einem ZielbenutzerSharePoint with at least one target user
  • Visual Studio 2012 oder Visual Studio 2013Visual Studio 2012 or Visual Studio 2013
  • Office Developer Tools für Visual Studio 2013Office Developer Tools for Visual Studio 2013

Hinweis

Anweisungen zum Einrichten einer Entwicklungsumgebung, die Ihren Anforderungen entspricht, finden Sie unter SharePoint-Add-Ins.Note For guidance about how to set up a development environment that fits your needs, see Start building Office and SharePoint Add-ins.

Die folgenden Abschnitte beschreiben die allgemeinen Schritte, um die Auswahl zu Ihrem Add-In hinzuzufügen und dann seine Benutzerinformationen von einem anderen Client-seitigen Steuerelement zu erhalten.The following steps describe the high-level steps for adding the picker to your add-in and then getting its user information from another client-side control. See Code example: Using the client-side People Picker for the corresponding code. Der entsprechende Code finden Sie unter Codebeispiel: Verwendung der clientseitigen Personenauswahl.For the corresponding code, see Code example: Using the client-side People Picker.

Sie können das clientseitige Personenauswahl-Steuerelement in SharePoint-gehosteten SharePoint-Add-Ins verwenden, nicht aber in providergehosteten Add-Ins.You can use the client-side People Picker control in SharePoint-hosted SharePoint Add-ins, but not in provider-hosted add-ins. For a sample that shows how to implement a people-picker control in a provider-hosted add-in, download the Office Add-in Model Samples.

Verwenden des clientseitigen Personenauswahl-Steuerelements in von SharePoint gehosteten Add-InsUse the client-side People Picker control in a SharePoint-hosted add-in

In Ihrem SeitenmarkupIn your page markup

  1. Fügen Sie Verweise auf die Skriptabhängigkeiten der clientseitigen Personenauswahl hinzu.Add references to the client-side People Picker control's script dependencies.

  2. Fügen Sie die HTML-Tags für die Benutzeroberfläche der Seite hinzu. Die App in diesem Beispiel definiert zwei div-Elemente: eines, in dem die Auswahl gerendert wird und eines für die Benutzeroberfläche: eine Schaltfläche zum Aufrufen des Skripts für die Abfrage der Auswahl und der Elemente, die Benutzerinformationen anzeigen.Add the HTML tags for the page UI. The add-in in this example defines two div elements: one for the picker to render in and one for the UI: a button that invokes script to query the picker and the elements that display user information.

In Ihrem SkriptIn your script

  1. Erstellen Sie ein JSON-Wörterbuch, das als Schema zum Speichern von auswahlspezifischen Eigenschaften wie z. B. AllowMultipleValues und MaximumEntitySuggestions verwendet wird.Create a JSON dictionary to use as a schema that stores picker-specific properties, such as AllowMultipleValues and MaximumEntitySuggestions.

  2. Rufen Sie die globale Funktion SPClientPeoplePicker_InitStandaloneControlWrapper auf.Call the SPClientPeoplePicker_InitStandaloneControlWrapper global function.

  3. Rufen Sie das Auswahlobjekt von der Seite ab.Get the picker object from the page.

  4. Abfrage der Auswahl.Query the picker. Das Add-In in diesem Beispiel ruft die Methode GetAllUserInfo auf, um alle Benutzerinformationen für die aufgelösten Benutzer zu erhalten, und die Methode GetAllUserKeys, um nur die Schlüssel für die aufgelösten Benutzer zu erhalten.Query the picker. The add-in in this example calls the GetAllUserInfo method to get all user information for the resolved users and the GetAllUserKeys method to just get the keys for the resolved users.

  5. Abrufen der Benutzer-ID mit dem JavaScript-Objektmodell. Die Benutzer-ID ist in den Informationen, die von der Auswahl zurückgegeben werden, nicht enthalten, deshalb ruft die App die SP.Web.ensureUser-Methode auf und die ID aus dem zurückgegebenen SP.User-Objekt ab.Get the user ID by using the JavaScript object model. The user ID isn't included in the information that's returned by the picker, so the add-in calls the SP.Web.ensureUser method and gets the ID from the returned SP.User object.

Rendering, Initialisierung und andere Funktionen der Auswahl werden vom Server bearbeitet, darunter das Durchsuchen und Auflösen von Benutzereingaben für die SharePoint-Authentifizierungsanbieter.Rendering, initializing, and other functionality for the picker are handled by the server, including searching and resolving user input against the SharePoint authentication providers.

Codebeispiel: Verwenden des clientseitigen Personenauswahl-Steuerelements in von SharePoint gehosteten Add-InsCode example: Using the client-side People Picker in a SharePoint-hosted add-in

Die folgenden HTML- und JavaScript-Codebeispiele fügen ein clientseitiges Personenauswahl-Steuerelement zu einem von SharePoint gehosteten Add-In hinzu.The following HTML and JavaScript code examples add a client-side People Picker control to a SharePoint-hosted add-in.

Das erste Beispiel zeigt das Seitenmarkup für die PlaceHolderMain asp:Content -Tags auf der Seite Default.aspx.The first example shows the page markup for the PlaceHolderMainasp:Content tags in the Default.aspx page. This code references the picker's script dependencies, gives a unique ID to the DOM element where the picker will render, and defines the add-in's UI. Dieser Code verweist auf die Skriptabhängigkeiten der Auswahl, gibt dem DOM-Element, in dem die Auswahl gerendert wird, eine eindeutige ID und definiert die Benutzeroberfläche des Add-Ins.The first example shows the page markup for the PlaceHolderMain asp:Content tags in the Default.aspx page. This code references the picker's script dependencies, gives a unique ID to the DOM element where the picker will render, and defines the add-in's UI.

<asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">
    <SharePoint:ScriptLink name="clienttemplates.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="clientforms.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="clientpeoplepicker.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="autofill.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="sp.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="sp.runtime.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="sp.core.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <div id="peoplePickerDiv"></div>
    <div>
        <br/>
        <input type="button" value="Get User Info" onclick="getUserInfo()"></input>
        <br/>
        <h1>User info:</h1>
        <p id="resolvedUsers"></p>
        <h1>User keys:</h1>
        <p id="userKeys"></p> 
        <h1>User ID:</h1>
        <p id="userId"></p>
    </div>
</asp:Content>


Hinweis

Abhängig von Ihrer Umgebung müssen Sie möglicherweise nicht explizit auf all diese Abhängigkeiten verweisen.Depending on your environment, you might not have to explicitly reference all of these dependencies.


Das folgende Beispiel zeigt das Skript aus der Datei app.js.The following example shows the script from the App.js file. Dieses Skript initialisiert und rendert die Auswahl und fragt anschließend Benutzerinformationen davon ab. Außerdem ruft es mithilfe des JavaScript-Objektmodells die Benutzer-ID ab.The following example shows the script from the App.js file. This script initializes and renders the picker, queries it for user information, and then gets the user ID by using the JavaScript object model.


// Run your custom code when the DOM is ready.
$(document).ready(function () {

    // Specify the unique ID of the DOM element where the
    // picker will render.
    initializePeoplePicker('peoplePickerDiv');
});

// Render and initialize the client-side People Picker.
function initializePeoplePicker(peoplePickerElementId) {

    // Create a schema to store picker properties, and set the properties.
    var schema = {};
    schema['PrincipalAccountType'] = 'User,DL,SecGroup,SPGroup';
    schema['SearchPrincipalSource'] = 15;
    schema['ResolvePrincipalSource'] = 15;
    schema['AllowMultipleValues'] = true;
    schema['MaximumEntitySuggestions'] = 50;
    schema['Width'] = '280px';

    // Render and initialize the picker. 
    // Pass the ID of the DOM element that contains the picker, an array of initial
    // PickerEntity objects to set the picker value, and a schema that defines
    // picker properties.
    this.SPClientPeoplePicker_InitStandaloneControlWrapper(peoplePickerElementId, null, schema);
}

// Query the picker for user information.
function getUserInfo() {

    // Get the people picker object from the page.
    var peoplePicker = this.SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan;

    // Get information about all users.
    var users = peoplePicker.GetAllUserInfo();
    var userInfo = '';
    for (var i = 0; i < users.length; i++) {
        var user = users[i];
        for (var userProperty in user) { 
            userInfo += userProperty + ':  ' + user[userProperty] + '<br>';
        }
    }
    $('#resolvedUsers').html(userInfo);

    // Get user keys.
    var keys = peoplePicker.GetAllUserKeys();
    $('#userKeys').html(keys);

    // Get the first user's ID by using the login name.
    getUserId(users[0].Key);
}

// Get the user ID.
function getUserId(loginName) {
    var context = new SP.ClientContext.get_current();
    this.user = context.get_web().ensureUser(loginName);
    context.load(this.user);
    context.executeQueryAsync(
         Function.createDelegate(null, ensureUserSuccess), 
         Function.createDelegate(null, onFail)
    );
}

function ensureUserSuccess() {
    $('#userId').html(this.user.get_id());
}

function onFail(sender, args) {
    alert('Query failed. Error: ' + args.get_message());
}


Siehe auchSee also