Référencement des styles CSS tiers dans les composants WebPart de SharePoint Framework

Pour générer des composants WebPart côté client SharePoint Framework enrichis, il existe de nombreuses bibliothèques tierces que vous pouvez exploiter. Outre les scripts, ces bibliothèques comprennent souvent d’autres ressources telles que des feuilles de style. Cet article décrit deux approches différentes pour inclure des styles CSS tiers dans les composants WebPart et la façon dont chaque approche affecte le groupe de composants WebPart qui en résulte. L’exemple de composant WebPart mentionné dans cet article utilise jQuery et l’interface utilisateur jQuery pour afficher un accordéon.

Accordéon de l’interface utilisateur jQuery rendu par un composant WebPart côté client de SharePoint Framework

Notes

Avant de suivre les étapes décrites dans cet article, n’oubliez pas de configurer votre environnement de développement de composant WebPart côté client SharePoint.

Préparer le projet

Création d’un projet

  1. Créez un dossier pour votre projet.

    md js-thirdpartycss
    
  2. Accédez au dossier du projet.

    cd js-thirdpartycss
    
  3. Dans le dossier du projet, exécutez le générateur Yeoman pour SharePoint Framework pour établir la structure d’un nouveau projet SharePoint Framework.

    yo @microsoft/sharepoint
    
  4. Lorsque vous y êtes invité, entrez les valeurs suivantes :

    • js-thirdpartycss comme nom de votre solution
    • Utiliser le dossier en cours pour l’emplacement des fichiers
    • Aucune infrastructure JavaScript comme point de départ pour créer le composant WebPart
    • Accordéon jQuery comme nom de votre composant WebPart
    • Affiche l’accordéon jQuery comme description de votre composant WebPart

    Générateur Yeoman pour SharePoint Framework avec les options par défaut

  5. Ouvrez votre dossier de projet dans votre éditeur de code. Cet article utilise Visual Studio Code dans les étapes et les captures d’écran, mais vous pouvez utiliser n’importe quel éditeur de votre choix.

    Projet SharePoint Framework ouvert dans Visual Studio Code

Ajout du contenu de test

Dans l’éditeur de code, ouvrez le fichier ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts, puis remplacez la méthode render() par :

export default class JQueryAccordionWebPart extends BaseClientSideWebPart<IJQueryAccordionWebPartProps> {
  // ...
  public render(): void {
    this.domElement.innerHTML = `
      <div>
        <div class="accordion">
          <h3>Information</h3>
          <div>
            <p>
            The Volcanoes, crags, and caves park is a scenic destination for
            many visitors each year. To ensure everyone has a good
            experience and to preserve the natural beauty, access is
            restricted based on a permit system.
            </p>
            <p>
            Activities include viewing active volcanoes, skiing on mountains,
            walking across lava fields, and caving (spelunking) in caves
            left behind by the lava.
            </p>
          </div>
          <h3>Snow permit</h3>
          <div>
            <p>
            The Northern region has snow in the mountains during winter.
            Purchase a snow permit for access to approved ski areas.
            </p>
          </div>
          <h3>Hiking permit</h3>
          <div>
            <p>
            The entire region has hiking trails for your enjoyment.
            Purchase a hiking permit for access to approved trails.
            </p>
          </div>
          <h3>Volcano access</h3>
          <div>
            <p>
            The volcanic region is beautiful but also dangerous. Each
            area may have restrictions based on wind and volcanic
            conditions. There are three type of permits based on activity.
            </p>
            <ul>
              <li>Volcano drive car pass</li>
              <li>Lava field access permit</li>
              <li>Caving permit</li>
            </ul>
          </div>
        </div>
      </div>`;

      ($('.accordion', this.domElement) as any).accordion();
  }
  // ...
}

Si vous générez maintenant le projet, vous obtenez une erreur indiquant que $ n’est pas défini. Cette erreur est due au fait que le projet renvoie à jQuery sans le charger au préalable. Il existe deux approches pour charger les bibliothèques. Aucune de ces approches n’influe sur la façon dont vous utilisez les scripts dans le code.

Approche 1 : inclusion des bibliothèques tierces dans le fichier groupé

Pour faire référence à une bibliothèque tierce dans les projets d’infrastructure SharePoint, le plus simple consiste à l’inclure dans le fichier groupé généré. La bibliothèque est installée en tant que package et référencée dans le projet. Pendant le regroupement du projet, Webpack sélectionne la référence à la bibliothèque et l’inclut dans le fichier groupé généré.

