Ausführen grundlegender Vorgänge unter Verwendung von JavaScript-Bibliothekscode in SharePoint

Sie können das SharePoint-Clientobjektmodell zum Abrufen, Aktualisieren und Verwalten von Daten in SharePoint verwenden. SharePoint stellt das Objektmodell in verschiedenen Formen zur Verfügung:

• Weitervertreibbare Assemblys für .NET Framework
• JavaScript-Bibliothek
• REST-/OData-Endpunkte
• Windows Phone-Assemblys
• Weitervertreibbare Silverlight-Assemblys

Weitere Information zu den Gruppen von APIs, die für SharePoint verfügbar sind, finden Sie unter Auswählen des richtigen API-Satzes in SharePoint.

In diesem Artikel wird gezeigt, wie Sie grundlegende Vorgänge mit dem JavaScript-Objektmodell ausführen. Einen Verweis auf das Objektmodell können Sie mit HTML-<script>Tags hinzufügen. Informationen zum Verwenden der anderen Client-APIs finden Sie in folgenden Themen:

• Ausführen grundlegender Vorgänge unter Verwendung von SharePoint-Clientbibliothekscode
• Ausführen grundlegender Vorgänge unter Verwendung von SharePoint REST-Endpunkten
• Erstellen von Windows Phone-Apps, die auf SharePoint zugreifen
• Verwenden des Silverlight-Objektmodells im SharePoint 2010 SDK

Ausführen grundlegender Aufgaben in SharePoint unter Verwendung des JavaScript-Clientobjektmodells

In den folgenden Abschnitten werden Aufgaben beschrieben, die Sie programmgesteuert ausführen können. Diese Abschnitte enthalten JavaScript-Codebeispiele zur Veranschaulichung der Vorgänge.

Wenn Sie ein in der Cloud gehostetes Add-In erstellen, können Sie mithilfe von HTML-<script>Tags einen Verweis auf das Objektmodell hinzufügen. Wir empfehlen, auf das Hostweb zu verweisen, da das Add-In-Web möglicherweise nicht in allen Szenarien von in der Cloud gehosteten Add-Ins verfügbar ist. Sie können die Hostweb-URL aus dem Abfragezeichenfolgenparameter SPHostUrl abrufen, wenn Sie das Token {StandardTokens} verwenden. Sie können auch Ihren benutzerdefinierten Abfragezeichenfolgenparameter verwenden, wenn Sie das Token {HostUrl} verwenden. Nachdem Sie die Hostweb-URL ermittelt haben, müssen Sie den Verweis auf das Objektmodell mit JavaScript-Code dynamisch erstellen.

Im folgenden Codebeispiel werden die folgenden Aufgaben ausgeführt, um einen Verweis auf das JavaScript-Objektmodell hinzuzufügen:

• Es wird auf die AJAX-Bibliothek aus dem Microsoft Netzwerk für die Inhaltsübermittlung (CDN) verwiesen.
• Es wird auf die jQuery-Bibliothek aus dem Microsoft CDN verwiesen.
• Die URL des Hostwebs wird aus der Abfragezeichenfolge extrahiert.
• Die Dateien "SP.Runtime.js" und "SP.js" werden mithilfe der getScript-Funktion in jQuery geladen. Nachdem die Dateien geladen wurden, hat das Programm Zugriff auf das JavaScript-Objektmodell für SharePoint.
• Der Programmablauf wird in der execOperation-Funktion fortgesetzt.

<script 
    src="//ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js" 
    type="text/javascript">
</script>
<script
    type="text/javascript"
    src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
</script>
<script type="text/javascript">
    var hostweburl;

    // Load the required SharePoint libraries.
    $(document).ready(function () {

        // Get the URI decoded URLs.
        hostweburl =
            decodeURIComponent(
                getQueryStringParameter("SPHostUrl")
        );

        // The js files are in a URL in the form:
        // web_url/_layouts/15/resource_file
        var scriptbase = hostweburl + "/_layouts/15/";

        // Load the js files and continue to
        // the execOperation function.
        $.getScript(scriptbase + "SP.Runtime.js",
            function () {
                $.getScript(scriptbase + "SP.js", execOperation);
            }
        );
    });

    // Function to execute basic operations.
    function execOperation() {

        // Continue your program flow here.

    }

    // 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("&amp;");
        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>

Wenn Sie ein von SharePoint gehostetes Add-In erstellen, können Sie mithilfe von HTML-Tags <script> einen Verweis auf das Objektmodell hinzufügen. Das Add-In-Web in einem von SharePoint gehosteten Add-In ermöglicht es Ihnen, relative Pfade zu verwenden, um auf die dateien zu verweisen, die für die Verwendung des JavaScript-Objektmodells erforderlich sind.

Im folgenden Markup werden diese Aufgaben ausgeführt, um einen Verweis auf das JavaScript-Objektmodell hinzuzufügen:

