使用客户端呈现在 SharePoint 加载项中自定义列表视图Customize a list view in SharePoint Add-ins using client-side rendering

在 SharePoint 中,客户端呈现提供了一种方法,可让你为 SharePoint 页面中托管的一组控件生成自己的输出。In SharePoint, client-side rendering provides a way for you to produce your own output for a set of controls that are hosted on a SharePoint page. 它可以让你使用知名技术(例如 HTML 和 JavaScript)定义 SharePoint 列表视图的呈现逻辑。It enables you to use well-known technologies, such as HTML and JavaScript, to define the rendering logic of SharePoint list views. 通过客户端呈现可以指定自己的 JavaScript 资源,并将其托管在加载项可用的数据存储选项(例如,文档库)中。With client-side rendering, you can specify your own JavaScript resources and host them in the data storage options that are available to your add-ins, such as in a document library. SharePoint 托管的加载项仅包含 SharePoint 组件。A SharePoint-hosted add-in includes only SharePoint components. SharePoint 托管的加载项在主机 Web 的隔离子网站中拥有 其资源,称为加载项 Web。A SharePoint-hosted add-in has its resources in an isolated subsite of the host web, called the add-in web.

使用本文中的示例的先决条件Prerequisites for using the examples in this article

若要按照此示例中的步骤操作,需要:To follow the steps in this example, you need the following:

有关如何设置符合你的需求的开发环境的指南,请参阅两种类型的 SharePoint 加载项:SharePoint 托管的加载项和提供程序托管的加载项For guidance about how to set up a development environment that fits your needs, see Two types of SharePoint Add-ins: SharePoint-hosted and provider-hosted.

用于帮助你理解使用客户端呈现自定义列表视图的核心概念Core concepts to help you understand list view customization with client-side rendering

下表列出了可帮助你理解列表视图自定义方案所涉及的概念的有用文章。The following table lists useful articles that can help you understand the concepts that are involved in a list view customization scenario.

文章标题Article title 说明Description
SharePoint 外接程序SharePoint Add-ins 了解 Microsoft SharePoint 中新的外接程序模型,可以利用此模型来创建外接程序,这些外接程序对最终用户来说是易于使用的小型解决方案。Learn about the new add-in model in Microsoft SharePoint that enables you to create add-ins, which are small, easy-to-use solutions for end users.
适用于 SharePoint 外接程序的 UX 设计UX design for SharePoint Add-ins 了解在生成 SharePoint 外接程序时可使用的 UX 选项。Learn about the UX options that you have when you are building SharePoint Add-ins.
SharePoint 中的主机 Web、外接程序 Web 和 SharePoint 组件Host webs, add-in webs, and SharePoint components in SharePoint 了解主机 Web 和外接程序 Web 之间的区别。找出哪些 SharePoint 组件可以包含在 SharePoint 外接程序中、哪些组件部署到主机 Web、哪些组件部署到外接程序 Web,以及如何将外接程序 Web 部署在独立的域中。Learn about the difference between host webs and add-in webs. Find out which SharePoint components can be included in a SharePoint Add-in, which components are deployed to the host web, which components are deployed to the add-in web, and how the add-in web is deployed in an isolated domain.

代码示例:使用客户端呈现自定义列表视图Code example: Customize a list view by using client-side rendering

以下步骤演示如何使用客户端呈现自定义部署到加载项 Web 的列表视图。The following steps show you how to customize a list view that is deployed to the add-in web by using client-side rendering.

  1. 创建 SharePoint 加载项项目。Create the SharePoint Add-in project.

  2. 创建带有自定义视图的新列表定义。Create a new list definition with a custom view.

  3. 在 JavaScript 文件中提供自定义呈现逻辑。Provide the custom rendering logic in a JavaScript file.

下图显示了公告列表的客户端呈现视图。The following figure shows a client-side rendered view of an announcements list.

公告列表的自定义视图Custom view of an announcements list

公告列表的自定义视图

创建 SharePoint 加载项项目To create the SharePoint Add-in project

  1. 以管理员身份打开 Visual Studio 2015。Open Visual Studio 2015 as administrator. (为此,请右键单击“开始”**** 菜单上的“Visual Studio”**** 图标,再选择“以管理员身份运行”****。)(To do this, right-click the Visual Studio icon on the Start menu, and select Run as administrator.)

  2. 使用 SharePoint 加载项模板创建新的项目。Create a new project using the SharePoint Add-in template.

    下图显示了 SharePoint 加载项模板在 Visual Studio 2015 中的位置,具体位于“模板”**** > “Visual C#”**** > “Office/SharePoint”**** > “Office 加载项”**** 下。The following figure shows the location of the SharePoint Add-in template in Visual Studio 2015, under Templates > Visual C# > Office/SharePoint > Office Add-ins.

    SharePoint 加载项 Visual Studio 模板Add-in for SharePoint Visual Studio template

    SharePoint 相关应用程序 Visual Studio 模板

  3. 提供要用于调试的 SharePoint 网站的 URL。Provide the URL of the SharePoint website that you want to use for debugging.

  4. 选择"Sharepoint 托管"作为您的外接程序的托管选项。Select SharePoint-hosted as the hosting option for your add-in.

