在 SharePoint 加载项中使用客户端部件版式控制Use the client chrome control in SharePoint Add-ins

利用 SharePoint 的部件版式控制,您无需注册服务器库或使用特定技术或工具即可在外接程序中使用特定 SharePoint 网站的标题样式。若要使用此功能,您必须通过标准 <script> 标记注册 SharePoint JavaScript 库。您可使用 HTML div 元素提供占位符并使用可用选项进一步自定义控件。该控件继承指定的 SharePoint 网站的外观。The chrome control in SharePoint enables you to use the header styling of a specific SharePoint site in your add-in without needing to register a server library or use a specific technology or tool. To use this functionality, you must register a SharePoint JavaScript library through a standard <script> tag. You can provide a placeholder by using an HTML div element and further customize the control by using the available options. The control inherits its appearance from the specified SharePoint website.

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

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

  • Visual Studio 2015Visual Studio 2015
  • SharePoint 开发环境(本地方案需要加载项隔离)A SharePoint development environment (add-in isolation required for on-premises scenarios)

有关如何设置符合你的需求的开发环境的指南,请参阅两种类型的 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 know before using the chrome control

下表列出了可帮助你了解使用部件版式控制的方案中涉及的概念的有用文章。The following table lists useful articles that can help you understand the concepts involved in a scenario that uses the chrome control.

文章标题Article title 说明Description
SharePoint 外接程序SharePoint Add-ins 了解 SharePoint 中新的外接程序模型,可以利用此模型来创建对最终用户来说是小型的易于使用的解决方案的外接程序。Learn about the new add-in model in 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 user experience (UX) options and alternatives that you have when 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 distinction 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: Use the chrome control in your cloud-hosted add-in

云托管加载项至少包含一个远程组件。有关详细信息,请参阅选择用于开发和托管 SharePoint 加载项的模式。若要在云托管加载项中使用部件版式控制,请按照以下步骤操作:A cloud-hosted add-in includes at least one remote component. For more information, see Choose patterns for developing and hosting your SharePoint Add-in. To use the chrome control in your cloud-hosted add-in, follow these steps:

  1. 创建 SharePoint 外接程序和远程 Web 项目。Create the SharePoint Add-in and remote web projects.
  2. 在查询字符串中发送默认配置选项。Send default configuration options in the query string.
  3. 向 Web 项目添加网页。Add a webpage to the web project.

下图显示的是具有部件版式控制的远程网页。The following figure shows a remote webpage with the chrome control.

具有部件版式控制的远程网页Remote webpage with the chrome control

具有部件版式控制的远程网页


创建 SharePoint 加载项和远程 Web 项目To create the SharePoint Add-in and remote web projects

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

  2. 使用“SharePoint 加载项”**** 模板新建项目。Create a new project by 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 模板SharePoint Add-in 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 托管代码示例,请参阅 SharePoint-Add-in-JSOM-BasicDataOperationsSelect Provider-hosted as the hosting option for your add-in. For a SharePoint-hosted code sample, see SharePoint-Add-in-JSOM-BasicDataOperations.

    在向导完成后,你应具有与下图类似的“解决方案资源管理器”**** 中的结构。After the wizard finishes, you should have a structure in Solution Explorer that resembles the following figure.

    解决方案资源管理器中适用于 SharePoint 项目的加载项Add-in for SharePoint projects in Solution Explorer

    解决方案资源管理器中适用于 SharePoint 项目的应用程序


在查询字符串中发送默认配置选项To send default configuration options in the query string

  1. 在清单编辑器中打开 Appmanifest.xml 文件。Open the Appmanifest.xml file in the manifest editor.

  2. {StandardTokens} 令牌和其他 SPHostTitle 参数添加到查询字符串。Add the {StandardTokens} token and an additional SPHostTitle parameter to the query string. 下图显示配置了查询字符串参数的清单编辑器。The following figure shows the manifest editor with the configured query string parameters.

    具有部件版式控制的查询字符串参数的清单编辑器Manifest editor with query string parameters for the chrome control

    具有查询字符串参数的清单编辑器


    部件版式控制将自动采用查询字符串中的下列值:The chrome control automatically takes the following values from the query string:

    • SPHostUrlSPHostUrl
    • SPHostTitleSPHostTitle
    • SPAppWebUrlSPAppWebUrl
    • SPLanguageSPLanguage

    {StandardTokens},包括 SPHostUrlSPAppWebUrl{StandardTokens} include SPHostUrl and SPAppWebUrl.

