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

  1. 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-core
    
  2. Créez un fichier nommé ./src/extensions/helloWorld/AppCustomizer.module.scss.

  3. 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;
      }
    }
    
  4. Dans Visual Studio Code (ou votre IDE préféré), ouvrez ./src/extensions/helloWorld/HelloWorldApplicationCustomizer.ts.

  5. Ajoutez PlaceholderContent l’instruction import à partir de PlaceholderName @ 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 strings en haut du fichier :

    import styles from './AppCustomizer.module.scss';
    import { escape } from '@microsoft/sp-lodash-subset';
    

    Vous utiliserez la escape fonction 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.

  6. 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 IHelloWorldApplicationCustomizerProperties liste, comme suit :

    Notes

    Si votre personnaliste d’application utilise ClientSideComponentProperties l’entrée JSON, elle est désérialisée dans BaseExtension.properties l’objet. Vous pouvez définir une interface pour le décrire.

    export interface IHelloWorldApplicationCustomizerProperties {
      Top: string;
      Bottom: string;
    }
    
  7. Ajoutez les variables privées suivantes à l’intérieur de HelloWorldApplicationCustomizer la classe. Dans ce scénario, elles peuvent être uniquement des variables locales dans une méthode onRender(), 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;
    
      // ...
    }
    
  8. 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>();
    }
    
  9. 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.tryCreateContent pour 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 Top et Bottom. 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 styles n’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.
  10. 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

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

  2. 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 serve
    
  3. Sélectionnez Charger les scripts de débogage pour continuer à charger les scripts depuis votre hôte local.

    Autoriser la question de manifeste de débogage de la page

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

Éléments d’en-tête et de pied de page personnalisés rendus dans la 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.