创建新的列表定义To create a new list definition

  1. 右键单击 SharePoint 外接程序项目,添加一个新的"列表"项。创建一个基于公告的可自定义列表。Right-click the SharePoint Add-in project, and add a new List item. Create a customizable list based on Announcements.

  2. 复制以下标记并将其粘贴到列表功能的 Schema.xml 文件的 Views 元素中。该标记将执行以下任务:Copy the following markup and paste it in the Views element in the Schema.xml file of your list feature. The markup performs the following tasks:

    • 声明一个名为 Overridable 且 BaseViewID=2 的新视图。Declares a new view named Overridable with a BaseViewID=2.

    • 为指向使用加载项预配的 JavaScript 文件的 JSLink 元素提供一个值。Provides a value for the JSLink element that points to a JavaScript file that is provisioned with the add-in.

    备注

    调查列表或事件列表不支持 JSLink 属性。SharePoint 日历是事件列表。The JSLink property is not supported on Survey or Events lists. A SharePoint calendar is an Events list.

    <View BaseViewID="2" 
        Name="8d2719f3-c3c3-415b-989d-33840d8e2ddb" 
        DisplayName="Overridable" 
        Type="HTML" 
        WebPartZoneID="Main" 
        SetupPath="pages\viewpage.aspx" 
        Url="Overridable.aspx"
        DefaultView="TRUE">
    <ViewFields>
        <FieldRef Name="Title" />
    </ViewFields>
    <Query />
    <Toolbar Type="Standard" />
    <XslLink>main.xsl</XslLink>
    <JSLink Default="TRUE">~site/Scripts/CSRListView.js</JSLink>
    </View>
    

在 JavaScript 文件中提供自定义呈现逻辑To provide the custom rendering logic in a JavaScript file

  1. 右键单击“脚本”**** 文件夹,并添加新的 JavaScript 文件。Right-click the Scripts folder, and add a new JavaScript file. 将文件命名为 CSRListView.jsName the file CSRListView.js.

  2. 复制以下代码并将其粘贴到 CSRListView.js 文件中。该代码将执行以下任务:Copy the following code and paste it in the CSRListView.js file. The code performs the following tasks:

    • PreRenderPostRender 事件提供事件处理程序。Provides event handlers for the PreRender and PostRender events.

    • 提供“页眉、页脚和项”模板集的模板。Provides templates for the Header, Footer, and Item template sets.

    • 注册模板。Registers the templates.

    
    (function () {
        // Initialize the variable that stores the objects.
        var overrideCtx = {};
        overrideCtx.Templates = {};
    
        // Assign functions or plain html strings to the templateset objects:
        // header, footer and item.
        overrideCtx.Templates.Header = "<B><#=ctx.ListTitle#></B>" +
            "<hr><ul id='unorderedlist'>";
    
        // This template is assigned to the CustomItem function.
        overrideCtx.Templates.Item = customItem;
        overrideCtx.Templates.Footer = "</ul>";
    
        // Set the template to the:
        //  Custom list definition ID
        //  Base view ID
        overrideCtx.BaseViewID = 2;
        overrideCtx.ListTemplateType = 10057;
    
        // Assign a function to handle the
        // PreRender and PostRender events
        overrideCtx.OnPreRender = preRenderHandler;
        overrideCtx.OnPostRender = postRenderHandler;
    
        // Register the template overrides.
        SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
    })();
    
    // This function builds the output for the item template.
    // It uses the context object to access announcement data.
    function customItem(ctx) {
    
        // Build a listitem entry for every announcement in the list.
        var ret = "<li>" + ctx.CurrentItem.Title + "</li>";
        return ret;
    }
    
    // The preRenderHandler attends the OnPreRender event
    function preRenderHandler(ctx) {
    
        // Override the default title with user input.
        ctx.ListTitle = prompt("Type a title", ctx.ListTitle);
    }
    
    // The postRenderHandler attends the OnPostRender event
    function postRenderHandler(ctx) {
    
        // You can manipulate the DOM in the postRender event
        var ulObj;
        var i, j;
    
        ulObj = document.getElementById("unorderedlist");
    
        // Reverse order the list.
        for (i = 1; i < ulObj.children.length; i++) {
            var x = ulObj.children[i];
            for (j = 1; j < ulObj.children.length; j++) {
                var y = ulObj.children[j];
                if(x.innerText<y.innerText){                  
                    ulObj.insertBefore(y, x);
                }
            }
        }
    }
    

生成并运行解决方案To build and run the solution

  1. 按 F5 键。Select the F5 key.

    备注

    按 F5 键时,Visual Studio 会生成解决方案并部署加载项,同时还会打开加载项的权限页面。When you select F5, Visual Studio builds the solution, deploys the add-in, and opens the permissions page for the add-in.

  2. 选择“信任它”**** 按钮。Select the Trust It button.

  3. 通过输入相对于加载项 Web 域(不是主机 Web 域)中你的加载项目录的 /Lists/<your_list_instance> 地址转到自定义列表。Go to your custom List by entering the /Lists/<your_list_instance> address relative to your add-in directory in the add-in web domain (not the host web domain). 添加一个或两个公告。Add one or two announcements. 在功能区上,选择“可重写”**** 视图。On the ribbon, select the Overridable view.

另请参阅See also