Использование экспериментального мини-приложения People Picker в надстройках SharePoint

Статья
04/08/2023

Мини-приложение People Picker можно использовать на любой веб-странице, даже если она не размещена в SharePoint. Используйте мини-приложение People Picker в своих надстройках, чтобы помочь пользователям находить и выбирать людей и группы.

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

Экспериментальные мини-приложения Office для веб-страниц предоставляются только в целях исследования и сбора отзывов. Не используйте их в рабочей среде. Поведение мини-приложений Office для веб-страниц может существенно измениться в будущих выпусках. Ознакомьтесь с условиями лицензии на экспериментальные мини-приложения Office для веб-страниц.

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

Обработка запроса мини-приложением People Picker

Экспериментальный элемент управления People Picker на странице

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

Свойство	Описание
department	Подразделение пользователя или группы.
displayName	Отображаемое имя пользователя или группы.
email	Электронный адрес пользователя или группы.
isResolved	Указывает, удалось ли мини-приложению разрешить текст для пользователя или группы в клиенте.
jobTitle	Должность пользователя.
loginName	Имя для входа пользователя или группы.
mobile	Номер мобильного телефона пользователя или группы.
principalId	Основной идентификатор пользователя или группы.
principalType	Указывает, является ли элемент пользователем или группой. Принимает значение 1, если это пользователь, и 4, если это группа.
sipAddress	SIP-адрес пользователя или группы.
text	Текстовый заголовок имени пользователя или группы.

Мини-приложение "Выбор людей" имеет кэш последних использовавшихся записей (MRU). В кэше хранятся пять последних записей, которые были обработаны мини-приложением.

Необходимые условия для использования примеров в этой статье

Для использования примеров, описанных в этой статье, вам потребуются:

Visual Studio 2013 или более поздней версии.
Диспетчер пакетов NuGet. Дополнительные сведения см. в статье Установка NuGet.
Среда разработки SharePoint (для локальных сценариев требуется изоляция приложений).
Пакет NuGet "Экспериментальные мини-приложения Office для веб-страниц". Дополнительные сведения об установке пакетов NuGet см. в статье Пользовательский интерфейс диспетчера пакетов NuGet. Вы также можете просмотреть страницу коллекции NuGet.

В этом примере простая страница размещена вне платформы SharePoint, объявляющей мини-приложение People Picker с помощью разметки. Для простоты в этом примере параметры не объявлены, но вы можете посмотреть пример с параметрами в разделе Дальнейшие действия.

Чтобы использовать мини-приложение People Picker, выполните следующие действия:

Создайте надстройку SharePoint и веб-проекты.
Создайте модуль на сайте надстройки. Этот шаг обеспечит создание сайта надстройки при развертывании надстройки пользователями.

Примечание.

Междоменная библиотека требует наличия сайта надстройки. Мини-приложение People Picker взаимодействует с SharePoint посредством междоменной библиотеки.
Создайте страницу надстройки, в которой с помощью разметки объявляется экземпляр мини-приложения People Picker.

Создание надстройки SharePoint и веб-проектов

Откройте Visual Studio от имени администратора. (Для этого выберите значок Visual Studio в меню Пуск и пункт Запуск от имени администратора.)
Создайте проект, используя шаблон "Надстройка SharePoint". Шаблон Надстройка SharePoint находится в следующем разделе: Шаблоны>Visual C#, Office/SharePoint>Надстройки.
Укажите URL-адрес веб-сайта SharePoint, который вы хотите использовать для отладки.
Выберите для надстройки вариант размещения Размещено у поставщика.

Примечание.

Мини-приложение People Picker можно использовать и с другими вариантами размещения, а также с надстройками Office или собственным веб-сайтом.
Выберите Приложение веб-форм ASP.NET в качестве типа проекта веб-приложения.
Выберите службу контроля доступа Windows Azure в качестве способа проверки подлинности.

Создание модуля на сайте надстройки

Выберите проект надстройки SharePoint в обозревателе решений. Выберите Добавить>Создать элемент.
Выберите Элементы Visual C#>Office/SharePoint>Модуль. Укажите имя модуля.

Примечание.

