Utiliser le contrôle Chrome client dans les compléments pour SharePointUse the client chrome control in SharePoint Add-ins

Le contrôle Chrome dans SharePoint vous permet d'utiliser les styles d'en-tête d'un site SharePoint spécifique dans votre complément sans avoir à inscrire dans le Registre une bibliothèque de serveur ou utiliser une technologie ou un outil spécifique. Pour utiliser cette fonctionnalité, vous devez inscrire dans le Registre une bibliothèque JavaScript SharePoint par le biais d'une balise <script> standard. Vous pouvez fournir un espace réservé au moyen d'un élément HTML div et personnaliser davantage le contrôle au moyen des options disponibles. Le contrôle hérite de son aspect à partir du site web SharePoint spécifié. 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.

Conditions préalables à l’utilisation des exemples de cet articlePrerequisites for using the examples in this article

Pour suivre les étapes de cet exemple, vous avez besoin des éléments suivants :To follow the steps in this example, you need the following:

  • Visual Studio 2015Visual Studio 2015
  • Un environnement de développement SharePoint (isolation de complément requise pour les scénarios locaux)A SharePoint development environment (add-in isolation required for on-premises scenarios)

Pour savoir comment configurer un environnement de développement adapté à vos besoins, consultez la section relative aux deux types de compléments SharePoint.Note For guidance about how to set up a development environment that fits your needs, see Start building Office and SharePoint Add-ins.

Concepts clés à connaître avant d’utiliser le contrôle ChromeCore concepts to know before using the chrome control

Le tableau suivant indique les articles utiles pouvant vous aider à comprendre les concepts figurant dans un scénario utilisant le contrôle Chrome.The following table lists useful articles that can help you understand the concepts involved in a scenario that uses the chrome control.

Titre d’articleArticle title DescriptionDescription
ComplémentsSharePoint Add-ins Découvrez le nouveau modèle de complément de SharePoint qui permet de créer des compléments, c’est-à-dire de petites solutions simples d’utilisation pour les utilisateurs finaux.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.
Conception de l’expérience utilisateur pour les compléments SharePointUX design for SharePoint Add-ins Découvrez les options d’expérience utilisateur (UX) et les solutions à votre disposition lorsque vous créez des compléments SharePoint.Learn about the user experience (UX) options and alternatives that you have when building SharePoint Add-ins.
Héberger des sites web, des sites web de complément et des composants SharePoint dans SharePointHost webs, add-in webs, and SharePoint components in SharePoint Découvrez la différence entre les sites web hôtes et les sites web de complément. Découvrez les composants SharePoint pouvant être inclus dans un Complément SharePoint, les composants déployés sur le site web hôte, les composants déployés sur le site web de complément et la façon dont le site web de complément est déployé dans un domaine isolé.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.

Exemple de code : utiliser le contrôle Chrome dans votre complément hébergé par le cloudCode example: Use the chrome control in your cloud-hosted add-in

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: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. Créez les projets de Complément SharePoint et de site web distant.Create the SharePoint Add-in and remote web projects.
  2. Envoyez les options de configuration par défaut dans la chaîne de requête.Send default configuration options in the query string.
  3. Ajoutez une page web au projet web.Add a webpage to the web project.

La figure suivante montre une page web distante avec le contrôle Chrome.Figure 1 shows a remote webpage with the chrome control.

Page web distante avec le contrôle ChromeFigure 1. Remote webpage with the chrome control

Page web distante avec le contrôle Chrome


Création du complément SharePoint et de projets web distantsTo create the SharePoint Add-in and remote web projects

  1. 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.)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. Créez un projet à l’aide du modèle Complément SharePoint.Create a new project by using the SharePoint Add-in template.

    La figure suivante montre l’emplacement du modèle Complément SharePoint dans Visual Studio 2015, sous Modèles > Visual C# > Office/SharePoint > Compléments Office.Figure 2 shows the location of the SharePoint Add-in template in Visual Studio 2015, under Templates > Visual C# > Office/SharePoint > Office Add-ins.

    Modèle de complément SharePoint dans Visual StudioFigure 2. SharePoint Add-in Visual Studio template

    Modèle d’application pour SharePoint de Visual Studio


  3. Indiquez l’URL du site web SharePoint que vous souhaitez utiliser pour le débogage.Provide the URL of the SharePoint website that you want to use for debugging.

  4. Sélectionnez Hébergement par le fournisseur comme option d'hébergement pour votre complément. Pour obtenir un exemple de code hébergé sur SharePoint, voir SharePoint-Add-in-JSOM-BasicDataOperations.Select Provider-hosted as the hosting option for your add-in. For a SharePoint-hosted code sample, see SharePoint-Add-in-JSOM-BasicDataOperations.

    À la fin de l’Assistant, votre structure dans l’Explorateur de solutions doit ressembler à celle illustrée dans la figure suivante.After the wizard finishes, you should have a structure in Solution Explorer that resembles Figure 3.

    Projets de complément SharePoint dans l’Explorateur de solutionsFigure 3. Add-in for SharePoint projects in Solution Explorer

    Projets d’application pour SharePoint dans l’Explorateur de solutions


