在 SharePoint 外接程序中使用实验版桌面列表视图小部件

项目
06/29/2022

可以在任何网页上使用“桌面列表视图”小组件，即使页面未在 SharePoint 中托管，也不例外。在加载项中使用“列表视图”小组件，以显示 SharePoint 站点上托管的列表中的数据。

警告

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

可以使用“列表视图”小部件显示 SharePoint 列表中的数据，就跟常规“列表视图”小部件一样，但可以将其用于不必在 SharePoint 中托管的外接程序和网站。

显示列表中的数据的“桌面列表视图”小组件

页面上的桌面列表视图实验版控件

可以指定你想用来显示数据的 SharePoint 列表中的视图。“列表视图”小部件将按视图指定的顺序显示列和项目。

“列表视图”小组件使用跨域库获取列表数据。因此，在客户端级别进行通信。

备注

“桌面列表视图”小组件不会启用本机“列表视图”的所有方案。

该小组件的当前版本尚未启用以下方案：

对不受跨域库本机支持的身份验证方案使用小部件。
对小部件使用除 SharePoint 列表或库以外的数据源。
将数据与小部件绑定。
用户触摸友好视图。
用户内联编辑。
显示状态信息。
提供自定义呈现模板。
本地方案。目前小部件仅可在 SharePoint Online 上运行。

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

若要按照本文中的示例操作，需要具备以下各项：

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

在本示例中，有一个简单页面托管在 SharePoint 外部，并声明“桌面列表视图”小部件。

若要使用该“列表视图”小部件，必须执行以下操作：

创建 SharePoint 外接程序和多个 Web 项目。
在加载项 Web 上创建列表。此步骤也会确保在用户部署加载项时，同时创建了加载项 Web。

备注

跨域库需要存在加载项 Web。 “列表视图”小组件通过使用跨域库与 SharePoint 进行通信。
创建使用 HTML 标记声明“列表视图”小组件实例的加载项页面。

创建一个 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” > “列表”。在“名称”文本框中输入 Announcements，然后选择“添加”。
选择“基于现有列表模板创建列表实例”。选择 Announcements 模板，然后选择“完成”。

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

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

将引用添加到所需的 Office 库和资源。
提供“列表视图”小部件的占位符。
初始化控件运行时。
运行 Office 控件运行时的 renderAll 方法。

<!DOCTYPE html>
<html>
<head>
    <!-- IE9 or superior -->
    <meta http-equiv="x-ua-compatible" content="IE=10">
    <title>Desktop List View HTML Markup</title>

    <!-- Controls 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.ListViewBasic");
        //Retrieve context tokens from the querystring
        Office.Samples.ListViewBasic.appWebUrl =
            decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));
        Office.Samples.ListViewBasic.hostWebUrl =
            decodeURIComponent(getQueryStringParameter("SPHostUrl"));
        Office.Samples.ListViewBasic.ctag =
            decodeURIComponent(getQueryStringParameter("SPClientTag"));

        //Pattern to dynamically load JSOM and the cross-domain library
        var scriptbase =
            Office.Samples.ListViewBasic.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>

    <!-- List View -->
    <script 
        src="../Scripts/Office.Controls.ListView.debug.js" 
        type="text/javascript">
    </script>

    <!-- SharePoint CSS -->
    <script type="text/javascript">
        document.addEventListener("DOMContentLoaded", function () {
            // The resource files are in a URL in the form:
            // web_url/_layouts/15/Resource.ashx
            var scriptbase =
                Office.Samples.ListViewBasic.appWebUrl + "/_layouts/15/";

            // Dynamically create the invisible iframe.
            var blankiframe;
            var blankurl;
            var body;
            blankurl =
                Office.Samples.ListViewBasic.appWebUrl + "/Pages/blank.html";
            blankiframe = document.createElement("iframe");
            blankiframe.setAttribute("src", blankurl);
            blankiframe.setAttribute("style", "display: none");
            body = document.getElementsByTagName("body");
            body[0].appendChild(blankiframe);

            // Dynamically create the link element.
            var dclink;
            var head;
            dclink = document.createElement("link");
            dclink.setAttribute("rel", "stylesheet");
            dclink.setAttribute("href",
                                scriptbase +
                                "defaultcss.ashx?ctag=" +
                                Office.Samples.ListViewBasic.ctag
                                );
            head = document.getElementsByTagName("head");
            head[0].appendChild(dclink);
        }, false);
    </script>
</head>
<body>
    Basic List View sample (HTML markup declaration):
    <div id="ListViewDiv"
        data-office-control="Office.Controls.ListView"
        data-office-options='{"listUrl" : getListUrl()}'>
    </div>

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

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

        function getListUrl() {
            return Office.Samples.ListViewBasic.appWebUrl +
                    "/_api/web/lists/getbytitle('Announcements')";
        }
    </script>
</body>
</html>

备注

上面的代码示例显式指定主机 Web 和加载项 Web URL 以初始化 Office 控件运行时。但是，如果加载项 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="ListViewDiv"></div>

使用以下 JavaScript 代码将“列表视图”实例化。

new Office.Controls.ListView(
    document.getElementById("ListViewDiv"), {
        listUrl: Office.Samples.ListViewBasic.appWebUrl + "/_api/web/lists/getbytitle('Announcements')"
    });

有关说明如何执行这些任务的示例，请参阅在加载项中使用“桌面列表视图”实验版小组件代码示例中的 JSSimple.html 页面。

指定用于显示数据的视图

为了在 SharePoint 列表中指定一个视图，“列表视图”小组件使用视图规范显示数据。

如果你使用 HTML 标记声明小组件，可以使用以下语法指定视图。

<div id="ListViewDiv"
        data-office-control="Office.Controls.ListView"
        data-office-options="{listUrl: 'list URL',
                            viewID: 'GUID'
                            }">
</div>

如果你使用 JavaScript 声明小组件，请使用以下语法指定视图。

new Office.Controls.ListView(
    document.getElementById("ListViewDiv"), {
        listUrl: "list URL",
        viewID: "GUID"
    });

可以在 SharePoint 列表中使用实验版桌面列表视图小组件来显示数据。小组件以只读模式显示数据。请在 Office 开发人员平台 UserVoice 网站上提供反馈和意见。

通过

在 SharePoint 加载项中使用“桌面列表视图”实验性小组件

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

在提供程序托管的 SharePoint 加载项中使用“桌面列表视图”小组件

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

在加载项 Web 上创建列表

添加可使用“桌面列表视图”小组件的新页面

生成并运行解决方案

后续步骤

使用 JavaScript 声明“桌面列表视图”小组件

指定用于显示数据的视图

另请参阅

其他资源