При создании надстройки с размещением в SharePoint нет необходимости создавать дополнительный модуль.

Выберите папку Страницы веб-проекта в обозревателе решений.

Скопируйте следующий код и вставьте его в файл ASPX в проекте. Этот код выполняет следующие задачи.

добавляет ссылки на необходимые библиотеки и ресурсы Office;
инициализирует среду выполнения элементов управления;
запускает метод renderAll среды выполнения элементов управления Office;
объявляет заполнитель для мини-приложения People Picker.

<!DOCTYPE html>
<html>
<head>
<!-- IE9 or superior -->
    <meta http-equiv="X-UA-Compatible" content="IE=9" >
    <title>People Picker HTML Markup</title>

    <!-- Widgets Specific CSS File -->
    <link 
        rel="stylesheet" 
        type="text/css" 
        href="../Scripts/Office.Controls.css" 
    />

<!-- Ajax, jQuery, and utils --> 
    <script 
        src=" https://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js.js">
    </script>
    <script 
        src=" https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.9.1.min.js">
    </script>
    <script type="text/javascript">
        // Function to retrieve a query string value.
        // For production purposes you may want to use
        //  a library to handle the query string.
        function getQueryStringParameter(paramToRetrieve) {
            var params =
                document.URL.split("?")[1].split("&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>

<!-- Cross-Domain Library and Office controls runtime -->
    <script type="text/javascript">
        //Register namespace and variables used through the sample
        Type.registerNamespace("Office.Samples.PeoplePickerBasic");
        //Retrieve context tokens from the querystring
        Office.Samples.PeoplePickerBasic.appWebUrl =
            decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));
        Office.Samples.PeoplePickerBasic.hostWebUrl =
            decodeURIComponent(getQueryStringParameter("SPHostUrl"));

        //Pattern to dynamically load JSOM and and the cross-domain library
        var scriptbase =
            Office.Samples.PeoplePickerBasic.hostWebUrl + "/_layouts/15/";

        //Get the cross-domain library
        $.getScript(scriptbase + "SP.RequestExecutor.js",
            //Get the Office controls runtime and 
            //  continue to the createControl function
            function () {
                $.getScript("../Scripts/Office.Controls.js", createControl)
            }
        );
    </script>

<!--People Picker -->
    <script 
        src="../Scripts/Office.Controls.PeoplePicker.js" 
        type="text/javascript">
    </script>
</head>
<body>
    Basic People Picker sample (HTML markup declaration):
    <div 
            id="PeoplePickerDiv" 
            data-office-control="Office.Controls.PeoplePicker">
    </div>

    <script type="text/javascript">
        function createControl() {
            //Initialize Controls Runtime
            Office.Controls.Runtime.initialize({
                sharePointHostUrl: Office.Samples.PeoplePickerBasic.hostWebUrl,
                appWebUrl: Office.Samples.PeoplePickerBasic.appWebUrl
            });

            //Render the widget, this must be executed after the
            //placeholder DOM is loaded
            Office.Controls.Runtime.renderAll();
        }
    </script>
</body>
</html>

Примечание.

В приведенном выше примере кода явно указаны URL-адреса хост-сайта и сайта надстройки, чтобы инициализировать среду выполнения для элементов управления Office. Однако если URL-адреса хост-сайта и сайта надстройки указаны в параметрах строки запроса SPAppWebUrl и SPHostUrl соответственно, то вы можете передать пустой объект, и код попытается получить параметры автоматически. Параметры SPAppWebUrl и SPHostUrl включаются в строку запроса при использовании маркера {StandardTokens}.

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

// Initialize with an empty object and the code 
// will attempt to get the tokens from the
// query string directly.
Office.Controls.Runtime.initialize({});

Сборка и запуск решения

Нажмите клавишу F5.

Примечание.

При нажатии клавиши F5 Visual Studio выполняет сборку решения, развертывает надстройку и открывает страницу разрешений.
Нажмите кнопку Доверять.
Выберите значок надстройки на странице Содержимое сайта.

Чтобы скачать этот пример из коллекции кода, см. пример кода Использование экспериментального мини-приложения People Picker в надстройке.

Дальнейшие действия

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

