Выполнение базовых операций с использованием кода библиотеки JavaScript в SharePoint

Предупреждение

Эти сведения действительны только при использовании классических функций SharePoint в SharePoint Online или локальной среде. Использование классической клиентской объектной модели JavaScript для SharePoint не поддерживается в современных интерфейсах и SharePoint Framework.

С помощью клиентской объектной модели SharePoint вы можете получать и обновлять данные в SharePoint, а также управлять ими. В SharePoint объектная модель доступна в нескольких формах:

  • распространяемые сборки .NET Framework;
  • библиотека JavaScript;
  • конечные точки REST и OData;
  • Сборки Windows Phone
  • распространяемые сборки Silverlight.

Дополнительные сведения о наборах API, доступных для SharePoint, см. в статье Выбор правильного набора API в SharePoint.

Примечание.

Пример создания надстройки SharePoint "Hello World", использующей библиотеку JavaScript, см. в статье Работа с данными SharePoint с помощью API JavaScript для SharePoint.

В этой статье описано, как выполнять базовые операции с помощью объектной модели JavaScript. Вы можете добавить ссылку на объектную модель, используя HTML-теги <script>. Сведения об использовании других клиентских API см. в статьях ниже.

Выполнение основных задач в SharePoint с помощью клиентской объектной модели JavaScript

В следующих разделах описываются задачи, которые вы можете выполнять программным путем. Они включают примеры кода на языке JavaScript, в которых демонстрируются эти операции.

При создании облачной надстройки вы можете добавить ссылку на объектную модель, используя HTML-теги <script>. Рекомендуем создать ссылку на хост-сайт, так как сайт надстройки может быть доступен не в каждом сценарии работы с облачными надстройками. Вы можете получить URL-адрес хост-сайта из параметра строки запроса SPHostUrl, если используете маркер {StandardTokens}. Вы также можете использовать специальный параметр строки запроса, если применяете токен {HostUrl}. Получив URL-адрес хост-сайта, вам нужно с помощью кода JavaScript динамично создать ссылку на объектную модель.

В примере кода ниже выполняются такие задачи для добавления ссылки на объектную модель JavaScript:

  • Создание ссылки на библиотеку AJAX из сети Microsoft Content Delivery Network (CDN).
  • Создание ссылки на библиотеку jQuery из сети Microsoft CDN.
  • Извлечение URL-адреса хост-сайта из строки запроса.
  • Загрузка файлов SP.Runtime.js и SP.js с помощью функции getScript в jQuery. После загрузки файлов программа получит доступ к объектной модели JavaScript для SharePoint.
  • Продолжение рабочего процесса функции execOperation.
<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>


При создании надстройки, размещенной в SharePoint, можно добавить ссылку на объектную модель с помощью тегов HTML <script> . Веб-сайт надстроек в надстройке, размещенной в SharePoint, позволяет использовать относительные пути для ссылки на необходимые файлы для использования объектной модели JavaScript.

Следующая разметка выполняет указанные далее задачи для добавления ссылки на объектную модель JavaScript:

  • Создание ссылки на библиотеку AJAX из сети Microsoft CDN.
  • Создание ссылки на файл SP.Runtime.js с использованием относительного URL-адреса сайта надстройки.
  • Создание ссылки на файл SP.js с использованием относительного URL-адреса сайта надстройки.
<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

Для работы с веб-сайтами с использованием JavaScript начните с использования конструктора ClientContext(serverRelativeUrl) и передачи URL-адреса или URI-кода для возврата определенного контекста запроса.

Получение свойств веб-сайта

Используйте веб-свойства класса ClientContext, чтобы указать свойства объекта веб-сайта, который размещен по указанному URL-адресу контекста. После загрузки объекта веб-сайта с помощью метода load(clientObject) и последующего вызова executeQueryAsync(succeededCallback, failedCallback) вы можете получить доступ ко всем свойствам этого веб-сайта.

В примере ниже отображается заголовок и описание указанного веб-сайта, хотя все другие возвращаемые свойства по умолчанию становятся доступными после загрузки объекта веб-сайта и выполнения запроса.


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());
}

Получение определенных свойств веб-сайта

Для снижения объема передаваемых данных между клиентом и сервером можно получать только указанные свойства объекта веб-сайта, а не все свойства. В этом случае используйте запрос LINQ или синтаксис лямбда-выражений с методом load(clientObject) для определения того, какие свойства следует получать от сервера. В следующем примере после вызова запроса executeQueryAsync(succeededCallback, failedCallback) доступны только заголовок и дата создания объекта веб-сайта.

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());
}

Примечание.

Если вы попытаетесь получить доступ к другим свойствам, код создает исключение, так как они недоступны.


Запись значений для свойств веб-сайта

Для изменения веб-сайта следует задать его свойства и вызвать метод update() аналогично применению серверной объектной модели. Однако в клиентской объектной модели следует вызвать executeQueryAsync(succeededCallback, failedCallback) для запроса пакетной обработки всех указанных команд. В следующем примере изменяется заголовок и описание указанного веб-сайта.

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

