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


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

Элемент управления хрома в SharePoint позволяет использовать стиль заголовка определенного сайта SharePoint в надстройке, не регистрируя серверную библиотеку и не применяя специальные технологии или средства. Чтобы использовать эту функцию, необходимо зарегистрировать библиотеку JavaScript SharePoint с помощью стандартного <script> тега. Вы можете указать заполнитель с помощью HTML-элемента div, а затем настроить этот элемент управления, используя доступные параметры. Этот элемент управления наследует внешний вид от указанного веб-сайта SharePoint.

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

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

  • Visual Studio 2015.
  • среда разработки SharePoint (для локальных сценариев необходимо изолировать надстройку).

Инструкции по настройке подходящей вам среды разработки см. в разделе Два типа надстроек SharePoint (с размещением в SharePoint и у поставщика).

Ключевые понятия, с которыми необходимо ознакомиться перед использованием элемента управления хрома

Ниже перечислены полезные статьи, в которых описано, как использовать элемент управления хрома.

Название статьи Описание
Надстройки SharePoint Сведения о новой модели надстроек в SharePoint, с помощью которой можно создавать надстройки — небольшие и удобные в использовании решения для пользователей.
Разработка пользовательского интерфейса для надстроек SharePoint Сведения о параметрах и вариантах построения пользовательского интерфейса при создании надстроек SharePoint.
Хост-сайты, сайты надстроек и компоненты SharePoint в SharePoint Узнайте, в чем разница между хост-сайтами и сайтами надстроек. Узнайте, какие компоненты SharePoint можно включать в надстройку SharePoint, какие компоненты развертываются на хост-сайте, а какие на сайте надстройки и как развертывается сайт надстройки в изолированном домене.

Пример кода. Использование элемента управления хрома в надстройке, размещенной в облаке

Размещенная в облаке надстройка включает по крайней мере один удаленный компонент. Дополнительные сведения см. в статье Выбор шаблонов для разработки и размещения надстройки SharePoint. Чтобы использовать элемент управления хрома в надстройке, размещенной в облаке, сделайте вот что:

  1. Создайте надстройку SharePoint и удаленные веб-проекты.
  2. Отправьте параметры конфигурации по умолчанию в строке запроса.
  3. Добавьте в веб-проект веб-страницу.

На следующем рисунке показана удаленная веб-страница с элементом управления хрома.

Удаленная веб-страница с элементом управления хрома

Удаленная веб-страница с элементом управления хрома


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

  1. Откройте Visual Studio 2015 от имени администратора. Для этого щелкните правой кнопкой мыши значок Visual Studio 2015 в меню Пуск и выберите Запуск от имени администратора.

  2. Создайте проект, используя шаблон Надстройка SharePoint.

    На следующем рисунке показано расположение шаблона Надстройка SharePoint в Visual Studio 2015: Шаблоны>Visual C#>Office/SharePoint>Надстройки Office.

    Шаблон надстройки SharePoint в Visual Studio

    Шаблон приложения для SharePoint в Visual Studio


  3. Укажите URL-адрес веб-сайта SharePoint, который планируется использовать для отладки.

  4. Выберите Размещено у поставщика в качестве варианта размещения надстройки. Пример кода с размещением в SharePoint: SharePoint-Add-in-JSOM-BasicDataOperations.

    Когда мастер завершит работу, структура в обозревателе решений будет напоминать структуру, показанную на следующем рисунке.

    Проекты "Надстройка для SharePoint" в обозревателе решений

    Проекты


Отправка параметров конфигурации по умолчанию в строке запроса

  1. Откройте файл Appmanifest.xml в редакторе манифеста.

  2. Добавьте в строку запроса маркер {StandardTokens} и дополнительный параметр SPHostTitle. На следующем рисунке показан редактор манифеста с настроенными параметрами строки запроса.

    Редактор манифеста с параметрами строки запроса для элемента управления хрома

    Редактор манифеста с параметрами строки запроса


    Элемент управления хрома автоматически принимает из строки запроса следующие значения:

    • SPHostUrl;
    • SPHostTitle;
    • SPAppWebUrl;
    • SPLanguage.

    Маркер {StandardTokens} включает маркеры SPHostUrl и SPAppWebUrl.

Добавление в веб-проект страницы с элементом управления хрома

  1. Щелкните правой кнопкой мыши веб-проект и добавьте новую веб-форму.

  2. Скопируйте следующие исправления и вставьте их на страницу ASPX. Исправления выполняют следующие действия:

    • загружает библиотеку AJAX из сети доставки содержимого Майкрософт (CDN);

    • Загружает библиотеку jQuery из сети CDN Майкрософт.

    • загружает файл SP.UI.Controls.js с помощью функции jQuery getScript;

    • определяет функцию обратного вызова для события onCssLoaded;

    • подготавливает параметры для элемента управления хрома;

    • инициализирует элемент управления хрома.

       <!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 для его настройки и инициализации. Эта разметка выполняет следующие задачи:

    • предоставляет заполнитель для файла JavaScript SP.UI.Controls.js;

    • динамически загружает файл SP.UI.Controls.js;

    • предоставляет заполнитель для элемента управления хрома и задает его параметры (разметку HTML).

       <!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 автоматически отображает элемент управления, если обнаруживает атрибут data-ms-control="SP.UI.Controls.Navigation" в элементе div.

Изменение элемента StartPage в манифесте надстройки

  1. Дважды щелкните файл AppManifest.xml в обозревателе решений.

  2. В раскрывающемся меню Начальная страница выберите веб-страницу, на которой используется элемент управления хрома.

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

  1. Убедитесь, что проект надстройки SharePoint выбран как запускаемый проект.

  2. Нажмите клавишу F5. (Обратите внимание, что после нажатия клавиши F5 Visual Studio выполняет сборку решения, развертывает надстройку и открывает для нее страницу разрешений.)

  3. Нажмите кнопку Доверять.

  4. Выберите значок надстройки ChromeControlCloudhosted.

  5. При использовании элемента управления хрома на веб-страницах вы также можете использовать таблицу стилей веб-сайта SharePoint, как показано на следующем рисунке.

    Таблица стилей веб-сайта SharePoint на странице

    Таблица стилей веб-сайта SharePoint на странице


Устранение неполадок в решении

Проблема Решение
Необработанное исключение SP не определен. Убедитесь, что в браузере загружается файл SP.UI.Controls.js.
Элемент управления хрома не выполняет обработку должным образом. Элемент управления хрома поддерживает только режимы документов Internet Explorer 8 и более поздних версий. Убедитесь, что браузер отображает страницу в режиме документов Internet Explorer 8 или более поздних версий.
Ошибка сертификата. Установите для свойства SSL включен веб-проекта значение false. В проекте надстройки SharePoint задайте для свойства Веб-проект значение None (Нет), а затем снова укажите в нем имя веб-проекта.

См. также