Créer des composants de complément à installer avec votre complément pour SharePoint
With add-in parts, you can show your add-in user experience right in the SharePoint website pages. An add-in part displays the webpage (which is typically an interactive form or a dynamic display of data) that you specify by using an IFrame (also referred to as a frame) in a page in the host web.
Pour en savoir plus sur les composants de complément, consultez les articles suivants :
- Accéder au complément à partir de l'interface utilisateur
- Conception de l'expérience utilisateur pour les compléments dans SharePoint
- Extension de l’interface SharePoint dans les compléments
La figure suivante illustre la manière dont le composant de complément est affiché dans une page SharePoint.
Contenu de composant de complément affiché dans une page SharePoint

An add-in part is implemented with the ClientWebPart class, and like all web parts it is a available in the Web Part Gallery after a user installs the SharePoint Add-in that includes it. Your users can further customize the add-in part by using the properties that you provide. (For an example of configurable properties in an add-in part, see the figure SharePoint page hosting a basic add-in part later in this article.)
L’exemple de cet article utilise une page web hébergée sur un serveur distant, et non sur SharePoint, en tant que page de contenu. N’oubliez pas que vous pouvez également utiliser des pages SharePoint pour héberger le contenu du composant de module de recherche, comme décrit dans la section Autres scénarios courants des composants de composants de SharePoint plus loin dans cet article.
Conditions requises pour utiliser l’exemple de cet article
Pour suivre les étapes de cet exemple, vous avez besoin des éléments suivants :
- Visual Studio
- Outils de développement Microsoft Office pour Visual Studio
- A SharePoint development environment. If you need help setting up a development environment, see Two types of SharePoint Add-ins: SharePoint-hosted and provider-hosted.
Créer un composant de complément à installer sur le site web hôte
Plusieurs tâches sont à réaliser pour créer et installer votre composant de complément sur le site web hôte :
- Créer les projets de Complément SharePoint et de site web distant.
- Ajouter un formulaire pour le contenu du composant de complément.
- Ajouter le composant de complément au projet de Complément SharePoint.
After completing the tasks, your add-in part should look similar to the following figure when the add-in part is in edit mode. Here we can see (1) the add-in content displayed in a SharePoint page, and (2) the add-in part custom properties.
Page SharePoint hébergeant un composant de complément de base

