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.

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
Créez un dossier pour votre projet.
md js-thirdpartycssAccédez au dossier du projet.
cd js-thirdpartycssDans 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/sharepointLorsque 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

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.

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
Installez jQuery et l’interface utilisateur jQuery en exécutant la commande suivante :
npm install jquery jquery-ui --saveComme 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.
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.Vérifiez que le projet est en cours de création en exécutant la commande suivante :
gulp serveUne fois le composant WebPart ajouté au canevas, l’accordéon devrait fonctionner.

À 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.
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é.
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.

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.

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.
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.
Vérifiez que le projet est en cours de création en exécutant la commande suivante :
gulp serveUne fois le composant WebPart ajouté au canevas, l’accordéon devrait fonctionner.

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.

À 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
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';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.
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.

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.