Verwenden des clientseitigen Personenauswahl-Steuerelement in von SharePoint gehosteten SharePoint-Add-Ins

Was ist das clientseitige Personenauswahl-Steuerelement in SharePoint?

Mit dem clientseitigen Steuerelement „Personenauswahl“ können Benutzer schnell nach gültigen Benutzerkonten für Personen, Gruppen und Ansprüche in ihrer Organisation suchen, und diese auswählen. Die Auswahl ist ein HTML- und JavaScript-Steuerelement, das für alle Browser unterstützt wird.

Die Auswahl lässt sich problemlos zu Ihrem Add-In hinzufügen:

1. Fügen Sie im Markup für das Steuerelement und die Verweise für dieses Steuerelement sowie die zugehörigen Abhängigkeiten ein Containerelement hinzu.

2. Rufen Sie im Skript die globale SPClientPeoplePicker_InitStandaloneControlWrapper-Funktion auf, um die Auswahl zu rendern und zu initialisieren.

Die Auswahl wird mit dem SPClientPeoplePicker-Objekt dargestellt, welches Methoden bereitstellt, die andere clientseitige Steuerelemente zum Abrufen von Informationen von der Auswahl oder zum Ausführen anderer Vorgänge verwenden können. Sie können die SPClientPeoplePicker-Eigenschaften verwenden, um Steuerelement-spezifische Einstellungen für die Auswahl zu konfigurieren, z. B. Zulassen mehrerer Benutzer oder Angeben von Cachingoptionen.

Die Auswahl verwendet auch Konfigurationseinstellungen von Webanwendungen wie Active Directory-Domänendienste-Parameter oder gezielte Gesamtstrukturen. Konfigurationseinstellungen von Webanwendungen werden automatisch abgerufen (von der SPWebApplication.PeoplePickerSettings-Eigenschaft).

Die Auswahl besteht aus den folgenden Komponenten:

• Ein Textfeld zum Eingeben von Namen für Benutzer, Gruppen und Ansprüche.
• Ein Span-Steuerelement, das die Namen der aufgelösten Benutzer, Gruppen und Ansprüche zeigt.
• Ein ausgeblendetes div-Element, das automatisch ein Dropdownfeld mit übereinstimmenden Abfrageergebnissen ausfüllt.
• Ein AutoAusfüllen-Steuerelement.

Voraussetzungen für das Einrichten der Entwicklungsumgebung für die Verwendung des clientseitiges Personenauswahl-Steuerelements in einem SharePoint-Add-In

In diesem Artikel wird davon ausgegangen, dass Sie das SharePoint-Add-In mithilfe von Napa auf einer Office 365-Entwicklerwebsite erstellen. Wenn Sie diese Entwicklungsumgebung verwenden, erfüllen Sie bereits die Voraussetzungen.

Wenn Sie nicht mit Napa auf einer Entwicklerwebsite arbeiten, benötigen Sie Folgendes:

• SharePoint mit mindestens einem Zielbenutzer
• Visual Studio 2012 oder Visual Studio 2013
• Office Developer Tools für Visual Studio 2013

In den folgenden Abschnitten werden die allgemeinen Schritte zum Hinzufügen der Auswahl zu Ihrem Add-In und zum Abrufen von Benutzerinformationen von einem anderen clientseitigen Steuerelement beschrieben. Den entsprechenden Code finden Sie unter Codebeispiel: Verwenden der clientseitigen Personenauswahl.

Sie können das clientseitige Personenauswahl-Steuerelement in von SharePoint gehosteten SharePoint-Add-Ins verwenden, jedoch nicht in von einem Anbieter gehosteten Add-Ins.

Verwenden des clientseitigen Personenauswahl-Steuerelements in von SharePoint gehosteten Add-Ins

In Ihrem Seitenmarkup

1. Fügen Sie Verweise auf die Skriptabhängigkeiten des clientseitigen Personenauswahl-Steuerelements hinzu.

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.

In Ihrem Skript

1. Erstellen Sie ein JSON-Wörterbuch, das als Schema zum Speichern von auswahlspezifischen Eigenschaften wie z. B. AllowMultipleValues und MaximumEntitySuggestions verwendet wird.

2. Rufen Sie die globale Funktion SPClientPeoplePicker_InitStandaloneControlWrapper auf.

3. Rufen Sie das Auswahlobjekt von der Seite ab.

4. Fragen Sie die Auswahl ab. Das Add-In in diesem Beispiel ruft die GetAllUserInfo-Methode auf, um alle Benutzerinformationen für die aufgelösten Benutzer abzurufen, und die GetAllUserKeys-Methode, um nur die Schlüssel für die aufgelösten Benutzer abzurufen.

5. Rufen Sie die Benutzer-ID mithilfe des JavaScript-Objektmodells ab. 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.

Rendering, Initialisierung und andere Funktionen der Auswahl werden vom Server bearbeitet, darunter das Durchsuchen und Auflösen von Benutzereingaben für die SharePoint-Authentifizierungsanbieter.

Codebeispiel: Verwenden des clientseitigen Personenauswahl-Steuerelements in von SharePoint gehosteten Add-Ins

Die folgenden HTML- und JavaScript-Codebeispiele fügen ein clientseitiges Personenauswahl-Steuerelement zu einem von SharePoint gehosteten Add-In hinzu.

Das erste Beispiel zeigt das Markup der Seite für die PlaceHolderMain asp:Content-Tags auf der Seite „Default.aspx“. Dieser Code verweist auf die Skriptabhängigkeiten der Auswahl, gibt eine eindeutige ID für das DOM-Element an, das die Auswahl rendert, und definiert die Add-In Benutzeroberfläche.

<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>

Das folgende Beispiel zeigt das Skript aus der Datei „App.js“. 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.

// 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 auch

• Erstellen von UX-Komponenten in SharePoint
• Überblick über die Personenauswahl und Anspruchsanbieter (SharePoint)
• Konfigurieren der Personenauswahl in SharePoint