Générateur Yeoman pour SharePoint Framework

  • Article

Le Générateur Yeoman SPFx SharePoint Online vous permet de créer rapidement un projet de solution SharePoint côté client avec la bonne structure de projet et la bonne chaîne d'outils. Il est utilisé avec Yeoman pour vous inviter à poser des questions pour créer la structure du projet (les fichiers de dossiers & ).

Importante

Cette page part du principe que vous avez déjà installé tous les prérequis nécessaires au développement de solutions SharePoint Framework. Vérifiez les instructions mises à jour décrites dans la page Configuration de votre environnement de développement SharePoint Framework.

Le Générateur Yeoman SPFx SharePoint Online (le « générateur SPFx »), utilise les réponses aux questions reçues par le développeur pour créer un projet SharePoint Framework (SPFx). Selon les réponses reçues, d’autres questions sont présentées.

Par exemple, si vous sélectionnez le type de composant WebPart, vous ne verrez que des questions relatives au nom du composant WebPart et au type de modèle. Toutefois, si vous sélectionnez le type de composant Extension, vous serez également invité à choisir le type d’extension tel que le personnalisateur d’application, le personnalisateur de champ ou le jeu de commandes ListView.

L’exemple suivant illustre la création d’une solution nommée sfpxplay-01 dans le dossier actuel avec un composant WebPart nommé HelloWorld qui utilise le modèle de projet Minimal :

yo @microsoft/sharepoint --skip-install

     _-----_     ╭──────────────────────────╮
    |       |    │      Welcome to the      │
    |--(o)--|    │  SharePoint Online SPFx  │
   `---------´   │          Yeoman          │
    ( _´U`_ )    │     Generator@1.14.0     │
    /___A___\   /╰──────────────────────────╯
     |  ~  |
   __'.___.'__
 ´   `  |° ´ Y `

Let's create a new SharePoint solution.
? What is your solution name? spfxplay-01
? Which type of client-side component to create? WebPart
Add new Web part to solution spfxplay-01.
? What is your Web part name? HelloWorld
? Which template would you like to use? Minimal

   create package.json
    force .yo-rc.json
   create config/package-solution.json
   create config/config.json
   create config/serve.json
   create tsconfig.json
   create .vscode/launch.json
   create .vscode/settings.json
   create config/deploy-azure-storage.json
   create config/write-manifests.json
   create src/index.ts
   create README.md
   create .gitignore
   create .npmignore
   create gulpfile.js
   create tslint.json
   create src/webparts/helloWorld/loc/en-us.js
   create src/webparts/helloWorld/loc/mystrings.d.ts
   create src/webparts/helloWorld/HelloWorldWebPart.module.scss
   create src/webparts/helloWorld/HelloWorldWebPart.ts
   create src/webparts/helloWorld/HelloWorldWebPart.manifest.json
   create teams/55564fc2-179d-4bc1-bd63-9ede8183dadc_outline.png
   create teams/55564fc2-179d-4bc1-bd63-9ede8183dadc_color.png

Changes to package.json were detected.
Skipping package manager install.

      _=+#####!
   ###########|       .------------------------------------.
   ###/    (##|(@)    |          Congratulations!          |
   ###  ######|   \   |  Solution spfxplay-01 is created.  |
   ###/   /###|   (@) |   Run gulp serve to play with it!  |
   #######  ##|   /   '------------------------------------'
   ###     /##|(@)
   ###########|
      **=+####!

Conseil

Les différents types de composants et options sont traités dans la documentation de ce site. Les options ne sont pas toutes traitées sur cette page. Pour plus d’informations sur les détails de chaque type de composant, consultez les rubriques pertinentes dans la documentation.

Installer le générateur Yeoman SPFx SharePoint Online

Le générateur SPFx est disponible en tant que package npm. Installez la dernière version du générateur SPFx en exécutant la commande suivante dans une console :

npm install @microsoft/generator-sharepoint -g

Vous pouvez également installer une version spécifique du générateur en spécifiant le numéro de version dans le nom du package, séparé par un @1. Par exemple, pour installer le générateur SPFx v1.10, exécutez la commande suivante :

npm install @microsoft/generator-sharepoint@1.10 -g

Options de modèle de projet