• Es wird auf die AJAX-Bibliothek aus dem Microsoft CDN verwiesen.
• Über eine auf das Add-In-Web bezogene URL wird auf die Datei SP.Runtime.js verwiesen.
• Über eine auf das Add-In-Web bezogene URL wird auf die Datei SP.js verwiesen.

<script 
    src="//ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js" 
    type="text/javascript">
</script>
<script 
    type="text/javascript" 
    src="/_layouts/15/sp.runtime.js">
</script>
<script 
    type="text/javascript" 
    src="/_layouts/15/sp.js">
</script>
<script type="text/javascript">

    // Continue your program flow here.

</script>

SharePoint-Websiteaufgaben

Wenn Sie Websites mithilfe von JavaScript bearbeiten möchten, verwenden Sie zuerst den ClientContext(serverRelativeUrl)-Konstruktor und übergeben eine URL oder einen URI, um einen bestimmten Anforderungskontext zurückzugeben.

Abrufen der Eigenschaften einer Website

Verwenden Sie die web-Eigenschaft der ClientContext-Klasse, um die Eigenschaften des Websiteobjekts anzugeben, das sich an der angegebenen Kontext-URL befindet. Nachdem das Websiteobjekt über die load(clientObject)-Methode geladen und anschließend executeQueryAsync(succeededCallback, failedCallback) aufgerufen wurde, können Sie Zugriff auf alle Eigenschaften dieser Website erhalten.

Im folgenden Beispiel werden Titel und Beschreibung der angegebenen Website angezeigt, obwohl alle anderen standardmäßig zurückgegebenen Eigenschaften verfügbar werden, nachdem das Websiteobjekt geladen und die Abfrage ausgeführt wurde.

