在 SharePoint 加载项中使用实验版“人员选取器”小组件

项目
04/08/2023

可以在任何网页上使用“人员选取器”小组件，即使该页面未在 SharePoint 中托管也是如此。在加载项中使用“人员选取器”小组件来帮助用户查找和选择人员和组。

警告

Office Web 小组件 - 实验版仅用于研究和反馈目的。请勿在生产方案中使用。 Office Web 小组件行为可能会在将来版本中发生重大变化。阅读和审阅 Office Web 小组件 - 实验版许可条款

您可以在外接程序中使用实验性“人员选取器”小部件，帮助您的用户查找和选择租户中的人员和组。用户可以开始在文本框中键入内容，小部件将检索名字或电子邮件与用户所键入文本匹配的人员。

用于解析查询的“人员选取器”小组件

页面中的人员选取器实验版控件

加载项可以通过读取小组件的 selectedItems 属性来访问选定的人员。 selectedItems 属性是表示人员或组的对象的数组。下表显示用户对象的可用属性。

属性	说明
department	用户或组的部门。
displayName	用户或组的显示名称。
email	用户或组的电子邮件地址。
isResolved	指示小部件是否已针对租户中的用户或组成功解析了小部件中的文本。
jobTitle	用户的职务。
loginName	用户或组的登录名。
mobile	用户或组的移动电话号码。
principalId	用户或组的主体 ID。
principalType	指示项是否为用户或组。如果是用户，则其值为 1;如果是组，则值为 4。
sipAddress	用户或组的 SIP 地址。
text	用户或组名称的文本标题。

“人员选取器”小部件有一个最近使用 (MRU) 项的缓存。缓存中存储了小部件解析的五个最新的项目。

使用本文中的示例的先决条件

若要使用本文中的示例，需要具备：

Visual Studio 2013 或更高版本。
NuGet 包管理器。有关详细信息，请参阅安装 NuGet。
SharePoint 开发环境（本地方案需要应用隔离）。
Office Web 小组件 - 实验版 NuGet 包。有关如何安装 NuGet 包的详细信息，请参阅 NuGet 包管理器 UI。也可以浏览 NuGet 库页面。

在本示例中，有一个简单页面托管在 SharePoint 外部，并声明使用标记的“人员选取器”小组件。为简单起见，此示例未声明任何选项，但可以在 NextSteps 部分中看到包含选项的示例。

若要使用“人员选取器”小组件，必须执行以下操作：

创建 SharePoint 外接程序和多个 Web 项目。
在外接程序 Web 中创建模块。此步骤会确保在用户部署外接程序时，也创建了外接程序 Web。

注意

跨域库需要存在加载项 Web。 “人员选取器”小组件通过使用跨域库与 SharePoint 通信。
创建使用标记声明“人员选取器”小组件实例的加载项页面。

创建一个 SharePoint 加载项和多个 Web 项目

以管理员身份打开 Visual Studio。（为此，请选择“开始”菜单上的“Visual Studio”图标，然后选择“以管理员身份运行”。）
使用 SharePoint 加载项模板新建一个项目。SharePoint 加载项模板位于“模板”>“Visual C#”“Office/SharePoint”>“加载项”下。
提供要用于调试的 SharePoint 网站 URL。
选择“提供程序托管”作为你的加载项的托管选项。

注意

您还可以将“人员选取器”小部件用于其他托管选项，甚至 Office 外接程序或您自己网站。
选择“ASP.NET Web 表单应用程序”作为 Web 应用程序项目的类型。
选择“Windows Azure 访问控制服务”作为身份验证选项。

在加载项 Web 上创建模块

选择“解决方案资源管理器”中的 SharePoint 加载项项目。选择“添加”>“新建项”。
选择“Visual C# 项”>“Office/SharePoint”>“模块”。提供模块的名称。

注意

如果生成 SharePoint 托管的加载项，则无需创建其他模块。

在“解决方案资源管理器”中的 Web 项目中选择“页面”文件夹。

复制以下代码并将其粘贴到项目中的 ASPX 文件中。该代码执行以下任务：

将引用添加到所需的 Office 库和资源。
初始化控件运行时。
运行 Office 控件运行时的 renderAll 方法。
声明“人员选取器”小组件的占位符。

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

注意

前面的代码示例显式指定要初始化 Office 控件运行时的主机 Web 和加载项 Web URL。但是，如果加载项 Web 和主机 Web URL 是在 SPAppWebUrl 和 SPHostUrl 查询字符串参数中分别指定的，则可以传递一个空对象，然后代码将尝试自动获取参数。在使用 {StandardTokens} 令牌时，SPAppWebUrl 和 SPHostUrl 参数将包括在查询字符串中。

下面的示例演示如何将空对象传递给初始化方法：

// 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 会生成解决方案并部署加载项，同时还会打开加载项的权限页面。
选择“信任它”按钮。
选择“网站内容”页上的加载项图标。

若要从代码库下载此示例，请参阅在加载项中使用“人员选取器”实验小组件代码示例。

后续步骤

本文介绍如何通过 HTML，在外接程序中使用“人员选取器”小部件。您还可以浏览关于小部件的以下方案和详细信息。

根据你的偏好，你可能想要使用 JavaScript（而不是 HTML）来声明小组件。如果的确如此，可以使用以下标记作为小组件的占位符。

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

使用以下 JavaScript 代码将“人员选取器”实例化。

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>

以下代码显示了使用 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.");

有关如何从小组件检索所选的人员或组的示例，请参阅 Office Web 小组件 - 实验版演示代码示例中的 demo.html 页面。

作为开发人员，你可能希望自定义小组件的外观。下图显示小组件中呈现的 HTML 层次结构。小组件定义了前缀为 office-peoplepicker 的多个类，可以在 Office.Controls.css 样式表中找到和自定义这些类。

“人员选取器”小组件中的 HTML 层次结构

“人员选取器”控件中的 HTML 层次结构

可以使用实验性“人员选取器”小组件选择租户中的人员和组，然后你的加载项可以使用用户选择的主体。请在 Office 开发人员平台 UserVoice 网站上提供反馈和意见。

通过

在 SharePoint 加载项中使用实验版“人员选取器”小组件

使用本文中的示例的先决条件

在提供程序托管的 SharePoint 加载项中使用“人员选取器”小组件

创建一个 SharePoint 加载项和多个 Web 项目

在加载项 Web 上创建模块

添加要使用“人员选取器”小组件的新页面

生成并运行解决方案

后续步骤

使用 JavaScript 声明“人员选取器”小组件

指定小组件的选项

检索小组件中所选的人员或组

自定义小组件的样式

另请参阅

其他资源