Для объявления мини-приложения можно использовать JavaScript, а не HTML. В этом случае в качестве заполнителя для мини-приложения можно использовать следующую разметку:

<div id="PeoplePickerDiv"></div>

Используйте приведенный ниже код JavaScript для создания экземпляров мини-приложения People Picker.

new Office.Controls.PeoplePicker(
    document.getElementById("PeoplePickerDiv"), {});

Пример кода, который показывает, как выполнять эти действия, размещен на странице JSSimple.html в разделе Использование экспериментального мини-приложения "Выбор людей" в надстройке.

Параметры мини-приложения можно задать с помощью атрибута data-office-options в объявлении мини-приложения. Следующий HTML-код демонстрирует способ задания параметров мини-приложения "Выбор людей".

<div id="PeoplePickerDiv"
        data-office-control="Office.Controls.PeoplePicker"
        data-office-options='{
        "allowMultipleSelections" : true,
        "onChange" : handleChange,
        "placeholder" : "Check the count message, it changes when you add names..."
    }'>
</div>

В приведенном ниже коде показано, как задать параметры при объявлении мини-приложения People Picker с помощью JavaScript.

new Office.Controls.PeoplePicker(
    document.getElementById("PeoplePickerDiv"), {
        allowMultipleSelections: true,
        placeholder: "Check the count message, it changes when you add names...",
        onChange: function (ctrl) {
            document.getElementById("count").textContent = 
ctrl.selectedItems.length.toString();
        }
    });

Кроме того, вы можете указать обработчики для таких событий, как onChange, onAdded и onRemoved. Обратите внимание, что в приведенном выше коде обработчик события onChange принимает единственный параметр ctrl, который является ссылкой на мини-приложение.

Пример указания параметров приведен на страницах MarkupOptions.html и JSOptions.html в разделе Использование экспериментального мини-приложения "Выбор людей" в надстройке.

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

Получите ссылку на мини-приложение.
Получите доступ к свойству selectedItems мини-приложения.

Вы можете получить ссылку на мини-приложение с помощью приведенного ниже синтаксиса.

var pplPicker = document.getElementById("PeoplePickerDiv")._officeControl;

Вы также можете сохранить ссылку при создании экземпляра мини-приложения.

var pplPicker = new Office.Controls.PeoplePicker(
                        document.getElementById("PeoplePickerDiv"), {});

Свойство selectedItems — это массив объектов, представляющих людей или группы. Люди или группы в массиве selectedItems могут быть разрешенными или неразрешенными. Это можно проверить с помощью свойства isResolved. В следующем примере показано, как получить доступ к элементу i в массиве и использовать имя пользователя или группы.

var principal = pplPicker.selectedItems[i];
$("#msg").text(principal.text + " is selected in the control.");

Пример способа загрузки выбранных людей или групп из мини-приложения приведен на странице demo.html в разделе Веб-виджеты Office экспериментальная демо-версия.

Разработчику может потребоваться настроить пользовательский интерфейс. На рисунке ниже представлена HTML-иерархия мини-приложения после его преобразования. Мини-приложение определяет множество классов с префиксом office-peoplepicker, которые можно найти и настроить в таблице стилей Office.Controls.css.

HTML-иерархия в мини-приложении People Picker

HTML-иерархия в мини-приложении People Picker

Экспериментальное мини-приложение People Picker позволяет выбирать людей и группы в клиенте, а затем передавать выбранные субъекты в надстройку. Свои идеи и комментарии вы можете оставить на сайте UserVoice для разработчиков Office.

Поделиться через

Использование экспериментального мини-приложения People Picker в надстройках SharePoint

Необходимые условия для использования примеров в этой статье

Использование мини-приложения People Picker в надстройке SharePoint с размещением у поставщика

Создание надстройки SharePoint и веб-проектов

Создание модуля на сайте надстройки

Добавление новой страницы, использующей мини-приложение People Picker

Сборка и запуск решения

Дальнейшие действия

Использование JavaScript для объявления мини-приложения People Picker

Указание параметров мини-приложения

Получение пользователей или групп, выбранных в мини-приложении

Настройка стиля мини-приложения

См. также

Дополнительные ресурсы