function retrieveWebSite(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();

    clientContext.load(this.oWebsite);

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded(sender, args) {
    alert('Title: ' + this.oWebsite.get_title() + 
        ' Description: ' + this.oWebsite.get_description());
}
    
function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Abrufen nur ausgewählter Eigenschaften einer Website

Sie können die unnötige Übertragung von Daten zwischen Client und Server reduzieren, indem Sie nicht alle, sondern nur angegebene Eigenschaften des Websiteobjekts zurückgeben. In diesem Fall verwenden Sie LINQ-Abfragen oder die Lambda-Ausdruckssyntax mit der load(clientObject)-Methode, um anzugeben, welche Eigenschaften vom Server zurückgegeben werden sollen. Im folgenden Beispiel werden nur der Titel und das Erstellungsdatum des Websiteobjekts verfügbar, nachdem executeQueryAsync(succeededCallback, failedCallback) aufgerufen wurde.

function retrieveWebSiteProperties(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();

    clientContext.load(this.oWebsite, 'Title', 'Created');

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded(sender, args) {
    alert('Title: ' + this.oWebsite.get_title() + 
        ' Created: ' + this.oWebsite.get_created());
}
    
function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Festlegen der Eigenschaften einer Website

Zum Ändern einer Website legen Sie deren Eigenschaften fest und rufen ähnlich wie im Serverobjektmodell die update()-Methode auf. Im Clientobjektmodell müssen Sie jedoch executeQueryAsync(succeededCallback, failedCallback) aufrufen, um die Batchverarbeitung aller angegebenen Befehle anzufordern. Im folgenden Beispiel werden der Titel und die Beschreibung einer angegebenen Website geändert.

function updateWebSite(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();

    this.oWebsite.set_title('Updated Web Site');
    this.oWebsite.set_description('This is an updated website.');
    this.oWebsite.update();

    clientContext.load(this.oWebsite, 'Title', 'Description');

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded(sender, args) {
    alert('Title: ' + this.oWebsite.get_title() + 
        ' Description: ' + this.oWebsite.get_description());
}
    
function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

SharePoint-Listenaufgaben

Das Arbeiten mit Listenobjekten mit JavaScript ähnelt dem Arbeiten mit Websiteobjekten. Beginnen Sie, indem Sie den ClientContext(serverRelativeUrl)-Konstruktor verwenden und eine URL oder einen URI übergeben, um einen bestimmten Anforderungskontext zurückzugeben. Sie können mithilfe der lists-Eigenschaft der Web-Klasse die Auflistung der Listen einer Website abrufen.

Abrufen aller Eigenschaften aller Listen einer Website

Zum Zurückgeben aller Listen einer Website laden Sie die Listenauflistung über die load(clientObject)-Methode, und rufen Sie dann executeQueryAsync(succeededCallback, failedCallback) auf. Im folgenden Beispiel werden die URL der Website sowie das Datum und die Uhrzeit der Erstellung der Liste angezeigt.

function retrieveAllListProperties(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    this.collList = oWebsite.get_lists();
    clientContext.load(collList);

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    var listInfo = '';
    var listEnumerator = collList.getEnumerator();

    while (listEnumerator.moveNext()) {
        var oList = listEnumerator.get_current();
        listInfo += 'Title: ' + oList.get_title() + ' Created: ' + 
            oList.get_created().toString() + '\n';
    }
    alert(listInfo);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Abrufen der angegebenen Eigenschaften von Listen

Im vorhergehenden Beispiel wurden alle Eigenschaften der Listen einer Website zurückgegeben. Um unnötige Datenübertragungen zwischen Client und Server zu vermeiden, können Sie mit LINQ-Abfrageausdrücken angeben, welche Eigenschaften zurückgegeben werden sollen. In JavaScript geben Sie Include als Teil der Abfragezeichenfolge an, die an die load(clientObject) -Methode übergeben wird, um anzugeben, welche Eigenschaften zurückgegeben werden sollen. Im folgenden Beispiel werden auf diese Weise nur der Titel und die ID der einzelnen Listen der Auflistung zurückgegeben.

function retrieveSpecificListProperties(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    this.collList = oWebsite.get_lists();

    clientContext.load(collList, 'Include(Title, Id)');
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    var listInfo = '';
    var listEnumerator = collList.getEnumerator();

    while (listEnumerator.moveNext()) {
        var oList = listEnumerator.get_current();
        listInfo += 'Title: ' + oList.get_title() + 
            ' ID: ' + oList.get_id().toString() + '\n';
    }
    alert(listInfo);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Speichern abgerufener Listen in einer Auflistung

Wie im folgenden Beispiel dargestellt, können Sie die loadQuery(clientObjectCollection, exp)-Methode anstelle der load(clientObject)-Methode verwenden, um den Rückgabewert in einer anderen Auflistung anstatt in der entsprechenden Listeneigenschaft zu speichern.

function retrieveSpecificListPropertiesToCollection(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    var collList = oWebsite.get_lists();

    this.listInfoCollection = clientContext.loadQuery(collList, 'Include(Title, Id)');
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    var listInfo = '';

    for (var i = 0; i < this.listInfoCollection.length; i++) {
        var oList = this.listInfoCollection[i];
        listInfo += 'Title: ' + oList.get_title() + 
            ' ID: ' + oList.get_id().toString();
    }
    alert(listInfo.toString());
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Anwenden von Filtern auf den Listenabruf

Wie das folgende Beispiel zeigt, können Sie Include-Anweisungen in einer JavaScript-Abfrage schachteln, um Metadaten für eine Liste und deren Felder zurückzugeben. In diesem Beispiel werden alle Felder aus allen Listen einer Website zurückgegeben und der Titel und der interne Name aller Felder angezeigt, deren interner Name die Zeichenfolge "name" enthält.

function retrieveAllListsAllFields(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    var collList = oWebsite.get_lists();

    this.listInfoArray = clientContext.loadQuery(collList, 
        'Include(Title,Fields.Include(Title,InternalName))');

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this._onQueryFailed)
    );
}

function onQuerySucceeded() {
    var listInfo = '';

    for (var i = 0; i < this.listInfoArray.length; i++) {
        var oList = this.listInfoArray[i];
        var collField = oList.get_fields();
        var fieldEnumerator = collField.getEnumerator();
            
        while (fieldEnumerator.moveNext()) {
            var oField = fieldEnumerator.get_current();
            var regEx = new RegExp('name', 'ig');
            
            if (regEx.test(oField.get_internalName())) {
                listInfo += '\nList: ' + oList.get_title() + 
                    '\n\tField Title: ' + oField.get_title() + 
                    '\n\tField Name: ' + oField.get_internalName();
            }
        }
    }
    alert(listInfo);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Erstellen, Aktualisieren und Löschen von Listen

Zum Erstellen, Aktualisieren und Löschen von Listen über das Clientobjektmodell gehen Sie ähnlich vor wie beim Ausführen dieser Aufgaben über das .NET-Clientobjektmodell. Allerdings werden die Clientvorgänge erst abgeschlossen, wenn die executeQueryAsync(succeededCallback, failedCallback)-Funktion aufgerufen wird.

Erstellen und Aktualisieren von Listen

Verwenden Sie zum Erstellen eines Listenobjekts mit JavaScript das ListCreationInformation-Objekt , um seine Eigenschaften zu definieren, und übergeben Sie dieses Objekt dann an die add(parameters) -Funktion des ListCollection-Objekts . Im folgenden Beispiel wird eine neue Ankündigungsliste erstellt.

function createList(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    
    var listCreationInfo = new SP.ListCreationInformation();
    listCreationInfo.set_title('My Announcements List');
    listCreationInfo.set_templateType(SP.ListTemplateType.announcements);

    this.oList = oWebsite.get_lists().add(listCreationInfo);

    clientContext.load(oList);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    var result = oList.get_title() + ' created.';
    alert(result);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Wenn Sie eine Liste nach ihrer Erstellung aktualisieren müssen, können Sie die entsprechenden Listeneigenschaften festlegen und die update()-Funktion vor dem Aufruf von executeQueryAsync(succeededCallback, failedCallback) aufrufen. Die folgenden Änderungen am vorhergehenden Beispiel zeigen dieses Vorgehen.

.
.
.
.
this.oList = oWebsite.get_lists().add(listCreationInfo);

oList.set_description('New Announcements List');
oList.update();

clientContext.load(oList);
clientContext.executeQueryAsync(
    Function.createDelegate(this, this.onQuerySucceeded), 
    Function.createDelegate(this, this.onQueryFailed)
);

Hinzufügen von Feldern zu einer Liste

Verwenden Sie die add(field)-Funktion oder die addFieldAsXml(schemaXml, addToDefaultView, options)-Funktion des FieldCollection-Objekts, um der Feldauflistung einer Liste ein Feld hinzuzufügen. Im folgenden Beispiel wird ein Feld erstellt, das dann vor dem Aufruf von executeQueryAsync(succeededCallback, failedCallback) aktualisiert wird.

function addFieldToList(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);

    var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
    this.oField = oList.get_fields().addFieldAsXml(
        '<Field DisplayName=\'MyField\' Type=\'Number\' />', 
        true, 
        SP.AddFieldOptions.defaultValue
    );

    var fieldNumber = clientContext.castTo(oField,SP.FieldNumber);
    fieldNumber.set_maximumValue(100);
    fieldNumber.set_minimumValue(35);
    fieldNumber.update();

    clientContext.load(oField);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    var result = oField.get_title() + ' added.';
    alert(result);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Löschen einer Liste

Zum Löschen einer Liste rufen Sie die deleteObject()-Funktion des Listenobjekts auf, wie im folgenden Beispiel dargestellt.

function deleteList(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    this.listTitle = 'My Announcements List';

    this.oList = oWebsite.get_lists().getByTitle(listTitle);
    oList.deleteObject();

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    var result = listTitle + ' deleted.';
    alert(result);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Erstellen, Aktualisieren und Löschen von Ordnern

Sie können Ordner bearbeiten, um Ihre Inhalte mithilfe des JavaScript-Objektmodells zu organisieren. In den folgenden Abschnitten ist beschrieben, wie Sie grundlegende Schritte für Ordner ausführen.

Erstellen eines Ordners in einer Dokumentbibliothek

Um einen Ordner zu erstellen, verwenden Sie ein ListItemCreationInformation Objekt, legen den zugrunde liegenden Objekttyp auf SP.FileSystemObjectType.folder fest und übergeben es als Parameter an die addItem(parameters)-Funktion des List-Objekts. Legen Sie Eigenschaften für das Listenelementobjekt fest, das diese Methode zurückgibt, und rufen Sie anschließend die update()-Funktion auf, wie im folgenden Beispiel dargestellt.

function createFolder(resultpanel) {
    var clientContext;
    var oWebsite;
    var oList;
    var itemCreateInfo;

    clientContext = new SP.ClientContext.get_current();
    oWebsite = clientContext.get_web();
    oList = oWebsite.get_lists().getByTitle("Shared Documents");

    itemCreateInfo = new SP.ListItemCreationInformation();
    itemCreateInfo.set_underlyingObjectType(SP.FileSystemObjectType.folder);
    itemCreateInfo.set_leafName("My new folder!");
    this.oListItem = oList.addItem(itemCreateInfo);
    this.oListItem.set_item("Title", "My new folder!");
    this.oListItem.update();

    clientContext.load(this.oListItem);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, successHandler),
        Function.createDelegate(this, errorHandler)
    );

    function successHandler() {
        resultpanel.innerHTML = "Go to the " +
            "<a href='../Lists/Shared Documents'>document library</a> " +
            "to see your new folder.";
    }

    function errorHandler() {
        resultpanel.innerHTML =
            "Request failed: " + arguments[1].get_message();
    }
}

Aktualisieren eines Ordners in einer Dokumentbibliothek

Zum Aktualisieren des Ordnernamens können Sie in die FileLeafRef-Eigenschaft schreiben und die update()-Funktion aufrufen, damit Änderungen wirksam werden, wenn Sie die executeQueryAsync-Methode aufrufen.

function updateFolder(resultpanel) {
    var clientContext;
    var oWebsite;
    var oList;

    clientContext = new SP.ClientContext.get_current();
    oWebsite = clientContext.get_web();
    oList = oWebsite.get_lists().getByTitle("Shared Documents");

    this.oListItem = oList.getItemById(1);
    this.oListItem.set_item("FileLeafRef", "My updated folder");
    this.oListItem.update();

    clientContext.load(this.oListItem);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, successHandler),
        Function.createDelegate(this, errorHandler)
    );

    function successHandler() {
        resultpanel.innerHTML = "Go to the " +
            "<a href='../Lists/Shared Documents'>document library</a> " +
            "to see your updated folder.";
    }

    function errorHandler() {
        resultpanel.innerHTML = "Request failed: " + arguments[1].get_message();
    }
}

Löschen eines Ordners in einer Dokumentbibliothek

Zum Löschen eines Ordners rufen Sie die deleteObject()-Funktion für das Objekt auf. Im folgenden Beispiel wird die getFolderByServerRelativeUrl-Methode verwendet, um den Ordner aus der Dokumentbibliothek abzurufen, und anschließend wird das Element gelöscht.

function deleteFolder(resultpanel) {
    var clientContext;
    var oWebsite;
    var folderUrl;

    clientContext = new SP.ClientContext.get_current();
    oWebsite = clientContext.get_web();

    clientContext.load(oWebsite);
    clientContext.executeQueryAsync(function () {
        folderUrl = oWebsite.get_serverRelativeUrl() + "/Lists/Shared Documents/Folder1";
        this.folderToDelete = oWebsite.getFolderByServerRelativeUrl(folderUrl);
        this.folderToDelete.deleteObject();

        clientContext.executeQueryAsync(
            Function.createDelegate(this, successHandler),
            Function.createDelegate(this, errorHandler)
        );
    }, errorHandler);

    function successHandler() {
        resultpanel.innerHTML = "Go to the " +
            "<a href='../Lists/Shared Documents'>document library</a> " +
            "to make sure the folder is no longer there.";
    }

    function errorHandler() {
        resultpanel.innerHTML = "Request failed: " + arguments[1].get_message();
    }
}

Erstellen, Lesen, Aktualisieren und Löschen von Dateien

Sie können Dateien mithilfe des JavaScript-Objektmodells bearbeiten. In den folgenden Abschnitten ist beschrieben, wie Sie grundlegende Schritte für Dateien ausführen.

Erstellen einer Datei in einer Dokumentbibliothek

Zum Erstellen von Dateien verwenden Sie ein FileCreationInformation-Objekt, legen das URL-Attribut fest und fügen Inhalte als base64-codiertes Bytearray an. Dies ist im folgenden Beispiel dargestellt.

function createFile(resultpanel) {
    var clientContext;
    var oWebsite;
    var oList;
    var fileCreateInfo;
    var fileContent;

    clientContext = new SP.ClientContext.get_current();
    oWebsite = clientContext.get_web();
    oList = oWebsite.get_lists().getByTitle("Shared Documents");

    fileCreateInfo = new SP.FileCreationInformation();
    fileCreateInfo.set_url("my new file.txt");
    fileCreateInfo.set_content(new SP.Base64EncodedByteArray());
    fileContent = "The content of my new file";

    for (var i = 0; i < fileContent.length; i++) {
        
        fileCreateInfo.get_content().append(fileContent.charCodeAt(i));
    }

    this.newFile = oList.get_rootFolder().get_files().add(fileCreateInfo);

    clientContext.load(this.newFile);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, successHandler),
        Function.createDelegate(this, errorHandler)
    );

    function successHandler() {
        resultpanel.innerHTML =
            "Go to the " +
            "<a href='../Lists/Shared Documents'>document library</a> " +
            "to see your new file.";
    }

    function errorHandler() {
        resultpanel.innerHTML = "Request failed: " + arguments[1].get_message();
    }
}

Lesen einer Datei in einer Dokumentbibliothek

Zum Lesen des Inhalts einer Datei führen Sie einen GET-Vorgang für die URL der Datei durch. Dies ist im folgenden Beispiel dargestellt.

function readFile(resultpanel) {
    var clientContext;
    var oWebsite;
    var fileUrl;

    clientContext = new SP.ClientContext.get_current();
    oWebsite = clientContext.get_web();

    clientContext.load(oWebsite);
    clientContext.executeQueryAsync(function () {
        fileUrl = oWebsite.get_serverRelativeUrl() +
            "/Lists/Shared Documents/TextFile1.txt";
        $.ajax({
            url: fileUrl,
            type: "GET"
        })
            .done(Function.createDelegate(this, successHandler))
            .error(Function.createDelegate(this, errorHandler));
    }, errorHandler);

    function successHandler(data) {
        resultpanel.innerHTML =
            "The content of file \"TextFile1.txt\": " + data
    }

    function errorHandler() {
        resultpanel.innerHTML =
            "Request failed: " + arguments[2];
    }
}

Aktualisieren einer Datei in einer Dokumentbibliothek

Zum Aktualisieren des Inhalts der Datei können Sie ein FileCreationInformation-Objekt verwenden und das overwrite-Attribut auf "true" festlegen, indem Sie die set_overwrite()-Methode verwenden. Dies ist in diesem Beispiel dargestellt.

function updateFile(resultpanel) {
    var clientContext;
    var oWebsite;
    var oList;
    var fileCreateInfo;
    var fileContent;

    clientContext = new SP.ClientContext.get_current();
    oWebsite = clientContext.get_web();
    oList = oWebsite.get_lists().getByTitle("Shared Documents");

    fileCreateInfo = new SP.FileCreationInformation();
    fileCreateInfo.set_url("TextFile1.txt");
    fileCreateInfo.set_content(new SP.Base64EncodedByteArray());
    fileCreateInfo.set_overwrite(true);
    fileContent = "The updated content of my file";

    for (var i = 0; i < fileContent.length; i++) {

        fileCreateInfo.get_content().append(fileContent.charCodeAt(i));
    }

    this.existingFile = oList.get_rootFolder().get_files().add(fileCreateInfo);

    clientContext.load(this.existingFile);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, successHandler),
        Function.createDelegate(this, errorHandler)
    );

    function successHandler() {
        resultpanel.innerHTML =
            "Go to the " +
            "<a href='../Lists/Shared Documents'>document library</a> " +
            "to see the updated \"TextFile1.txt\" file.";
    }

    function errorHandler() {
        resultpanel.innerHTML =
            "Request failed: " + arguments[1].get_message();
    }
}

