Ajouter une bibliothèque externe à votre composant WebPart côté client SharePoint

  • Article

Vous souhaiterez peut-être inclure une ou plusieurs bibliothèques JavaScript dans votre composant WebPart. Cet article vous montre comment inclure une bibliothèque externe dans un fichier groupé et partager des bibliothèques.

Regrouper un script

Par défaut, le programme de regroupement de composants WebPart inclut automatiquement toute bibliothèque qui est une dépendance du module de composant WebPart. Cela signifie que la bibliothèque est déployée dans le même fichier groupé JavaScript que votre composant WebPart. Ce système est plus pratique pour les bibliothèques de petite taille qui ne sont pas utilisées dans plusieurs composants WebPart.

Exemple

  1. Incluez le package validator, qui installe une bibliothèque de validation de chaînes, dans un composant WebPart.

  2. Téléchargez le package de validation à partir de NPM :

    npm install validator --save

    Remarque

    Étant donné que vous utilisez TypeScript, vous aurez probablement besoin des déclarations de type pour le package que vous ajoutez. Cela est utile lorsque vous écrivez du code, car TypeScript n’est qu’un sur-ensemble de JavaScript. Tout le code TypeScript est toujours converti en code JavaScript lors de la compilation. Vous pouvez installer des déclarations de type à l’aide de NPM, par exemple : npm install @types/{package} --save-dev

  3. Créez un fichier dans le dossier de votre composant WebPart appelé validator.d.ts et ajoutez ce qui suit :

    declare module "validator" {
    export function isEmail(email: string): boolean;
    export function isAscii(text: string): boolean;
}

    Remarque

    Certaines bibliothèques n’ont pas de déclarations de type. Même si la bibliothèque de validation possède une communauté fournie par le fichier de déclarations de type, imaginons que ce n’est pas le cas dans ce scénario. Dans ce cas, vous pouvez définir votre propre fichier .d.ts de définition de déclarations de type pour la bibliothèque. Le code précédent vous montre un exemple.

  4. Dans le fichier de votre composant WebPart, importez les déclarations de type :

    import * as validator from 'validator';

  5. Utilisez la bibliothèque validator dans votre code de composant WebPart :

    validator.isEmail('someone@example.com');

Partage d’une bibliothèque entre plusieurs composants WebPart

Votre solution côté client peut inclure plusieurs composants WebPart. Il se peut que ces composants WebPart doivent importer ou partager la même bibliothèque. Dans ce cas, au lieu d’inclure la bibliothèque dans un fichier groupé, vous devez l’inclure dans un fichier JavaScript à part pour améliorer les performances et la mise en cache. C’est particulièrement vrai pour les bibliothèques plus volumineuses.

Exemple

Dans cet exemple, vous allez partager le package marqué (un compilateur Markdown) dans un fichier groupé séparé.

  1. Téléchargez le package marqué à partir du NPM :

    npm install marked --save

  2. Installez le package de déclarations de type dans votre projet :

    npm install @types/marked --save-dev

  3. Modifiez la valeur config/config.json et ajoutez une entrée à la carte externals. Cette opération indique au programme de regroupement d’inclure le package dans un fichier à part. De cette façon, il ne l’inclut pas dans un fichier groupé :

    "marked": "node_modules/marked/marked.min.js"

  4. Maintenant que nous avons ajouté le package et les déclarations de type pour la bibliothèque, ajoutez l’instruction pour importer la bibliothèque marqué dans votre composant WebPart :

    import * as marked from 'marked';

  5. Utilisez la bibliothèque dans votre composant WebPart :

    console.log(marked('I am using __markdown__.'));

Chargement d’un script à partir d’un CDN

Au lieu de charger la bibliothèque à partir d’un package NPM, vous pouvez charger un script à partir d’un réseau de distribution de contenu (CDN). Pour ce faire, modifiez le fichier config.json pour charger la bibliothèque à partir de l’URL de son CDN.

Exemple