Pour envoyer les options de configuration par défaut dans la chaîne de requêteTo send default configuration options in the query string

  1. Ouvrez le fichier Appmanifest.xml dans l’éditeur de manifeste.Open the Appmanifest.xml file in the manifest editor.

  2. 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.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.

    Éditeur de manifeste avec les paramètres de chaîne de requête pour le contrôle ChromeFigure 4. Manifest editor with query string parameters for the chrome control

    Éditeur de manifeste avec paramètres de chaîne de requête


    Le contrôle Chrome prend automatiquement les valeurs suivantes dans la chaîne de requête :The chrome control automatically takes the following values from the query string:

    • SPHostUrlSPHostUrl
    • SPHostTitleSPHostTitle
    • SPAppWebUrlSPAppWebUrl
    • SPLanguageSPLanguage

    **{StandardTokens} ** comprend SPHostUrl et SPAppWebUrl.{StandardTokens} include SPHostUrl and SPAppWebUrl.

Pour ajouter une page utilisant le contrôle Chrome dans le projet webTo add a page that uses the chrome control in the web project

  1. Cliquez avec le bouton droit sur le projet web et ajoutez un nouveau formulaire web.Right-click the web project, and add a new Web Form.

  2. Copiez le balisage suivant et collez-le dans la page ASPX. Le balisage effectue les tâches suivantes :Copy the following markup, and paste it in the ASPX page. The markup performs the following tasks:

    • Charge la bibliothèque AJAX à partir du réseau de distribution de contenu Microsoft (CDN).Loads the AJAX library from the Microsoft CDN (Content Delivery Network).

    • Charge la bibliothèque jQuery à partir du réseau de distribution de contenu Microsoft.Loads the jQuery library from the Microsoft CDN.

    • Charge le fichier SP.UI.Controls.js au moyen de la fonction jQuery getScript.Loads the SP.UI.Controls.js file using the jQuery function getScript.

    • Définit une fonction de rappel pour l'événement onCssLoaded.Defines a callback function for the onCssLoaded event.

    • Prépare les options pour le contrôle Chrome.Prepares the options for the chrome control.

    • Initialise le contrôle Chrome.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. Vous pouvez également utiliser le contrôle Chrome de façon déclarative. Dans l'exemple de code suivant, le code HTML déclare le contrôle sans utiliser de code JavaScript pour configurer et initialiser le contrôle. Le code effectue les tâches suivantes :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:

    • Fournit un espace réservé pour le fichier SP.UI.Controls.js JavaScript.Provides a placeholder for the SP.UI.Controls.js JavaScript file.

    • Charge de façon dynamique le fichier SP.UI.Controls.js.Dynamically loads the SP.UI.Controls.js file.

    • Fournit un espace réservé pour le contrôle Chrome et spécifie les options en les incorporant dans le code 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>
    

    La bibliothèque SP.UI.Controls.js effectue automatiquement un rendu du contrôle si elle trouve l'attribut data-ms-control="SP.UI.Controls.Navigation" dans un élément div.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.

Pour modifier l’élément StartPage dans le manifeste du complémentTo edit the StartPage element in the add-in manifest

  1. Double-cliquez sur le fichier AppManifest.xml dans l' Explorateur de solutions.Double-click the AppManifest.xml file in Solution Explorer.

  2. Dans le menu déroulant Page de démarrage, sélectionnez la page web qui utilise le contrôle Chrome.On the Start page drop-down menu, select the webpage that uses the chrome control.

Pour créer et exécuter la solutionTo build and run the solution

  1. Vérifiez que le projet de Complément SharePoint est défini en tant que projet de démarrage.Make sure that the SharePoint Add-in project is set as the startup project.

  2. Select the F5 key. (Note that when you select F5, Visual Studio builds the solution, deploys the add-in, and opens the permissions page for the add-in.)Select the F5 key. (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. Sélectionnez le bouton Approuver.Select the Trust It button.

  4. Sélectionnez l’icône de complément ChromeControlCloudhosted.Select the ChromeControlCloudhosted add-in icon.

  5. Quand vous utilisez le contrôle Chrome dans vos pages web, vous pouvez également utiliser la feuille de style du site web SharePoint, comme illustré dans la figure suivante.When you use the chrome control in your webpages, you can also use the SharePoint website style sheet, as shown in Figure 5.

    Feuille de style de site web SharePoint utilisée dans la pageFigure 5. SharePoint website style sheet used in the page

    Feuille de style de site web SharePoint utilisée dans une page


Dépannage de la solutionTroubleshooting the solution

ProblèmeProblem SolutionSolution
Exception non gérée SP n'est pas défini.Unhandled exception SP is undefined. Vérifiez que votre navigateur charge le fichier SP.UI.Controls.js.Make sure your browser loads the SP.UI.Controls.js file.
Le contrôle Chrome ne s’affiche pas correctement.The chrome control does not render properly. The chrome control only supports document modes Internet Explorer 8 and later. Make sure your browser renders your page in document mode Internet Explorer 8 or later.The chrome control only supports document modes Internet Explorer 8 and later. Make sure your browser renders your page in document mode Internet Explorer 8 or later.
Erreur de certificat.Certificate error. Définissez la propriété SSL activé de votre projet web sur False. Dans le projet Complément SharePoint, définissez la propriété Projet web sur None, puis redéfinissez la propriété conformément au nom de votre projet 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.

Voir aussiSee also