Avant la version SPFx v1.14, le générateur fournissait deux modèles de projet aux développeurs :

  • Aucune infrastructure JavaScript :
  • React

Remarque

Une troisième option, Knockout, était disponible dans toutes les versions SPFx via SPFx v1.10. Knockout a été supprimée en tant qu’option dans la version SPFx v1.11.

Ces modèles incluent le code minimal nécessaire à un projet pour commencer à créer des solutions. Le modèle Aucune infrastructure JavaScript utilisait du code HTML et CSS pour appliquer un style à un composant standard, alors que le modèle React utilisait HTML, React et CSS pour faire la même chose.

Modèle de projet mis à jour dans la version SPFx v1.14 avec prise en charge du thème

Dans la version SPFx v1.14, le générateur SPFx a introduit de nouveaux & modèles de projet mis à jour. L’objectif de ces modèles est d’inclure le code nécessaire pour prendre en charge le thème dans l’environnement actuel où le composant est en cours d’exécution (SharePoint ou Microsoft Teams).

Le code inclus dans ces modèles simplifie le travail initial à effectuer par les développeurs afin d’ajouter la prise en charge des thèmes à leurs composants. Par exemple, à l’aide de ces modèles, tout le code nécessaire pour déterminer les couleurs et la police utilisées dans le site SharePoint actuel sont disponibles dans le composant WebPart qui sera averti lorsque le thème change pour récupérer les nouveaux paramètres de thème.

Pour les composants SPFx utilisés dans le contexte de Microsoft Teams, ils recevront les détails du thème pour le client Microsoft Teams actuel, tels que par défaut (clair), sombre et contraste élevé.

En outre, ces modèles incluent le code pour déterminer si le composant est en cours d’exécution dans un contexte SharePoint ou un contexte Microsoft Teams.

Par exemple, les méthodes suivantes sont incluses dans les deux modèles. La méthode _getEnvironmentMessage() renvoie une chaîne indiquant si le composant est en cours d’exécution dans SharePoint ou Microsoft Teams et s’il est déployé en production ou en développement (servi à partir de l’hôte local). onThemeChanged() détermine si le thème actuel est en mode sombre et applique certaines modifications aux propriétés en fonction des couleurs de thème actuelles :

private _getEnvironmentMessage(): string {
  if (!!this.context.sdks.microsoftTeams) { // running in Teams
    return this.context.isServedFromLocalhost
        ? strings.AppLocalEnvironmentTeams
        : strings.AppTeamsTabEnvironment;
  }

  return this.context.isServedFromLocalhost
        ? strings.AppLocalEnvironmentSharePoint
        : strings.AppSharePointEnvironment;
}

protected onThemeChanged(currentTheme: IReadonlyTheme | undefined): void {
  if (!currentTheme) {
    return;
  }

  this._isDarkTheme = !!currentTheme.isInverted;
  const {
    semanticColors
  } = currentTheme;
  this.domElement.style.setProperty('--bodyText', semanticColors.bodyText);
  this.domElement.style.setProperty('--link', semanticColors.link);
  this.domElement.style.setProperty('--linkHovered', semanticColors.linkHovered);

}

Modèle de projet minimal

Une nouvelle option de modèle de projet, Minimal, a été ajoutée au générateur SPFx dans la version SPFx v1.14. Cette option de modèle de projet n’inclut aucun code de thème ou d’environnement hôte dans les nouveaux projets.

Par exemple, un nouveau projet de composant WebPart commence par le code suivant, représentant le code minimal nécessaire pour l’exécuter :

export default class HelloWorldMinimalWebPart
          extends BaseClientSideWebPart<IHelloWorldMinimalWebPartProps> {

  protected onInit(): Promise<void> {
    return super.onInit();
  }

  public render(): void {
    this.domElement.innerHTML = `<div class="${ styles.helloWorldMinimal }"></div>`;
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }
}

Invites du générateur supprimées

Lors de la mise en production de chaque SharePoint Framework, des invites peuvent être ajoutées ou supprimées dans le générateur Yeoman. Les invites ont été supprimées pour simplifier l’expérience de création de projet.

Dans la section suivante, vous trouverez les invites supprimées avec les instructions applicables.

Cibler plusieurs environnements SharePoint