Работа с объектами списка с помощью JavaScript аналогична работе с объектами веб-сайта. Начинайте работу с использования конструктора ClientContext(serverRelativeUrl) и передачи URL-адреса или URI-кода для возврата определенного контекста запроса. После этого можно использовать свойство lists класса Web для получения коллекции списков на веб-сайте.

Извлечение всех свойств всех списков на веб-сайте

Для возврата всех списков веб-сайта загрузите коллекцию списков с помощью метода load(clientObject), а затем вызовите executeQueryAsync(succeededCallback, failedCallback). В следующем примере представлен URL-адрес веб-сайта, а также дата и время создания списка.

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());
}

Извлечение только заданных свойств списков

В предыдущем примере выполнялся возврат всех свойств списков на веб-сайте. Для уменьшения ненужных данных, передаваемых между клиентом и сервером, можно использовать выражения запросов LINQ, чтобы указать возвращаемые свойства. В JavaScript в строке запроса, передаваемой методу load(clientObject), необходимо указать Include, чтобы указать возвращаемые свойства. В следующем примере этот подход используется для возврата только заголовка и идентификатора каждого из списков в коллекции.

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());
}


Хранение полученных списков в коллекции

Как показывает следующий пример, вы можете использовать метод loadQuery(clientObjectCollection, exp) вместо метода load(clientObject) для хранения возвращаемого значения в другой коллекции вместо его сохранения в свойстве списков.

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());
}

Применение фильтров для извлечения списков

Как показано в следующем примере, можно вложить инструкции Include в запрос JavaScript, чтобы вернуть метаданные как для списка, так и для его полей. В примере возвращаются все поля из всех списков на веб-сайте, а также отображаются заголовок и внутреннее имя всех полей, внутреннее имя которых содержит строку "name".

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());
}


Создание, обновление и удаление списков

Создание, обновление и удаление списков с использованием клиентской объектной модели аналогично выполнению этих операций с помощью серверной объектной модели .NET, хотя клиентские операции не будут завершены до вызова функции executeQueryAsync(succeededCallback, failedCallback).

Создание и обновление списка

Чтобы создать объект списка с помощью JavaScript, используйте объект ListCreationInformation для определения его свойств, а затем передайте этот объект в функцию add(parameters) объекта ListCollection . В следующем примере создается список объявлений.

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());
}

Если нужно обновить список после его создания, можно задать свойства списка и вызвать функцию update() перед вызовом executeQueryAsync(succeededCallback, failedCallback), как показано далее в измененном примере.

.
.
.
.
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)
);

Добавление поля в список

Используйте функцию add(field) или addFieldAsXml(schemaXml, addToDefaultView, options) объекта FieldCollection для добавления поля в коллекцию полей списка. В следующем примере создается поле, которое затем обновляется перед вызовом executeQueryAsync(succeededCallback, failedCallback).

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());
}

Удаление списка

Чтобы удалить список, вызовите функцию deleteObject() объекта списка, как показано в примере ниже.

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());
}

Создание, обновление и удаление папок

Вы можете управлять папками, чтобы упорядочить содержимое с помощью объектной модели JavaScript. В следующих разделах рассказывается об основных операциях с папками.

Создание папки в библиотеке документов

Чтобы создать папку, нужно использовать объект ListItemCreationInformation, задать базовый тип объекта как SP.FileSystemObjectType.folder, а затем передать его в виде параметра в функцию addItem(parameters) объекта List. Затем необходимо задать свойства для объекта элемента списка, возвращенного этим методом, и вызвать функцию update(), как показано в примере ниже.

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();
    }
}

Обновление папки в библиотеке документов

Чтобы изменить имя папки, вы можете записать его в свойство FileLeafRef и вызвать функцию update(), чтобы изменения вступили в силу при вызове метода executeQueryAsync.

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();
    }
}

Удаление папки в библиотеке документов

Чтобы удалить папку, следует вызвать функцию deleteObject() объекта. В следующем примере метод getFolderByServerRelativeUrl используется для извлечения папки из библиотеки документов и удаления элемента.

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();
    }
}

Создание, чтение, обновление и удаление файлов

Управлять файлами можно с помощью объектной модели JavaScript. В следующих разделах рассказывается об основных операциях с файлами.

Примечание.

С помощью объектной модели JavaScript можно работать только с файлами размером до 1,5 МБ. Чтобы отправлять более крупные файлы, используйте REST. Дополнительные сведения см. в разделе Завершение базовых операций с помощью конечных точек REST SharePoint.

Создание файла в библиотеке документов

Для создания файлов используйте объект FileCreationInformation, задав атрибут URL и добавив контент как байтовый массив в кодировке Base64, как показано в следующем примере.

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();
    }
}

Чтение файла в библиотеке документов

Для чтения контента файла используйте операцию GET с URL-адресом файла, как показано в следующем примере.

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];
    }
}

Обновление файла в библиотеке документов

Чтобы изменить контент файла, используйте объект FileCreationInformation, задав атрибут перезаписи равным "true" с помощью метода set_overwrite(), как показано в следующем примере.

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();
    }
}

Удаление файла в библиотеке документов