Löschen einer Datei in einer Dokumentbibliothek

Zum Löschen einer Datei rufen Sie die deleteObject()-Funktion für das Objekt auf. Im folgenden Beispiel wird die getFileByServerRelativeUrl-Methode verwendet, um die Datei aus der Dokumentbibliothek abzurufen, und anschließend wird das Element gelöscht.

function deleteFile(resultpanel) {
    var clientContext;
    var oWebsite;
    var fileUrl;

    clientContext = new SP.ClientContext.get_current();
    oWebsite = clientContext.get_web();

    clientContext.load(oWebsite);
    clientContext.executeQueryAsync(function () {
        fileUrl = oWebsite.get_serverRelativeUrl() +
            "/Lists/Shared Documents/TextFile1.txt";
        this.fileToDelete = oWebsite.getFileByServerRelativeUrl(fileUrl);
        this.fileToDelete.deleteObject();

        clientContext.executeQueryAsync(
            Function.createDelegate(this, successHandler),
            Function.createDelegate(this, errorHandler)
        );
    }, errorHandler);

    function successHandler() {
        resultpanel.innerHTML =
            "Go to the " +
            "<a href='../Lists/Shared Documents'>document library</a> " +
            "to confirm that the \"TextFile1.txt\" file has been deleted.";
    }

    function errorHandler() {
        resultpanel.innerHTML = "Request failed: " + arguments[1].get_message();
    }
}