Ajouter un formulaire pour le contenu du composant de complément
Créez un complément SharePoint hébergé par un fournisseur, en suivant les étapes décrites dans l’article Commencer à créer des compléments hébergés par un fournisseur pour SharePoint, mais nommez le projet TestAppPart.
After the Visual Studio solution has been created, right-click the web application project (not the SharePoint Add-in project) and add a new Web Form by selecting Add > New Item > Web > Web Form. Name the form AppPartContent.aspx.
In the AppPartContent.aspx file, replace the entire HTML element and its children with the following HTML code. Leave all the markup above the HTML element as it is. The HTML code contains JavaScript that performs the following tasks:
- Il extrait les valeurs des propriétés par défaut de la chaîne de requête.
- Il affiche les valeurs des propriétés
Notez que le code attend certains paramètres dans la chaîne de requête. Le composant de complément fournit ses propriétés personnalisées via la chaîne de requête, afin que la page web puisse les utiliser. La tâche suivante explique comment déclarer des propriétés personnalisées et les rendre disponibles pour la page web du complément.
<html> <body> <div id="content"> <!-- Placeholders for properties --> String property: <span id="strProp"></span><br /> Integer property: <span id="intProp"></span><br /> Boolean property: <span id="boolProp"></span><br /> Enumeration property: <span id="enumProp"></span><br /> </div> <!-- Main JavaScript function, controls the rendering logic based on the custom property values --> <script lang="javascript"> "use strict"; var params = document.URL.split("?")[1].split("&"); var strProp; var intProp; var boolProp; var enumProp; // Extracts the property values from the query string. for (var i = 0; i < params.length; i = i + 1) { var param = params[i].split("="); if (param[0] == "strProp") strProp = decodeURIComponent(param[1]); else if (param[0] == "intProp") intProp = parseInt(param[1]); else if (param[0] == "boolProp") boolProp = (param[1] == "true"); else if (param[0] == "enumProp") enumProp = decodeURIComponent(param[1]); } document.getElementById("strProp").innerText = strProp; document.getElementById("intProp").innerText = intProp; document.getElementById("boolProp").innerText = boolProp; document.getElementById("enumProp").innerText = enumProp; </script> </body> </html>Enregistrez et fermez le fichier.
Ajouter le composant de complément au projet de complément SharePoint
Right-click the SharePoint Add-in project (not the web application project), and then select Add > New Item > Office/SharePoint > Client web part (Host Web). ("Client web part" is another name for "add-in part".)
Nommez le composant Composant de complément de base.
In the Specify the client web part page dialog box, select Select or enter a URL for an existing webpage. Select the TestAppWebPart/AppPartContent.aspx page in the drop-down list. (After you've made your choice, the page URL may appear in the box with "TestAppWebPart" replaced by ~remoteAppUrl and with {StandardTokens } added for the query parameters.)
Sélectionnez Terminer.
Cliquez avec le bouton droit de la souris sur Composant de complément de base dans l’Explorateur de solutions, puis sélectionnez Propriétés.
Dans le volet Propriétés, sélectionnez Propriétés personnalisées, puis sélectionnez le bouton de légende (...).
À partir de la boîte de dialogue Propriétés personnalisées, ajoutez quatre propriétés personnalisées au composant de complément. Vous devez définir cinq attributs de chacune des quatre propriétés personnalisées. Les noms et les valeurs des attributs sont répertoriés dans le tableau 1. Pour créer les propriétés, suivez la procédure ci-dessous :
Cliquez sur Ajouter.
Dans la liste des attributs, sélectionnez le premier attribut de la table 1 : DefaultValue (Valeur par défaut).
Définissez la valeur, par exemple Valeur de chaîne par défaut.
Sélectionnez l'attribut suivant, Name et définissez sa valeur, par exemplestrProp.
Continuez avec les attributs Type, WebCategory et WebDisplayName.
Select Add again and repeat the process for all four rows of Table 1. Do not close the dialog box.
Tableau 1. Attributs des propriétés personnalisées du composant de complément
DefaultValue Nom Type WebCategory WebDisplayName Valeur par défaut de la chaîne strProp string Catégorie de composant de complément de base Propriété de type chaîne 0 intProp int Catégorie de composant de complément de base Propriété de type entier false boolProp boolean Catégorie de composant de complément de base Propriété de type booléen 1st enumProp enum Catégorie de composant de complément de base Propriété de type énumération À ce stade, la boîte de dialogue doit avoir l'aspect suivant :
Boîte de dialogue Propriétés personnalisées pour un composant WebPart client

Sélectionnez la propriété enumProp, l’attribut EnumItems, puis le bouton de légende (...).
Utilisez l' éditeur de collections ClientWebPartEnumItem pour ajouter trois éléments. Vous devez définir deux attributs de chacun d'entre eux. Les noms et les valeurs des attributs sont répertoriés dans le tableau 1. Pour créer les propriétés, suivez la procédure ci-dessous :
Cliquez sur Ajouter.
Dans la liste des attributs, sélectionnez le premier attribut de la table 2 : Value.
Définissez la valeur de l'attribut, par exemple, 1st.
Sélectionnez l'attribut suivant, WebDisplayName et définissez sa valeur, par exemple Première option.
Sélectionnez de nouveau Ajouter et répétez le processus pour toutes les lignes du Tableau 2.
Tableau 2. Éléments enum de la propriété enumProp
Valeur WebDisplayName 1st Première option 2nd Deuxième option 3rd Troisième option La boîte de dialogue doit avoir l'aspect suivant lorsque vous avez terminé :
Éditeur de collections ClientWebPartEnumItem

Sélectionnez OK pour fermer la boîte de dialogue, puis sélectionnez une nouvelle fois OK pour fermer la boîte de dialogue Propriétés personnalisées.
Visual Studio generates the following XML code in the elements.xml file of the add-in part (line breaks added for clarity). Note that the Title attribute of the ClientWebPart element is set to "Basic add-in part Title" and the Description is set to "Basic add-in part Description". Delete the word "Title" from the first, and replace the second with a Basic add-in part.
<?xml version="1.0" encoding="UTF-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<ClientWebPart
Name="Basic add-in part"
Title="Basic add-in part Title"
Description="Basic add-in part Description" >
<!-- The properties are passed through the query string
using the following notation: _propertyName_
in the Src property of the Content element.
-->
<Content
Src="~remoteAppUrl/AppPartContent.aspx?strProp=_strProp_&amp;intProp=_intProp_&amp;boolProp=_boolProp_&amp;enumProp=_enumProp_"
Type="html"/>
<Properties>
<Property
Name="strProp"
Type="string"
RequiresDesignerPermission="true"
DefaultValue="String default value"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type string.">
</Property>
<Property
Name="intProp"
Type="int"
RequiresDesignerPermission="true"
DefaultValue="0"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type integer.">
</Property>
<Property
Name="boolProp"
Type="boolean"
RequiresDesignerPermission="true"
DefaultValue="false"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type boolean.">
</Property>
<Property
Name="enumProp"
Type="enum"
RequiresDesignerPermission="true"
DefaultValue="1st"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type enum.">
<EnumItems>
<EnumItem WebDisplayName="First option" Value="1st"/>
<EnumItem WebDisplayName="Second option" Value="2nd"/>
<EnumItem WebDisplayName="Third option" Value="3rd"/>
</EnumItems>
</Property>
</Properties>
</ClientWebPart>
</Elements>
Définir la page de démarrage du complément sur la page d’accueil du site web hôte
The continuing sample SharePoint Add-in doesn't have any add-in web, and its remote web application exists only to host the form. There isn't any full page, immersive experience for this add-in. So the start page of the add-in should be set to the home page of the host web.
Pour commencer, sélectionnez le projet de complément SharePoint (et non le projet d’application web) dans l’Explorateur de solutions et copiez la valeur de la propriété URL du site, avec son protocole (par exemple https://contoso.sharepoint.com) dans le Presse-papiers.
Ouvrez le manifeste du complément, puis collez l'URL dans la zone Page de démarrage.
Vous pouvez également supprimer la page Default.aspx du projet d’application web, car elle n’est pas utilisée dans le complément SharePoint.
Créer et tester la solution
Sélectionnez la touche F5.
Notes
Quand vous sélectionnez F5, Visual Studio génère la solution, installe le complément et ouvre la page des autorisations pour le complément.
Sélectionnez le bouton Approuver.
Ajoutez le composant de complément de base à partir de la galerie de composants de complément. Pour obtenir des instructions détaillées, reportez-vous à Ajouter un composant de complément à une page.
When the add-in is installed on the host web, the Basic add-in part is available in the Add-in Part gallery. It should look a lot like the following figure.
Composant de complément dans la galerie de composants de compléments

Une fois le composant de complément ajouté, sélectionnez la flèche vers le bas située à droite du titre Composant de complément de base, puis sélectionnez Modifier le composant WebPart.
Le composant de complément doit apparaître en mode Édition.
Ouvrez Catégorie de composant de complément de base et modifiez certaines valeurs de propriétés.
Sélectionnez OK pour enregistrer les modifications et vérifiez que les propriétés ont changé dans le composant de complément.
When you end the debugging session, and you won't be using F5 again on this project for a while, it is a good practice to retract the SharePoint Add-in one last time to ensure that the test add-in part is removed from your home page. Right-click the SharePoint Add-in project and select Retract.
Dépannage de la solution
| Problème | Solution |
|---|---|
| Le composant de complément n’affiche pas de contenu, mais l’erreur suivante : Navigation vers la page web annulée. Cette erreur se produit car le navigateur a bloqué la page de contenu. | Enable mixed content. The procedure might be different depending on the browser you are using: Internet Explorer 9 and 10 display the following message at the bottom of the page: Only secure content is displayed. Select Show all content to display the add-in part content. Internet Explorer 8 shows a dialog box with the following message: Do you want to view only the webpage content that was delivered securely? Select No to display the add-in part content. Sinon, vous pouvez activer le contenu mixte dans la zone Internet dans laquelle vous travaillez. Pour la plupart des développeurs, cette zone Internet est un intranet local. Si ce n’est pas le cas pour vous, remplacez Intranet local par la zone Internet dans laquelle vous travaillez. In Internet Explorer, select Tools > Internet Options. In the Internet Options dialog box, on the Security tab, select Local intranet, and then select the Custom level button. In the Security Settings dialog box, enable Display mixed content in the Miscellaneous section. |
Autres scénarios courants utilisant des composants de complément
Cet article montre comment créer un composant de complément de base avec des propriétés personnalisées à l’aide d’une page web distante en tant que page de contenu. Vous pouvez également explorer les scénarios et détails suivants concernant les composants de complément.
Utiliser une page SharePoint en tant que page de contenu
In most cases, a webpage can't be displayed in a frame if it sends an X-Frame-Options HTTP header in the response. By default, SharePoint pages include the X-Frame-Options header. If you are using a SharePoint webpage hosted on the add-in web, you might run into the following error (shown in the following figure): This content cannot be displayed in a frame.
Composant de complément ne pouvant pas afficher son contenu dans un cadre

Be aware that certain scenarios are susceptible to ClickJacking attacks when the webpages are displayed in a frame. Carefully evaluate your add-in part scenarios to make sure there is no risk of ClickJacking attacks.
If your page hosted on the add-in web is not susceptible to ClickJacking attacks, you can use the AllowFraming web part to suppress the X-Frame-Options header from your page's response. The following code example shows how to use the AllowFraming web part on a SharePoint page. Copy this markup into the page that is hosted on the add-in web. Put it just above the first asp:content element in the page. It should not be a child of any other element.
<WebPartPages:AllowFraming ID="AllowFraming1" runat="server" />
Pour savoir comment utiliser une page SharePoint comme page de contenu, vous pouvez télécharger un exemple de code de composant de complément destiné à afficher le contenu du site web de complément sur le site web hôte à l’aide d’un composant de complément.
Redimensionner le composant de complément
Si vous utilisez du contenu dynamique dans votre composant de complément, il est possible que la largeur et la hauteur du contenu soient modifiées. En raison de la nature dynamique du contenu, celui-ci peut ne pas être adapté au cadre. Il se peut également que vous utilisiez trop d'espace. Avec le contenu dynamique, il peut s'avérer difficile de spécifier une taille fixe dans la déclaration du composant de complément, mais vous pouvez redimensionner le cadre pour qu'il s'adapte à la largeur et à la hauteur du contenu.
You can use POST messages from your content webpage to specify the frame's size. The following JavaScript example shows you how to send a POST message to resize the frame in which your add-in part is hosted. Typically, you would have this in a JavaScript method in a JavaScript file that you call from the page. For example, the page could have a control in which the user specifies the size of the add-in part window. The custom method is then called from onchange handler of the control.
Pour obtenir un exemple complet de composant de complément qui redimensionne dynamiquement les composants, consultez l’exemple de code : redimensionner les composants de complément de façon dynamique dans les compléments SharePoint.
window.parent.postMessage("<message senderId={SenderId}>resize(120, 300)</message>", {hostweburl});
In the example above, the senderId value is set on the query string of the page automatically by the add-in part code when the page is rendered. Your page would just need to read the SenderId value off of the query string and use it when requesting a resize. You can retrieve the host web URL from the query string by appending the StandardTokens or HostUrl tokens to the Src attribute in your add-in part definition.
Utiliser la feuille de style SharePoint dans le contenu de votre composant de complément
Because your add-in part is hosted within a SharePoint page, you might want to make the add-in part content look like it is part of the page. One way to achieve a similar look and feel is to use the same style classes as the SharePoint page that is hosting the add-in part. You can make the SharePoint website's style sheet available to the add-in part by adding a reference to the defaultcss.ashx file from the add-in web.
Pour savoir comment référencer le fichier defaultcss.ashx dans vos compléments SharePoint, consultez l’article Utilisation d’une feuille de style de site web SharePoint dans les compléments SharePoint.
Pour obtenir un composant de complément qui référence la feuille de style, téléchargez l’exemple de code : afficher le contenu d’une page web distante à l’aide du composant de complément cafetière.
Détecter le passage en mode d’édition du composant de complément
Users can edit the add-in part to change its properties. For example, a user might want to change one of the add-in part's Appearance or Layout properties. If your add-in part is in edit mode, you might want to modify the rendering logic or prevent some unnecessary processing from happening. Consider, for example, an add-in part that calls a backend database whenever the host page reloads. Changing an add-in part property value in edit mode causes a page reload, but you might not want the network call to be triggered in that case. You can use the editMode token to detect if users are editing your add-in part.
Pour utiliser le jeton editMode, ajoutez un paramètre de chaîne de requête à l’attribut Src de l’élément Content dans la déclaration du composant de complément.
<Content Src="content_page_url&amp;editmode=_editMode_">
Le jeton editMode permet à votre page de contenu de déterminer si le composant de complément est en mode d'édition. Si tel est le cas, le jeton editMode est résolu en 1 ; sinon, il est résolu en 0.