在 Web 项目中添加使用部件版式控制的页To add a page that uses the chrome control in the web project

  1. 右键单击 Web 项目,并添加新 Web 表单。Right-click the web project, and add a new Web Form.

  2. 复制以下标记,然后将其粘贴到 ASPX 页中。该标记将执行以下任务:Copy the following markup, and paste it in the ASPX page. The markup performs the following tasks:

    • 从 Microsoft CDN(内容交付网络)加载 AJAX 库。Loads the AJAX library from the Microsoft CDN (Content Delivery Network).

    • 从 Microsoft CDN 加载 jQuery 库。Loads the jQuery library from the Microsoft CDN.

    • 使用 jQuery 函数 getScript 加载 SP.UI.Controls.js 文件。Loads the SP.UI.Controls.js file using the jQuery function getScript.

    • 定义 onCssLoaded 事件的回调函数。Defines a callback function for the onCssLoaded event.

    • 为部件版式控制准备选项。Prepares the options for the chrome control.

    • 初始化部件版式控件。Initializes the chrome control.

       <!DOCTYPE html>
     <html xmlns="http://www.w3.org/1999/xhtml">
     <head>
         <title>Chrome control host page</title>
         <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"
             src="ChromeLoader.js">
         </script>
     <script type="text/javascript">
     "use strict";
    
     var hostweburl;
    
     //load the SharePoint resources
     $(document).ready(function () {
         //Get the URI decoded URL.
         hostweburl =
             decodeURIComponent(
                 getQueryStringParameter("SPHostUrl")
         );
    
         // The SharePoint js files URL are in the form:
         // web_url/_layouts/15/resource
         var scriptbase = hostweburl + "/_layouts/15/";
    
         // Load the js file and continue to the 
         //   success handler
         $.getScript(scriptbase + "SP.UI.Controls.js", renderChrome)
     });
    
     // Callback for the onCssLoaded event defined
     //  in the options object of the chrome control
     function chromeLoaded() {
         // When the page has loaded the required
         //  resources for the chrome control,
         //  display the page body.
         $("body").show();
     }
    
     //Function to prepare the options and render the control
     function renderChrome() {
         // The Help, Account and Contact pages receive the 
         //   same query string parameters as the main page
         var options = {
             "appIconUrl": "siteicon.png",
             "appTitle": "Chrome control add-in",
             "appHelpPageUrl": "Help.html?"
                 + document.URL.split("?")[1],
             // The onCssLoaded event allows you to 
             //  specify a callback to execute when the
             //  chrome resources have been loaded.
             "onCssLoaded": "chromeLoaded()",
             "settingsLinks": [
                 {
                     "linkUrl": "Account.html?"
                         + document.URL.split("?")[1],
                     "displayName": "Account settings"
                 },
                 {
                     "linkUrl": "Contact.html?"
                         + document.URL.split("?")[1],
                     "displayName": "Contact us"
                 }
             ]
         };
    
         var nav = new SP.UI.Controls.Navigation(
                                 "chrome_ctrl_placeholder",
                                 options
                             );
         nav.setVisible(true);
     }
    
     // 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>
     </head>
    
     <!-- The body is initally hidden. 
          The onCssLoaded callback allows you to 
          display the content after the required
          resources for the chrome control have
          been loaded.  -->
     <body style="display: none">
    
         <!-- Chrome control placeholder -->
         <div id="chrome_ctrl_placeholder"></div>
    
         <!-- The chrome control also makes the SharePoint
               Website stylesheet available to your page -->
         <h1 class="ms-accentText">Main content</h1>
         <h2 class="ms-accentText">The chrome control</h2>
         <div id="MainContent">
             This is the page's main content. 
             You can use the links in the header to go to the help, 
             account or contact pages.
         </div>
     </body>
     </html>
    

  3. 您还可通过声明性方式使用部件版式控件。在以下代码示例中,HTML 标记无需使用 JavaScript 代码配置和初始化该控件也可声明该控件。以下标记执行下列任务:You can also use the chrome control in a declarative way. In the following code example, the HTML markup declares the control without using JavaScript code to configure and initialize the control. The following markup performs the following tasks:

    • 为 SP.UI.Controls.js JavaScript 文件提供一个占位符。Provides a placeholder for the SP.UI.Controls.js JavaScript file.

    • 动态加载 SP.UI.Controls.js 文件。Dynamically loads the SP.UI.Controls.js file.

    • 提供用于部件版式控制的占位符并指定内联 HTML 标记的选项。Provides a placeholder for the chrome control and specifies the options inline with the HTML markup.

       <!DOCTYPE html>
     <html xmlns="http://www.w3.org/1999/xhtml">
     <head>
         <title>Chrome control host page</title>
         <script 
             src="http://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js" 
             type="text/javascript">
         </script>
         <script 
             type="text/javascript" 
             src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
         </script>      
         <script type="text/javascript">
         var hostweburl;
    
         // Load the SharePoint resources.
         $(document).ready(function () {
    
             // Get the URI decoded add-in web URL.
             hostweburl =
                 decodeURIComponent(
                     getQueryStringParameter("SPHostUrl")
             );
    
             // The SharePoint js files URL are in the form:
             // web_url/_layouts/15/resource.js
             var scriptbase = hostweburl + "/_layouts/15/";
    
             // Load the js file and continue to the 
             // success handler.
             $.getScript(scriptbase + "SP.UI.Controls.js")
         });
    
         // 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>
     </head>
     <body>
    
         <!-- Chrome control placeholder 
                Options are declared inline.  -->
         <div 
             id="chrome_ctrl_container"
             data-ms-control="SP.UI.Controls.Navigation"  
             data-ms-options=
                 '{  
                     "appHelpPageUrl" : "Help.html",
                     "appIconUrl" : "siteIcon.png",
                     "appTitle" : "Chrome control add-in",
                     "settingsLinks" : [
                         {
                             "linkUrl" : "Account.html",
                             "displayName" : "Account settings"
                         },
                         {
                             "linkUrl" : "Contact.html",
                             "displayName" : "Contact us"
                         }
                     ]
                  }'>
         </div>
    
         <!-- The chrome control also makes the SharePoint
               Website style sheet available to your page. -->
         <h1 class="ms-accentText">Main content</h1>
         <h2 class="ms-accentText">The chrome control</h2>
         <div id="MainContent">
             This is the page's main content. 
             You can use the links in the header to go to the help, 
             account or contact pages.
         </div>
     </body>
     </html>
    

    SP.UI.Controls.js 库将自动呈现该控件,前提是它在 div 元素中发现 data-ms-control="SP.UI.Controls.Navigation" 属性。The SP.UI.Controls.js library automatically renders the control if it finds the data-ms-control="SP.UI.Controls.Navigation" attribute in a div element.