Installation des bibliothèques

  1. Installez jQuery et l’interface utilisateur jQuery en exécutant la commande suivante :

    npm install jquery jquery-ui --save
    
  2. Comme vous générez votre composant WebPart dans TypeScript, vous avez également besoin de déclarations de types TypeScript pour jQuery que vous pouvez installer en exécutant la commande suivante :

    npm install @types/jquery --save-dev
    

Bibliothèques de référence dans le composant WebPart

Après avoir installé les bibliothèques, l’étape suivante consiste à y référer dans le projet.

  1. Dans l’éditeur de code, ouvrez le fichier ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts. Dans la partie supérieure, juste en dessous de la dernière instruction import, ajoutez des références aux interfaces utilisateur jQuery et jQuery.

    import * as $ from 'jquery';
    require('../../../node_modules/jquery-ui/ui/widgets/accordion');
    

    Étant donné que vous avez installé les déclarations de types TypeScript pour le package jQuery, vous pouvez y faire référence à l’aide d’une instruction import. Toutefois, le package de l’interface utilisateur jQuery est créé différemment. Contrairement au nombre de modules structurés, il n’existe aucun point d’entrée principal avec une référence à tous les composants que vous pouvez utiliser. Dans ce cas, faites directement référence à l’élément spécifique que vous souhaitez utiliser. Le point d’entrée de ce composant contient toutes les références aux dépendances dont il a besoin pour fonctionner correctement.

  2. Vérifiez que le projet est en cours de création en exécutant la commande suivante :

    gulp serve
    
  3. Une fois le composant WebPart ajouté au canevas, l’accordéon devrait fonctionner.

    Accordéon de l’interface utilisateur jQuery sans styles rendus par un composant WebPart côté client de SharePoint Framework

À ce stade, vous avez référencé uniquement les scripts d’interface utilisateur jQuery, ce qui explique pourquoi le style de l’accordéon n’est pas appliqué. Ensuite, vous allez ajouter les feuilles de style CSS manquantes pour personnaliser l’accordéon.

Référencement des feuilles de style CSS tierces dans le composant WebPart

L’ajout de références à des feuilles de style CSS tierces qui font partie des packages installés dans le projet est aussi simple que l’ajout de références aux packages eux-mêmes. SharePoint Framework offre une prise en charge standard du chargement des fichiers CSS via Webpack.

  1. Dans l’éditeur de code, ouvrez le fichier ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts. Juste en dessous de la dernière instruction require, ajoutez des références à des fichiers CSS de l’accordéon d’interface utilisateur jQuery.

    require('../../../node_modules/jquery-ui/themes/base/core.css');
    require('../../../node_modules/jquery-ui/themes/base/accordion.css');
    require('../../../node_modules/jquery-ui/themes/base/theme.css');
    

    Faire référence à des fichiers CSS qui font partie d’un package dans le projet est semblable à l’ajout de références à des fichiers JavaScript. Il vous suffit d’indiquer le chemin d’accès relatif au fichier CSS à charger, y compris l’extension .css. Pendant le regroupement du projet, Webpack traite ces références et inclut les fichiers dans le fichier groupé de composants WebPart généré.

  2. Vérifiez que le projet est en cours de création en exécutant la commande suivante :

    gulp serve
    

L’accordéon doit être affiché correctement et personnalisé à l’aide du thème standard de jQuery UI.

Accordéon de l’interface utilisateur jQuery marqué à l’aide du thème de l’interface utilisateur jQuery par défaut rendu par un composant WebPart côté client de SharePoint Framework

Analyser le contenu du fichier groupé de composants WebPart généré

Le moyen le plus simple d’utiliser des bibliothèques tierces et leurs ressources consiste à les inclure dans le fichier groupé de composants WebPart généré. Dans cette approche, Webpack résout automatiquement toutes les dépendances entre les différentes bibliothèques et vérifie que tous les scripts sont chargés dans le bon ordre. L’inconvénient de cette approche est que toutes les ressources référencées sont chargées séparément avec chaque composant WebPart. Si vous avez plusieurs composants WebPart dans votre projet, qui utilisent tous l’interface utilisateur jQuery, chaque composant WebPart charge sa propre copie de l’interface utilisateur jQuery et ralentit la page.

