Utilisation des espaces réservés de page du personnalisateur d’application (Hello World 2e partie)
Les personnalisateurs d’application permettent d’accéder à des emplacements connus sur des pages SharePoint que vous pouvez modifier en fonction de vos exigences professionnelles et fonctionnelles. Par exemple, vous pouvez créer des expériences d’en-tête et de pied de page dynamiques qui s’affichent sur toutes les pages dans SharePoint Online.
Ce modèle revient plu sou moins à utiliser une collection UserCustomAction dans un objet Site ou Web pour modifier l’expérience de page via JavaScript personnalisé. La principale différence entre les extensions SharePoint Framework (SPFx) est que les éléments de votre page ne changent pas si des modifications sont apportées à la structure HTML/DOM dans SharePoint Online.
Cet article explique comment étendre votre extension Hello World pour tirer parti des espaces réservés de page.
Vous pouvez également suivre cette procédure en regardant la vidéo sur la chaîne YouTube SharePoint PnP :
Accéder aux espaces réservés de page
Les extensions du personnaliste d’application sont pris en charge avec les étendues Site, Web et List. Vous pouvez contrôler l’étendue en décidant où et comment est enregistré le personnalisateur d’application dans votre client SharePoint.
Notes
L’inscription XML de fonctionnalité du personnalateur d’application est uniquement prise en charge avec le niveau web ou de liste. Vous pouvez toutefois activer le personnalateur d’application plus largement à l’aide du déploiement à l’échelle du client de la fonctionnalité d’extensions ou en associant le personnaliste d’application à la UserCustomAction collection sur Site l’objet.
Lorsque le personnalisateur d’application existe dans l’étendue et est affiché, vous pouvez utiliser la méthode suivante pour accéder à l’espace réservé.
// Handling the Bottom placeholder
if (!this._bottomPlaceholder) {
this._bottomPlaceholder =
this.context.placeholderProvider.tryCreateContent(
PlaceholderName.Bottom,
{ onDispose: this._onDispose });
...
}
Une fois que vous obtenez l’objet d’espace réservé, vous disposez d’un contrôle total sur ce que verra l’utilisateur final.
Vous remarquerez que vous demandez un espace réservé connu à l’aide de l’identificateur connu correspondant. Dans ce cas, le code accède à la section de pied de page à l’aide de Bottom l’option sur PlaceholderName l’enum.
Modification du personnalisateur d’application pour accéder à des espaces réservés et les modifier en ajoutant des éléments HTML personnalisés
Installez le package @ microsoft/sp-office-ui-fabric-core pour activer l’importation à partir de SPFabricCore.scss. Nous l’utiliserons pour définir des styles de rendu pour nos titulaires de lieu.
npm install @microsoft/sp-office-ui-fabric-coreCréez un fichier nommé ./src/extensions/helloWorld/AppCustomizer.module.scss.
Mettez à jour AppCustomizer.module.scss comme suit :
Notes
Voici les styles qui sont utilisés dans le code HTML créé pour les espaces réservés d’en-tête et de pied de page.
@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss'; .app { .top { height:60px; text-align:center; line-height:2.5; font-weight:bold; display: flex; align-items: center; justify-content: center; background-color: $ms-color-themePrimary; color: $ms-color-white; } .bottom { height:40px; text-align:center; line-height:2.5; font-weight:bold; display: flex; align-items: center; justify-content: center; background-color: $ms-color-themePrimary; color: $ms-color-white; } }Dans Visual Studio Code (ou votre IDE préféré), ouvrez ./src/extensions/helloWorld/HelloWorldApplicationCustomizer.ts.
Ajoutez
PlaceholderContentl’instruction import à partir dePlaceholderName@ microsoft/sp-application-base en mettant à jour l’instruction import comme suit :import { BaseApplicationCustomizer, PlaceholderContent, PlaceholderName } from '@microsoft/sp-application-base';Ajoutez également les instructions import suivantes après l’importation de
stringsen haut du fichier :import styles from './AppCustomizer.module.scss'; import { escape } from '@microsoft/sp-lodash-subset';Vous utiliserez la
escapefonction pour éviter les propriétés du personnalateur d’application. Vous allez créer des définitions de style pour la sortie dans les étapes suivantes.Notes
Après avoir passé l’extrait de code ci-dessus, une erreur peut s’Visual Studio Code. Ces erreurs disparaissent une fois que vous avez construit la solution lorsque le fichier scss est compilé dans une classe.
Dans le fichier HelloWorldApplicationCustomizer.ts, mettez à jour l’interface pour ajouter des propriétés spécifiques pour l’en-tête et le pied de
IHelloWorldApplicationCustomizerPropertiesliste, comme suit :Notes
Si votre personnaliste d’application utilise
ClientSideComponentPropertiesl’entrée JSON, elle est désérialisée dansBaseExtension.propertiesl’objet. Vous pouvez définir une interface pour le décrire.export interface IHelloWorldApplicationCustomizerProperties { Top: string; Bottom: string; }Ajoutez les variables privées suivantes à l’intérieur de
HelloWorldApplicationCustomizerla classe. Dans ce scénario, elles peuvent être uniquement des variables locales dans une méthodeonRender(), mais si vous souhaitez les partager avec d’autres objets, définissez-les comme variables privées.export default class HelloWorldApplicationCustomizer extends BaseApplicationCustomizer<IHelloWorldApplicationCustomizerProperties> { // These have been added private _topPlaceholder: PlaceholderContent | undefined; private _bottomPlaceholder: PlaceholderContent | undefined; // ... }Mettez à jour le code de la méthode
onInit()comme suit :@override public onInit(): Promise<void> { Log.info(LOG_SOURCE, `Initialized ${strings.Title}`); // Wait for the placeholders to be created (or handle them being changed) and then // render. this.context.placeholderProvider.changedEvent.add(this, this._renderPlaceHolders); return Promise.resolve<void>(); }Créez une méthode privée
_renderPlaceHolders()avec le code suivant :private _renderPlaceHolders(): void { console.log("HelloWorldApplicationCustomizer._renderPlaceHolders()"); console.log( "Available placeholders: ", this.context.placeholderProvider.placeholderNames .map(name => PlaceholderName[name]) .join(", ") ); // Handling the top placeholder if (!this._topPlaceholder) { this._topPlaceholder = this.context.placeholderProvider.tryCreateContent( PlaceholderName.Top, { onDispose: this._onDispose } ); // The extension should not assume that the expected placeholder is available. if (!this._topPlaceholder) { console.error("The expected placeholder (Top) was not found."); return; } if (this.properties) { let topString: string = this.properties.Top; if (!topString) { topString = "(Top property was not defined.)"; } if (this._topPlaceholder.domElement) { this._topPlaceholder.domElement.innerHTML = ` <div class="${styles.app}"> <div class="${styles.top}"> <i class="ms-Icon ms-Icon--Info" aria-hidden="true"></i> ${escape( topString )} </div> </div>`; } } } // Handling the bottom placeholder if (!this._bottomPlaceholder) { this._bottomPlaceholder = this.context.placeholderProvider.tryCreateContent( PlaceholderName.Bottom, { onDispose: this._onDispose } ); // The extension should not assume that the expected placeholder is available. if (!this._bottomPlaceholder) { console.error("The expected placeholder (Bottom) was not found."); return; } if (this.properties) { let bottomString: string = this.properties.Bottom; if (!bottomString) { bottomString = "(Bottom property was not defined.)"; } if (this._bottomPlaceholder.domElement) { this._bottomPlaceholder.domElement.innerHTML = ` <div class="${styles.app}"> <div class="${styles.bottom}"> <i class="ms-Icon ms-Icon--Info" aria-hidden="true"></i> ${escape( bottomString )} </div> </div>`; } } } }Tenez compte des informations suivantes :
- Utilisez
this.context.placeholderProvider.tryCreateContentpour accéder à l’espace réservé. - Le code d’extension ne doit pas supposer que l’espace réservé attendu est disponible.
- Le code attend des propriétés personnalisées appelées
TopetBottom. Si les propriétés existent, elles s’affichent dans les espaces réservés. - Les chemins d’accès du code pour les espaces réservés du haut et du bas sont presque identiques. Les seules différences sont les variables utilisées et les définitions de style.
- Il est possible d’utiliser directement les noms de classe définis dans la feuille de style, mais cela n’est pas recommandé. Si aucune référence de feuille de style définie dans la variable
stylesn’est trouvée dans le code, la feuille de style n’est pas ajoutée à la page. En effet, les références inutilisées sont supprimées pendant le processus de génération.
- Utilisez
Ajoutez la méthode suivante après la méthode
_renderPlaceHolders(). Dans ce cas, vous affichez simplement un message de console lorsque l’extension est supprimée de la page.private _onDispose(): void { console.log('[HelloWorldApplicationCustomizer._onDispose] Disposed custom top and bottom placeholders.'); }
Vous êtes maintenant prêt à tester votre code dans SharePoint Online.
Tester votre code
Dans le fichier ./config/serve.js, mettez à jour la section des propriétés du fichier pour qu’elle présente les messages Haut et Bas.
{ "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json", "port": 4321, "https": true, "serveConfigurations": { "default": { "pageUrl": "https://sppnp.sharepoint.com/sites/mySite/SitePages/myPage.aspx", "customActions": { "54328ea6-0591-4fbd-aadb-5dc51fd53235": { "location": "ClientSideExtension.ApplicationCustomizer", "properties": { "Top": "Top area of the page", "Bottom": "Bottom area of the page" } } } }, "helloWorld": { "pageUrl": "https://sppnp.sharepoint.com/sites/mySite/SitePages/myPage.aspx", "customActions": { "54328ea6-0591-4fbd-aadb-5dc51fd53235": { "location": "ClientSideExtension.ApplicationCustomizer", "properties": { "Top": "Top area of the page", "Bottom": "Bottom area of the page" } } } } } }Notes
Le GUID dans l’extrait JSON ci-dessus est l’ID unique du composant d’extension SPFx. Ceci est défini dans le manifeste du composant. Le GUID de votre solution sera différent, car chaque ID de composant est unique.
Basculez vers la fenêtre de console qui exécute Gulp serve et recherchez les erreurs. Gulp signale les erreurs dans la console ; Vous devrez les corriger avant de continuer. Si la solution est déjà en cours d’exécution, redémarrez-la afin que les paramètres mis à jour s’appliquent à partir du fichierserve.jssur.
gulp serveSélectionnez Charger les scripts de débogage pour continuer à charger les scripts depuis votre hôte local.

Vous devriez maintenant voir le contenu d’en-tête et de pied de page personnalisé dans votre page.

Étapes suivantes
Félicitations, vous avez créé vos propres en-tête et pied de page personnalisés à l’aide du personnalisateur d’application.
Pour poursuivre la création de votre extension, consultez Déployer votre extension dans SharePoint (Hello world 3e partie). Vous allez découvrir comment déployer et afficher un aperçu de l’extension Hello World dans une collection de sites SharePoint sans utiliser les paramètres de requête Débogage.