Dans cet exemple, vous allez charger jQuery à partir du CDN. Vous n’avez pas besoin d’installer le package NPM. Toutefois, vous devez toujours installer les déclarations de type.

  1. Installer des déclarations de type pour jQuery :

    npm install --save-dev @types/jquery

  2. Mettez à jour config.json dans le dossier config pour charger jQuery à partir du CDN. Ajoutez une entrée au champ externals:

    "jquery": "https://code.jquery.com/jquery-3.1.0.min.js"

  3. Importez jQuery dans votre composant WebPart :

    import * as $ from 'jquery';

  4. Utilisez jQuery dans votre composant WebPart :

    alert( $('#foo').val() );

Chargement d’un module non AMD

Certains scripts suivent l’ancien modèle JavaScript, à savoir stocker la bibliothèque sur l’espace de noms global. Ce modèle est en cours d’abandon, au profit de définitions de modules universels (UMD)/définitions de modules asynchrones (AMD) ou de modules ES6. Toutefois, vous devrez peut-être charger ces bibliothèques dans votre composant WebPart.

Conseil

Il est difficile de déterminer manuellement si le script que vous essayez de charger est un script AMD ou non. C’est notamment le cas si le script est minimisé.

Si votre script est hébergé sur une URL accessible au public, vous pouvez utiliser l’outil gratuit Rencore SharePoint Framework Script Check pour déterminer le type de script à votre place. Cet outil vous permet également de savoir si l’emplacement d’hébergement à partir duquel vous chargez le script est correctement configuré. Cet outil est également disponible dans l’extension de code VS Vérification des scripts SPFx de Rencore

Pour charger un module non AMD, vous devez ajouter une propriété supplémentaire à l’entrée de votre fichier config.json.

Exemple

Dans cet exemple, vous allez charger un module fictif non-AMD à partir du CDN de Contoso. Ces étapes s’appliquent à tout script non AMD dans votre répertoire src/ ou node_modules/.

Le script est appelé Contoso.js et se trouve à l’emplacement https://contoso.com/contoso.js. Voici son contenu :

var ContosoJS = {
  say: function(text) { alert(text); },
  sayHello: function(name) { alert('Hello, ' + name + '!'); }
};

  1. Créez des déclarations de type pour le script dans un fichier appelé contoso.d.ts dans le dossier du composant WebPart.

    declare module "contoso" {
  interface IContoso {
    say(text: string): void;
    sayHello(name: string): void;
  }
  var contoso: IContoso;
  export = contoso;
}

  2. Mettez à jour le fichier config.json pour inclure ce script. Ajoutez une entrée à la carte externals :

    {
  "contoso": {
    "path": "https://contoso.com/contoso.js",
    "globalName": "ContosoJS"
  }
}

  3. Ajoutez une instruction import au code de votre composant WebPart :

    import contoso from 'contoso';

  4. Utilisez la bibliothèque contoso dans votre code :

    contoso.sayHello(username);

Chargement d’une bibliothèque comportant une dépendance sur une autre bibliothèque

De nombreuses bibliothèques ont des dépendances sur une autre bibliothèque. Vous pouvez spécifier ces dépendances dans le fichier config.json à l’aide de la propriété globalDependencies.

Importante

Vous n’êtes pas obligé de remplir ce champ pour les modules AMD : ils s’importent mutuellement. Toutefois, un module non AMD ne peut pas avoir de module AMD comme dépendance. Dans certains cas, il est possible de charger un script AMD sous la forme d’un script non AMD. Ce paramètre est souvent obligatoire quand vous travaillez avec jQuery, qui est lui-même un script AMD, ou avec les plug-ins jQuery, qui sont souvent distribués comme des scripts non AMD et qui dépendent de jQuery.

En voici deux exemples.

Module non AMD ayant un module non AMD comme dépendance

Cet exemple implique deux scripts fictifs. Ils se trouvent dans le dossier src /, bien qu’ils puissent également être chargés à partir d’un CDN.

ContosoUI.js

Contoso.EventList = {
  alert: function() {
    var events = Contoso.getEvents();
    events.forEach( function(event) {
      alert(event);
    });
  }
}

ContosoCore.js