Pour connaître l’impact des bibliothèques sur la taille du fichier groupé de composants WebPart généré, une fois le regroupement du projet effectué, ouvrez le fichier ./temp/stats/js-thirdpartycss.stats.html dans le navigateur web. Déplacez votre souris sur le graphique et vous verrez, par exemple, que les fichiers CSS de l’interface utilisateur jQuery référencés par le composant WebPart constituent plus de 6 % de la taille totale du fichier groupé de composants WebPart.

Fichier CSS de l’interface utilisateur jQuery en surbrillance dans le graphique illustrant la taille des différentes parties du fichier groupé de composants WebPart généré

Comme indiqué dans la clause d’exclusion de responsabilité qui suit le graphique, les tailles sont fournies à titre indicatif et reflètent la taille de la version de débogage du fichier groupé. La version commerciale du fichier groupé est plus petite. Il est donc préférable de déterminer les différentes parties qui composent le fichier groupé de composants WebPart et leur taille relative par rapport aux autres éléments du fichier groupé.

Approche 2 : chargement des bibliothèques tierces à partir d’une URL

Une autre méthode pour faire référence à des bibliothèques tierces dans l’infrastructure SharePoint consiste à y faire référence à partir d’une URL telle qu’un CDN public ou un emplacement géré en privé. Le principal avantage est que si vous chargez une bibliothèque fréquemment utilisée à partir d’un emplacement public, il est possible que les utilisateurs aient déjà téléchargé cette bibliothèque particulière sur leur ordinateur. Dans ce cas, SharePoint Framework réutilise la bibliothèque mise en cache, ce qui accélère le chargement de votre composant WebPart.

Même si vous ne pouvez pas utiliser un CDN public pour charger des bibliothèques à partir d’un emplacement central, nous vous recommandons d’utiliser cette méthode pour obtenir de meilleures performances. Pointer sur une URL permet à vos utilisateurs de ne télécharger le script qu’une seule fois et de le réutiliser dans le portail entier, ce qui accélère considérablement le chargement des pages et améliore l’expérience utilisateur.

Quand vous chargez des bibliothèques tierces à partir d’URL publiques, il existe un risque lié à l’utilisation de ces bibliothèques. Comme vous ne gérez pas l’emplacement d’hébergement d’un script en particulier, vous ne pouvez pas être sûr de son contenu. Les scripts chargés par l’infrastructure SharePoint s’exécutent dans le contexte de l’utilisateur actuel et sont autorisés à faire tout ce que peut faire cet utilisateur. En outre, si l’emplacement d’hébergement est en mode hors connexion, votre composant WebPart ne fonctionnera pas.

Installer des déclarations de type pour les bibliothèques

Lorsque vous référencez des bibliothèques tierces à partir d’une URL, vous n’avez pas besoin de les installer en tant que packages dans votre projet. Vous devez installer leurs déclarations de type TypeScript si vous souhaitez bénéficier des contrôles de sécurité de type pendant le développement.

En supposant que vous commenciez avec un projet vide créé comme indiqué précédemment dans cet article, installez les déclarations de types TypeScript pour jQuery en exécutant la commande suivante :

npm install @types/jquery --save-dev

Spécifier les URL des bibliothèques

Pour charger les bibliothèques tierces à partir d’une URL, vous devez spécifier l’URL où elles se trouvent dans la configuration de votre projet. Dans l’éditeur de code, ouvrez le fichier ./config/config.json. Dans la section externals, ajoutez le fichier JSON suivant :

{
  //...
  "externals": {
    //...
    "jquery": "https://code.jquery.com/jquery-3.1.1.min.js",
    "jquery-ui": "https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"
    //...
  }
  //...
}

Référencement des bibliothèques à partir de l’URL dans le composant WebPart