SharePoint-Listenelementaufgaben

Um mithilfe von JavaScript Elemente aus einer Liste zurückzugeben, verwenden Sie die getItemById(id)-Funktion zum Zurückgeben eines einzelnen Elements oder die getItems(query)-Funktion zum Zurückgeben mehrerer Elemente. Anschließend können Sie mit der load(clientObject)-Funktion Listenelementobjekte abrufen, die diese Elemente darstellen.

Abrufen von Listenelementen

Mit der getItems(query) -Funktion können Sie eine CAML-Abfrage (Collaborative Application Markup Language) definieren, die angibt, welche Elemente zurückgegeben werden sollen. Sie können ein nicht definiertes CamlQuery-Objekt übergeben, um alle Elemente aus der Liste zurückzugeben, oder die funktion set_viewXml verwenden, um eine CAML-Abfrage zu definieren und Elemente zurückzugeben, die bestimmte Kriterien erfüllen. Im folgenden Beispiel werden neben den Werten der Spalten "Title" und "Body" die IDs der ersten 100 Elemente der Liste "Announcements" angezeigt, wobei mit den Listenelementen begonnen wird, deren ID größer als 10 ist.

function retrieveListItems(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
        
    var camlQuery = new SP.CamlQuery();
    camlQuery.set_viewXml(
        '<View><Query><Where><Geq><FieldRef Name=\'ID\'/>' + 
        '<Value Type=\'Number\'>1</Value></Geq></Where></Query>' + 
        '<RowLimit>10</RowLimit></View>'
    );
    this.collListItem = oList.getItems(camlQuery);
        
    clientContext.load(collListItem);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    ); 
}