编辑外接程序清单中的 StartPage 元素To edit the StartPage element in the add-in manifest

  1. 在“解决方案资源管理器”**** 中,双击“AppManifest.xml”**** 文件。Double-click the AppManifest.xml file in Solution Explorer.

  2. 在“起始页”**** 下拉菜单上,选择使用部件版式控制的网页。On the Start page drop-down menu, select the webpage that uses the chrome control.

生成并运行解决方案的具体步骤To build and run the solution

  1. 确保已将 SharePoint 加载项项目设置为启动项目。Make sure that the SharePoint Add-in project is set as the startup project.

  2. 按 F5 键。Select the F5 key. (请注意,按 F5 键时,Visual Studio 会生成解决方案并部署加载项,同时还会打开加载项的权限页面。)(Note that when you select F5, Visual Studio builds the solution, deploys the add-in, and opens the permissions page for the add-in.)

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

  4. 选择“ChromeControlCloudhosted”**** 加载项图标。Select the ChromeControlCloudhosted add-in icon.

  5. 在网页中使用部件版式控制时,还可以使用 SharePoint 网站样式表,如下图中所示。When you use the chrome control in your webpages, you can also use the SharePoint website style sheet, as shown in the following figure.

    页面中使用的 SharePoint 网站样式表SharePoint website style sheet used in the page

    页面中使用的 SharePoint 网站样式表


解决方案疑难解答Troubleshooting the solution

问题Problem 解决方案Solution
发生未处理异常“SP 未定义”****。Unhandled exception SP is undefined. 请确保浏览器可以加载 SP.UI.Controls.js 文件。Make sure your browser loads the SP.UI.Controls.js file.
部件版式控制没有正确呈现。The chrome control does not render properly. 部件版式控制仅支持文档模式 Internet Explorer 8 及更高版本。The chrome control only supports document modes Internet Explorer 8 and later. 请确保浏览器以文档模式 Internet Explorer 8 或更高版本呈现页面。Make sure your browser renders your page in document mode Internet Explorer 8 or later.
证书错误。Certificate error. 将 Web 项目的“已启用 SSL”**** 属性设置为“false”****。在 SharePoint 加载项项目中,将“Web 项目”**** 属性设置为“无”****,然后将该属性设置回 Web 项目的名称。Set the SSL Enabled property of your web project to false. In the SharePoint Add-in project, set the Web Project property to None, and then set the property back to your web project's name.

另请参阅See also