var Contoso = {
  getEvents: function() {
    return ['A', 'B', 'C'];
  }
};

  1. Ajoutez ou créez des déclarations de type pour cette classe. Dans ce cas, vous allez créer Contoso.d.ts, qui contient des déclarations de type pour les deux fichiers JavaScript.

    contoso.d.ts

    declare module "contoso" {
  interface IEventList {
    alert(): void;
  }
  interface IContoso {
    getEvents(): string[];
    EventList: IEventList;
  }
  var contoso: IContoso;
  export = contoso;
}

  2. Mettez à jour le fichier config.json . Ajoutez deux entrées à externals:

    {
  "contoso": {
    "path": "/src/ContosoCore.js",
    "globalName": "Contoso"
  },
  "contoso-ui": {
    "path": "/src/ContosoUI.js",
    "globalName": "Contoso",
    "globalDependencies": ["contoso"]
  }
}

  3. Ajouter des instructions import pour Contoso et ContosoUI :

    import contoso = require('contoso');
require('contoso-ui');

  4. Utilisez les bibliothèques dans votre code :

    contoso.EventList.alert();

Chargement d’un JSOM SharePoint

Le chargement d’un JSOM SharePoint s’effectue essentiellement de la même façon que le chargement de scripts non AMD ayant des dépendances. Cela signifie l’utilisation des globalName options et .globalDependency

Importante

L’approche suivante génère des erreurs dans les pages SharePoint classiques, là où un JSOM SharePoint est déjà chargé. Pour que votre composant WebPart fonctionne sur les pages classiques et modernes, vérifiez d’abord si un JSOM SharePoint est déjà disponible. Si ce n’est pas le cas, chargez-le dynamiquement à l’aide de SPComponentLoader.

  1. Installez des déclarations de type pour Microsoft Ajax, une dépendance des déclarations de type de JSOM :

    npm install @types/microsoft-ajax --save-dev

  2. Installez des déclarations de type pour le JOSM :

    npm install @types/sharepoint --save-dev

  3. Ajoutez des entrées au fichier config.json:

    {
  "sp-init": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/init.js",
    "globalName": "$_global_init"
  },
  "microsoft-ajax": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/MicrosoftAjax.js",
    "globalName": "Sys",
    "globalDependencies": [ "sp-init" ]
  },
  "sp-runtime": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/SP.Runtime.js",
    "globalName": "SP",
    "globalDependencies": [ "microsoft-ajax" ]
  },
  "sharepoint": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/SP.js",
    "globalName": "SP",
    "globalDependencies": [ "sp-runtime" ]
  }
}

  4. Dans votre composant WebPart, ajoutez les instructions require suivantes :

    require('sp-init');
require('microsoft-ajax');
require('sp-runtime');
require('sharepoint');

Chargement de ressources localisées

Il existe une carte dans config.json appelée localizedResources pour décrire le mode de chargement des ressources localisées. Les chemins d’accès de cette carte sont des chemins relatifs par rapport au dossier lib et ne doivent pas contenir de barre oblique (/).

Dans cet exemple, vous avez un dossier src/strings/. Ce dossier contient plusieurs fichiers JavaScript portant des noms tels que en-us.js, fr-fr.js, de-de.js. Étant donné que chacun de ces fichiers doit être chargeable par le chargeur de module, ils doivent contenir un wrapper CommonJS. Par exemple, dans en-us.js:

  define([], function() {
    return {
      "PropertyPaneDescription": "Description",
      "BasicGroupName": "Group Name",
      "DescriptionFieldLabel": "Description Field"
    }
  });

  1. Modifiez le fichier config.json. Ajoutez une entrée à localizedResources. {locale} remplace ici le nom des paramètres régionaux :

    {
  "strings": "strings/{locale}.js"
}

  2. Ajoutez des déclarations de type pour vos chaînes. Dans ce cas, vous avez un fichier MyStrings.d.ts :

    declare interface IStrings {
  webpartTitle: string;
  initialPrompt: string;
  exitPrompt: string;
}

declare module 'mystrings' {
  const strings: IStrings;
  export = strings;
}

  3. Ajoutez des instructions import pour les chaînes de votre projet :

    import * as strings from 'mystrings';

  4. Utilisez les chaînes dans votre projet :

    alert(strings.initialPrompt);

Voir aussi