function onQuerySucceeded(sender, args) {
    var listItemInfo = '';
    var listItemEnumerator = collListItem.getEnumerator();
        
    while (listItemEnumerator.moveNext()) {
        var oListItem = listItemEnumerator.get_current();
        listItemInfo += '\nID: ' + oListItem.get_id() + 
            '\nTitle: ' + oListItem.get_item('Title') + 
            '\nBody: ' + oListItem.get_item('Body');
    }

    alert(listItemInfo.toString());
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Zugreifen auf Eigenschafen von ListItem-Objekten mit der Include-Methode

Vier Eigenschaften von ListItem-Objekten sind nicht standardmäßig verfügbar, wenn Sie die Listenelemente displayName, effectiveBasePermissions, hasUniqueRoleAssignments und roleAssignments zurückgeben. Im vorhergehenden Beispiel wird eine Ausnahme vom Typ PropertyOrFieldNotInitializedException zurückgegeben, wenn Sie auf eine dieser Eigenschaften zuzugreifen versuchen. Um auf diese Eigenschaften zuzugreifen, geben Sie die Include-Methode als Teil der Abfragezeichenfolge an, wie im folgenden Beispiel gezeigt.

function retrieveListItemsInclude(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oList = clientContext.get_web().get_lists().getByTitle('Announcements');

    var camlQuery = new SP.CamlQuery();
    camlQuery.set_viewXml('<View><RowLimit>100</RowLimit></View>');
    this.collListItem = oList.getItems(camlQuery);

    clientContext.load(
        collListItem, 
        'Include(Id, DisplayName, HasUniqueRoleAssignments)'
    );
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded(sender, args) {
    var listItemInfo = '';
    var listItemEnumerator = collListItem.getEnumerator();
        
    while (listItemEnumerator.moveNext()) {
        var oListItem = listItemEnumerator.get_current();
        listItemInfo += '\nID: ' + oListItem.get_id() + 
            '\nDisplay name: ' + oListItem.get_displayName() + 
            '\nUnique role assignments: ' + 
            oListItem.get_hasUniqueRoleAssignments();
    }

    alert(listItemInfo.toString());
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Da in diesem Beispiel die Include-Methode verwendet wird, sind nach der Ausführung der Abfrage nur die angegebenen Eigenschaften verfügbar. Daher wird eine PropertyOrFieldNotInitializedException-Ausnahme ausgelöst, wenn Sie versuchen, auf andere als die genannten Eigenschaften zuzugreifen. Darüber hinaus erhalten Sie diesen Fehler, wenn Sie versuchen, Funktionen wie get_contentType oder get_parentList für den Zugriff auf die Eigenschaften enthaltener Objekte zu verwenden.

Beschränkungen beim Abrufen von Elementen

Die loadQuery(clientObjectCollection, exp)-Methode des JavaScript-Objektmodells in SharePoint Foundation 2010 unterstützt die LINQ-Methoden und -Operatoren nicht, die im verwalteten Objektmodell verwendet werden.

Erstellen, Aktualisieren und Löschen von Listenelementen

Das Erstellen, Aktualisieren oder Löschen von Listenelementen im Clientobjektmodell funktioniert ähnlich wie das Ausführen dieser Aufgaben im Serverobjektmodell. Erstellen Sie ein Objekt für ein Listenelement, stellen Sie dessen Eigenschaften ein und aktualisieren Sie dann das Objekt. Verwenden Sie zum Ändern oder Löschen des Listenelementobjekts die Funktion getById(id) des Objekts ListItemCollection, um das Objekt zurückzugeben. Legen sie dann entweder Eigenschaften für das von dieser Methode zurückgegebene Objekt fest und aktualisieren Sie es oder wählen Sie zum Löschen die spezielle Methode für das Objekt. Anders als beim Serverobjektmodell, muss jeder dieser Vorgänge im Clientobjektmodell mit einem Aufruf von executeQueryAsync(succeededCallback, failedCallback) abschließen, damit Änderungen auf dem Server wirksam werden.

Listenelement erstellen

Zum Erstellen von Listenelementen erstellen Sie ein ListItemCreationInformation-Objekt, legen dessen Eigenschaften fest und übergeben das Objekt als Parameter an die addItem(parameters)-Funktion des List-Objekts. Legen Sie Eigenschaften für das Listenelementobjekt fest, das diese Methode zurückgibt, und rufen Sie anschließend die update()-Funktion auf, wie im folgenden Beispiel dargestellt.

function createListItem(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
        
    var itemCreateInfo = new SP.ListItemCreationInformation();
    this.oListItem = oList.addItem(itemCreateInfo);
    oListItem.set_item('Title', 'My New Item!');
    oListItem.set_item('Body', 'Hello World!');
    oListItem.update();

    clientContext.load(oListItem);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    alert('Item created: ' + oListItem.get_id());
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Aktualisieren eines Listenelements

Zum Festlegen der meisten Listenelementeigenschaften können Sie mithilfe eines Spaltenindexers eine Zuweisung definieren und die update()-Funktion aufrufen, sodass Änderungen übernommen werden, wenn Sie executeQueryAsync(succeededCallback, failedCallback) aufrufen. Im folgenden Beispiel wird der Titel des dritten Elements der Liste "Announcements" festgelegt.

function updateListItem(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oList = clientContext.get_web().get_lists().getByTitle('Announcements');

    this.oListItem = oList.getItemById(3);
    oListItem.set_item('Title', 'My Updated Title');
    oListItem.update();

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    alert('Item updated!');
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Löschen eines Listenelements

Um ein Listenelement zu löschen, rufen Sie die deleteObject() -Funktion für das -Objekt auf. Im folgenden Beispiel wird die getItemById(id)- Funktion verwendet, um das zweite Element aus der Liste zurückzugeben, und dann wird das Element gelöscht. SharePoint verwaltet die ganzzahligen IDs von Elementen in Sammlungen, auch wenn sie gelöscht wurden. So kann beispielsweise das zweite Element in einer Liste nicht 2 als Bezeichner aufweisen. Eine ServerException wird zurückgegeben, wenn die deleteObject() -Funktion für ein Element aufgerufen wird, das nicht vorhanden ist.

function deleteListItem(siteUrl) {
    this.itemId = 2;
    var clientContext = new SP.ClientContext(siteUrl);
    var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
    this.oListItem = oList.getItemById(itemId);
    oListItem.deleteObject();

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    alert('Item deleted: ' + itemId);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Wenn Sie z. B. die neue Elementanzahl abrufen möchten, die das Ergebnis eines Löschvorgangs ist, schließen Sie einen Aufruf der update()-Methode ein, um die Liste zu aktualisieren. Zudem müssen Sie entweder das Listenobjekt oder die itemCount-Eigenschaft für das Listenobjekt aufrufen, bevor Sie die Abfrage ausführen. Wenn Sie die Anzahl der Listenelemente am Anfang und am Ende abrufen möchten, müssen Sie zwei Abfragen ausführen und die Elementanzahl zweimal zurückgeben, wie es in der folgenden Änderung des vorherigen Beispiels gezeigt wird.

function deleteListItemDisplayCount(siteUrl) {
    this.clientContext = new SP.ClientContext(siteUrl);
    this.oList = clientContext.get_web().get_lists().getByTitle('Announcements');
    clientContext.load(oList);

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.deleteItem), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function deleteItem() {
    this.itemId = 58;
    this.startCount = oList.get_itemCount();
    this.oListItem = oList.getItemById(itemId);
    oListItem.deleteObject();

    oList.update();
    clientContext.load(oList);
        
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.displayCount), 
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function displayCount() {
    var endCount = oList.get_itemCount();
    var listItemInfo = 'Item deleted: ' + itemId + 
        '\nStart Count: ' +  startCount + 
        ' End Count: ' + endCount;
        
    alert(listItemInfo)
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + 
        '\n' + args.get_stackTrace());
}

Zugreifen auf Objekte im Hostweb

Bei der Entwicklung Ihres Add-Ins müssen Sie möglicherweise auf das Hostweb zugreifen, um mit elementen darin zu interagieren. Verwenden Sie das AppContextSite-Objekt , um auf das Hostweb oder andere SharePoint-Websites zu verweisen, wie im folgenden Beispiel gezeigt. Ein vollständiges Codebeispiel finden Sie unter Abrufen des Hostwebtitels mithilfe der domänenübergreifenden Bibliothek (JSOM).

function execCrossDomainRequest(appweburl, hostweburl) {
    // context: The ClientContext object provides access to
    //      the web and lists objects.
    // factory: Initialize the factory object with the
    //      add-in web URL.
    var context;
    var factory;
    var appContextSite;

    context = new SP.ClientContext(appweburl);
    factory = new SP.ProxyWebRequestExecutorFactory(appweburl);
    context.set_webRequestExecutorFactory(factory);
    appContextSite = new SP.AppContextSite(context, hostweburl);

    this.web = appContextSite.get_web();
    context.load(this.web);

    // Execute the query with all the previous 
    //  options and parameters.
    context.executeQueryAsync(
        Function.createDelegate(this, successHandler), 
        Function.createDelegate(this, errorHandler)
    );

    // Function to handle the success event.
    // Prints the host web's title to the page.
    function successHandler() {
        alert(this.web.get_title());
    }

    // Function to handle the error event.
    // Prints the error message to the page.
    function errorHandler(data, errorCode, errorMessage) {
        alert("Could not complete cross-domain call: " + errorMessage);
    }
}

Im vorherigen Beispiel wird die domänenübergreifende Bibliothek in SharePoint zum Zugreifen auf das Hostweb verwendet. Weitere Informationen finden Sie unter Zugreifen auf SharePoint-Daten über Add-Ins mithilfe der domänenübergreifenden Bibliothek.

Siehe auch

• Entwickeln von SharePoint-Add-ins
• Sicherer Datenzugriff und Clientobjektmodelle für SharePoint-Add-Ins
• Arbeiten mit externen Daten in SharePoint