Dans la version SPFx v1.13, l’invite suivante a été supprimée :

Quels packages de base voulez-vous cibler pour vos composants ?

Le développeur recevait cette invite avec la possibilité de créer un projet ciblant des déploiements SharePoint spécifiques, notamment :

  • SharePoint Online uniquement (dernière version)
  • SharePoint 2016 et versions ultérieures, y compris 2019 et SharePoint Online
  • SharePoint 2019 et versions ultérieures, y compris SharePoint Online

À partir de la version SPFx v1.13, le générateur peut uniquement créer des projets pour SharePoint Online.

Ignorer le déploiement de fonctionnalités – skipFeatureDeployment

Dans la version SPFx v1.14, l’invite suivante a été supprimée :

Voulez-vous autoriser l’administrateur client à choisir de pouvoir déployer la solution sur tous les sites immédiatement sans exécuter de déploiement de fonctionnalité ni ajouter d’applications sur les sites.

Cette question vous demande si la solution doit être installée automatiquement pour tous les sites du client ou si elle doit être installée manuellement sur chaque site. L’option par défaut était [N]o.

Remarque

En savoir plus sur cette invite : Déploiement de solutions destinées au client pour les solutions SharePoint Framework.

Le résultat de cette question a été défini sur la propriété skipFeatureDeployment dans le fichier ./config/package-solution.json du projet.

À partir de la version SPFx v1.14, la propriété skipFeatureDeployment est true par défaut. Vous pouvez modifier la valeur de cette propriété après la création du projet, le cas échéant.

Composants WebPart isolés de domaine : isDomainIsolated

Dans la version SPFx v1.14, l’invite suivante a été supprimée :

Les composants de la solution nécessiteront-ils des autorisations pour accéder aux API web qui sont uniques et qui ne sont pas partagées avec d'autres composants du client ?

Cette question vous demande si les composants WebPart au sein de la solution doivent être rendus dans l’IFRAME dans un domaine unique ou dans le DIV en tant que page actuelle. L’option par défaut était [N]o.

Remarque

En savoir plus sur cette invite : Composants WebPart isolés

Le résultat de cette question a été défini sur la propriété isDomainIsolated dans le fichier ./config/package-solution.json du projet.

À partir de la version SPFx v1.14, la propriété isDomainIsolated est false par défaut. Vous pouvez modifier la valeur de cette propriété après la création du projet, le cas échéant.

Quelle infrastructure voulez-vous utiliser ?

Dans la version SPFx v1.14, l’invite suivante a été modifiée :

Quelle infrastructure voulez-vous utiliser ?

Cette invite s’affiche pour des types de projet spécifiques, tels que les types de composants WebPart & des extensions SPFx. Elle permettait aux développeurs de sélectionner des modèles de projet différents : Aucune infrastructure JavaScript ou React.

La création de la structuration du projet par défaut par le générateur Yeoman a été déterminée à l’aide de l’option sélectionnée.

Dans la version SPFx v1.14, cette invite a été modifiée de la façon suivante et offrait trois choix à l’utilisateur : Minimal, Aucune infrastructure ou React :

Quel modèle souhaitez-vous utiliser ?

Descriptions des composants

Dans la version SPFx v1.14, les invites suivantes ont été supprimées :

Quelle est la description de votre composant WebPart ?

Quelle est la description de votre personnalisateur d’application ?

Quelle est la description de votre Personnalisateur de champ ?

Quelle est la description de votre Jeu de commandes ListView ?

Quelle est la description de votre Bibliothèque ?

Quelle est la description de votre extension de carte adaptative?

Les valeurs de ces invites ont été définies sur les preConfiguredEntries[0].description.default&preConfiguredEntries[0].properties.description propriétés du fichier *.manifest.json du composant.

À partir de la version SPFx v1.14, ces propriétés sont définies sur des chaînes vides. Vous pouvez modifier la valeur de ces propriétés après la création du projet, le cas échéant.

Options de ligne de commande du générateur Yeoman

Vous pouvez utiliser les options de ligne de commande disponibles avec le générateur SPFx pour créer des projets en une seule commande au lieu de suivre les invites. Exécutez la commande suivante pour afficher la liste des options de ligne de commande disponibles pour le générateur SharePoint :

yo @microsoft/sharepoint --help