Чтобы удалить файл, следует вызвать функцию deleteObject() объекта. В следующем примере метод getFileByServerRelativeUrl используется для извлечения файла из библиотеки документов и удаления элемента.

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

Чтобы получить элементы из списка с помощью JavaScript, используйте функцию getItemById(id) для возврата одного элемента или функцию getItems(query) для извлечения нескольких элементов. Затем можно использовать функцию load(clientObject), чтобы получить объекты, представляющие элементы списка.

Получение элементов из списка

Функция getItems(query) позволяет определить запрос CAML, указывающий, какие элементы следует возвращать. Вы можете передать неопределенный объект CamlQuery , чтобы вернуть все элементы из списка, или использовать функцию set_viewXml для определения запроса CAML и возврата элементов, соответствующих определенным условиям. В следующем примере отображается идентификатор (помимо значений столбцов Title и Body) первых 100 элементов списка объявлений, начиная с элементов списка, идентификатор коллекции которых превышает 10.

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());
}

Использование метода Include для доступа к свойствам объектов ListItem

При возврате элементов списка четыре свойства объектов ListItem недоступны по умолчанию: displayName, effectiveBasePermissions, hasUniqueRoleAssignments и roleAssignments. Если в предыдущем примере попытаться получить доступ к одному из этих свойств, возвращается исключение PropertyOrFieldNotInitializedException. Чтобы получить доступ к этим свойствам, используйте метод Include в строке запроса, как показано в примере ниже.

Примечание.

При использовании LINQ для создания запросов к клиентской объектной модели используется LINQ to Objects, а не поставщик LINQ to SharePoint, который можно использовать только при написании кода для серверной объектной модели.

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());
}


Так как в этом примере используется метод Include, после выполнения запроса доступны только указанные свойства. Поэтому если вы попытаетесь получить доступ к другим свойствам помимо указанных, будет возвращено исключение PropertyOrFieldNotInitializedException. Кроме того, эта ошибка возникает при попытке использовать такие функции, как get_contentType или get_parentList для доступа к свойствам содержащих объекты.

Ограничения на получение элементов

Метод loadQuery(clientObjectCollection, exp) объектной модели JavaScript в SharePoint Foundation 2010 не поддерживает методы и операторы LINQ, которые используются в управляемой объектной модели.


Создание, обновление и удаление элементов списков

Создание, обновление и удаление элементов списка с использованием клиентской объектной модели аналогично выполнению этих задач с помощью серверной объектной модели. Можно создать объект элемента списка, установить его свойства, а затем обновить этот объект. Чтобы изменить или удалить объект элемента списка, необходимо вернуть этот объект с помощью функции getById(id) объекта ListItemCollection, а затем либо установить свойства и вызвать обновление в объекте, возвращенном методом, либо вызвать собственный метод объекта для удаления. В отличие от серверной объектной модели, каждая из этих операций в клиентской объектной модели должна завершаться вызовом метода executeQueryAsync(succeededCallback, failedCallback), чтобы изменения вступили в силу на сервере.

Создание элемента списка

Чтобы создать элементы списка, следует создать объект ListItemCreationInformation, установить его свойства и передать его как параметр в функцию addItem(parameters) объекта List. Затем необходимо задать свойства для объекта элемента списка, возвращенного этим методом, и вызвать функцию update(), как показано в примере ниже.

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());
}

Обновление элемента списка

Для установки большинства свойств элемента списка можно с помощью индексатора столбца создать назначение, а затем вызвать функцию update(), чтобы изменения вступили в силу при вызове executeQueryAsync(succeededCallback, failedCallback). В примере ниже устанавливается заголовок третьего элемента списка Announcements.

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());
}

Удаление элемента списка

Чтобы удалить элемент списка, следует вызвать функцию deleteObject() объекта. В следующем примере используется функция getItemById(id) для возврата второго элемента списка, а затем выполняется удаление элемента. SharePoint обслуживает целочисленные идентификаторы элементов в коллекциях, даже если эти элементы удаляются. Поэтому, например, второй элемент списка должен иметь идентификатор, отличный от 2. ServerException возвращается, если функция deleteObject() вызывается для несуществующего элемента.

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());
}

Если, например, требуется получить новое количество элементов, появившееся в результате операции удаления, следует включить вызов метода update(), чтобы обновить список. Кроме того, перед выполнением запроса необходимо загрузить либо сам объект "list", либо его свойство itemCount. Если требуется получить как исходное, так и итоговое количество элементов списка, то необходимо выполнить два запроса и получить число элементов дважды, как показано в следующем варианте предыдущего примера.

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());
}

Доступ к объектам на хост-сайте

При разработке надстройки может потребоваться доступ к хост-сайту для работы с элементами на нем. Используйте объект AppContextSite для ссылки на хост-сайт или другие сайты SharePoint, как показано в следующем примере. Полный пример кода см. в разделе Получение заголовка хост-сайта с помощью междоменной библиотеки (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);
    }
}

В предыдущем примере для доступа к хост-сайту используется междоменная библиотека в SharePoint. Дополнительные сведения см. в статье Обращение к данным SharePoint из надстроек с помощью междоменной библиотеки.

См. также