Une fois que vous avez spécifié l’URL que l’infrastructure SharePoint doit utiliser pour charger jQuery et l’interface utilisateur jQuery, l’étape suivante consiste à y faire référence dans le projet.

  1. Dans l’éditeur de code, ouvrez le fichier ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts. Dans la partie supérieure, juste en dessous de la dernière instruction import, ajoutez les références suivantes à jQuery et à l’interface utilisateur jQuery :

    import * as $ from 'jquery';
    require('jquery-ui');
    

    En comparaison avec la façon de référencer les deux bibliothèques lorsqu’elles étaient installées sous forme de packages dans votre projet, le référencement à partir de l’URL est similaire. Étant donné que les déclarations de types TypeScript de jQuery sont installés, vous pouvez faire référence à jQuery à l’aide d’une instruction import. Pour l’interface utilisateur jQuery, vous souhaitez simplement charger le script dans la page.

    Comme vous avez enregistré jquery et jquery-ui dans la configuration du projet comme des ressources externes, quand vous référencez l’une de ces bibliothèques, SharePoint Framework utilise les URL spécifiées pour les charger pendant l’exécution. Pendant le regroupement du projet, ces ressources sont marquées comme externes et sont exclues du fichier groupé.

    N’oubliez pas que, précédemment, vous avez choisi de charger l’accordéon à partir du package de jQuery UI. Maintenant, vous faites référence à jQuery UI à partir du CDN qui contient tous les composants de jQuery UI.

  2. Vérifiez que le projet est en cours de création en exécutant la commande suivante :

    gulp serve
    

    Une fois le composant WebPart ajouté au canevas, l’accordéon devrait fonctionner.

    Accordéon de l’interface utilisateur jQuery sans styles rendus par un composant WebPart côté client de SharePoint Framework

  3. Dans votre navigateur web, ouvrez les outils de développement, basculez vers l’onglet affichant les requêtes réseau et rechargez la page. Vous devriez voir comment jQuery et l’interface utilisateur jQuery sont chargés depuis le CDN.

    Requête jQuery et interface utilisateur jQuery mise en surbrillance dans les outils de développement Microsoft Edge

À ce stade, vous avez référencé uniquement les scripts de l’interface utilisateur jQuery, ce qui explique pourquoi le style de l’accordéon n’est pas appliqué. Ensuite, vous allez ajouter les feuilles de style CSS manquantes pour personnaliser l’accordéon.

Référencement des feuilles de style CSS tierces à partir de l’URL dans le composant WebPart

L’ajout de références à des feuilles de style CSS tierces à partir d’une URL et le référencement des ressources à partir de packages de projet ne reviennent pas au même. Alors que la configuration du projet dans le fichier config.json vous permet de spécifier des ressources externes, elle s’applique uniquement aux scripts. Pour référencer des feuilles de style CSS à partir d’une URL, utilisez plutôt SPComponentLoader.

Chargement de CSS à partir de l’URL à l’aide de SPComponentLoader

  1. Dans l’éditeur de code, ouvrez le fichier ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts. Dans la partie supérieure du fichier, juste après la dernière instruction import, ajoutez le code suivant :

    import { SPComponentLoader } from '@microsoft/sp-loader';
    
  2. Dans le même fichier, remplacez la méthode onInit() comme suit :

    export default class JQueryAccordionWebPart extends BaseClientSideWebPart<IJQueryAccordionWebPartProps> {
      protected onInit(): Promise<void> {
        SPComponentLoader.loadCss('https://code.jquery.com/ui/1.12.1/themes/base/jquery-ui.min.css');
        return super.onInit();
      }
    
      // ...
    }
    

    Quand le composant WebPart est instancié dans la page, il charge la feuille de style CSS de jQuery UI à partir de l’URL spécifiée. Cette feuille de style CSS est la version combinée et optimisée de la feuille CSS de l’interface utilisateur qui contient les styles de base, le thème et le style de tous les composants jQuery.

  3. Vérifiez que le projet est en cours de création en exécutant la commande suivante :

    gulp serve
    

L’accordéon doit être affiché correctement et personnalisé à l’aide du thème standard de jQuery UI.

Accordéon de l’interface utilisateur jQuery marqué à l’aide du thème de l’interface utilisateur jQuery par défaut rendu par un composant WebPart côté client de SharePoint Framework

Analyse du contenu du fichier groupé de composants WebPart généré à partir de l’URL

Une fois le projet généré dans le navigateur web, ouvrez le fichier ./temp/stats/js-thirdpartycss.stats.html.

Le fichier groupé global est plus petit (7 Ko contre plus de 300 Ko quand vous incluez jQuery et l’interface utilisateur jQuery dans le fichier groupé). jQuery et l’interface utilisateur jQuery ne figurent pas dans le graphique car ils sont chargés pendant l’exécution.

Voir aussi