Partager via

Utilisation des structures d’interface utilisateur Office UI Fabric Core et Fabric React dans SharePoint Framework

  • Article

Office UI Fabric est l’infrastructure frontale officielle pour la création d’expériences dans Office 365 et SharePoint. SharePoint fournit une intégration transparente à Fabric qui permet à Microsoft de fournir un langage de conception robuste et cohérent dans diverses expériences SharePoint, telles que les sites d’équipe modernes, les pages modernes et les listes modernes. En outre, Office UI Fabric est disponible pour les développeurs dans le SharePoint Framework lors de la création de solutions SharePoint personnalisées.

Microsoft utilise Fabric Core et Fabric React dans SharePoint. Microsoft effectue régulièrement des mises à jour de SharePoint Online susceptibles de mettre également à jour les version de Fabric Core et de Fabric React. Ces mises à jour pourraient entraîner un conflit avec des solutions client tierces développées avec les versions précédentes de Fabric Core et Fabric React, ce qui pourrait provoquer des exceptions dans les personnalisations. La principale raison expliquant ces types de défaillances est l’utilisation des styles CSS globaux dans les deux bibliothèques Fabric. Ces conflits doivent être évités à tout prix.

Pour en savoir plus sur le problème associé aux styles CSS globaux dans le contexte de React et JavaScript, consultez cette présentation.

Pour obtenir un système fiable, il est essentiel de résoudre le problème des styles CSS globaux. Pour cela, nous vous recommandons d’éviter d’utiliser des noms de classes génériques dans les marques HTML, et d’utiliser plutôt les mixins et les variables de Fabric Core dans le fichier de déclaration Sass. Cela implique l’importation des déclarations Sass de Fabric Core dans votre fichier Sass, puis l’utilisation appropriée des variables et des mixins.

Objectifs

L’objectif de SharePoint Framework est de permettre à Microsoft et aux clients de générer des expériences utilisateur riches, esthétiques et cohérentes sur SharePoint.

Dans cette optique, voici quelques principes de conception clés :

  • Les clients doivent pouvoir utiliser Fabric Core et Fabric React dans leurs solutions avec fluidité et fiabilité.
  • Microsoft va déployer des expériences mises à jour qui utilisent des versions également mises à jour de Fabric Core et Fabric React dans SharePoint sans conflit avec les solutions du client.
  • Les clients peuvent personnaliser et remplacer les styles par défaut, les conceptions et les composants en fonction des besoins de leur solution.

Deux parties d’Office UI Fabric peuvent être utilisées par les développeurs :

  • Office UI Fabric Core. Regroupe le style de base, la typographie, la grille réactive, les animations, les icônes et d’autres blocs de construction fondamentaux du langage de conception global.

  • Office UI Fabric React. Un ensemble de composants React basés sur le langage de conception Fabric pour les projets basés sur React.

Package Office UI Fabric Core

Le package npm Fabric Core de SharePoint Framework (@microsoft/sp-office-ui-fabric-core) contient un sous-ensemble de styles Fabric Core pris en charge et pouvant être utilisés en toute sécurité au sein d’un composant SharePoint Framework.

Les styles Core suivants sont pris en charge dans le package :

  • Typographie
  • Dispositions
  • Couleurs
  • Thèmes
  • Localisation

Les éléments suivants ne sont pas encore pris en charge dans le package :

  • Animations
  • Icônes

Depuis la version 1.3.4 du générateur Yeoman de SharePoint Framework, les modèles de projets par défaut (composants WebPart et extensions) incluent, dès l’installation, le nouveau package @microsoft/sp-office-ui-fabric-core et utilisent les styles du package au lieu d’utiliser des styles CSS génériques.

Mettre à jour des projets existants

Pour utiliser le package Fabric Core dans votre projet existant, installez le package comme une dépendance :

npm install @microsoft/sp-office-ui-fabric-core --save

Une fois installé, vous pouvez importer les déclarations Sass de Fabric Core dans votre fichier de définition Sass et utiliser les variables et mixins comme décrit dans la section suivante.

Utiliser les styles Fabric Core

Pour utiliser les styles Fabric Core, importez les déclarations SPFabricCore dans votre fichier Sass.

Remarque

Vérifiez que le package npm @microsoft/sp-office-ui-fabric-core est bien installé.

@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

À présent, vous pouvez utiliser les styles Core comme mixins et variables.

.row {
  @include ms-Grid-row;
  @include ms-fontColor-white;
  background-color: $ms-color-themeDark;
  padding: 20px;
}

Office UI Fabric React

Nous vous recommandons d’utiliser les versions du package Office UI Fabric React inclus dans le projet dans le générateur Yeoman de SharePoint Framework. Par exemple, SharePoint Framework V1.7.0 utilise Fabric React v5.131.0.

Remarque

Les versions 2.x ou antérieures de Fabric React ne sont pas prises en charge dans SharePoint Framework.

Une fois le package Fabric React installé, vous pouvez importer les composants requis à partir du bundle de Fabric React.

//import Button component from Fabric React Button bundle
import { Button } from 'office-ui-fabric-react/lib/Button';

//use it in your component
render() {
  ...
  <div>
    <Button>click me</Button>
  </div>
  ...
}

Le package Fabric React inclut les styles Fabric Core pris en charge et utilisés dans les composants Fabric React. Nous vous recommandons d’importer les styles Fabric Core à partir du package Fabric React, et non à partir du package @microsoft/sp-office-ui-fabric-core, pour vous assurer que les bons styles sont utilisés dans votre composant.

Comme le package @microsoft/sp-office-ui-fabric-core est déjà installé dans votre solution par le générateur Yeoman, nous vous recommandons de désinstaller ce package si vous décidez d’utiliser des composants Fabric et de réduire la taille de votre paquet de composants.

npm uninstall @microsoft/sp-office-ui-fabric-core --save

Vous pouvez ensuite importer les styles Core à partir des déclarations Sass disponibles dans le package Fabric React.

@import '~office-ui-fabric-react/dist/sass/_References.scss';

Comprendre cette approche et ses défauts :

Dans votre solution, les composants Fabric sont verrouillés sur la version spécifique de Fabric React que vous avez installée. Mettez à jour le package Fabric React pour obtenir de nouveaux composants s’ils sont disponibles dans une version plus récente du package. Comme les composants Fabric sont inclus dans le paquet de composants, la taille de votre paquet de composants peut augmenter. Cependant, cette approche est la seule officiellement prise en charge en cas d’utilisation d’Office UI Fabric React dans les solutions SharePoint Framework.

Difficultés liées aux styles CSS avec Office UI Fabric

Les références et concepts suivants fournissent des informations sur les difficultés liées à l’utilisation d’Office UI Fabric dans le contexte de composants WebPart côté client.

Styles CSS globaux

Se passer des styles CSS globaux à tout prix représente un véritable problème. Aujourd’hui, Fabric Core et Fabric React contiennent des styles globaux. L’absence de solution native dans le navigateur pour gérer l’étendue des styles complique le problème.

  • L’étendue CSS n’en est qu’à ses prémices.
  • Les iFrames ne représentent pas une bonne option pour isoler les styles.
  • Les composants web fournissent une autre solution aux styles inclus dans l’étendue, mais ils sont toujours sur la table des discussions.
  • La présentation React: CSS in JS explique clairement ce problème.

De nombreux documents existent sur le web sur les solutions aux dangers de l’espace de noms global.

Spécificité CSS

La spécificité CSS s’applique à l’interface utilisateur web. Les styles de spécificité supérieure remplacent les styles de spécificité inférieure. Il est important de comprendre comment s’appliquent ces règles de spécificité. En règle générale, l’ordre de priorité est le suivant :

  • L’attribut de style (par exemple, style="background:red;")
  • Les sélecteurs d’ID (#myDiv { })
  • Les sélecteurs de classes (.myCssClass{}), les sélecteurs d’attributs ([type="radio"]) et les pseudo-classes (:hover)
  • Les sélecteurs de types (h1)

Ordre de chargement : si deux classes sont appliquées sur un élément et présentent la même spécificité, la classe chargée en dernier est prioritaire. Comme illustré dans le code suivant, le bouton s’affiche en rouge. Si l’ordre des balises de style est modifié, le bouton s’affiche en vert. Ce concept est important. S’il n’est pas utilisé correctement, l’expérience utilisateur peut devenir dépendante de l’ordre de chargement, et donc incohérente.

<style>
  .greenButton { color: green; }
</style>
<style>
  .redButton { color: red; }
</style>
<body>
  <button class="greenButton redButton"></button>
</body>

Autres approches envisagées et abandonnées

Voici quelques informations supplémentaires concernant les autres approches envisagées mais abandonnées, car elles n’ont pas atteint les objectifs clés permettant aux développeurs tiers d’utiliser de façon sûre les styles Office UI Fabric.

Office UI Fabric Core

Le développeur de composants WebPart n’aura aucune opération explicite à effectuer pour faire fonctionner l’étendue. Nous prévoyons de résoudre ce problème grâce à la spécificité CSS et au sélecteurs de descendants. L’équipe Fabric Core fournira plusieurs copies de Fabric Core css (par exemple fabric-6.css, fabric-6-scoped.css, fabric-6.0.0.css, fabric-6.0.0-scoped.css).

Tous les styles des fichiers CSS inclus dans l’étendue seront à l’intérieur d’un sélecteur de descendants, par exemple .ms-Fabric--v6-0-0 .ms-Icon--List. Au moment de la compilation, les outils collecteront la version d’Office UI Fabric Core utilisée pour la création du composant WebPart. Cette version pourra être l’une de celles fournies avec SharePoint Framework. Par ailleurs, les développeurs de composants WebPart pourront spécifier une dépendance explicite sur une version spécifique d’Office UI Fabric Core dans le fichier package.json.

Cette étendue sera affectée à la balise div du composant WebPart, soit <div data-sp-webpart class="ms-Fabric--v6-0-0">. SharePoint Framework chargera la version majeure spécifique du fichier CSS inclus dans l’étendue Fabric Core. Si le composant WebPart est créé avec la version 6.0.0 du fichier CSS Fabric Core, SharePoint Framework téléchargera fabric-6-scoped.css pendant le chargement du composant WebPart.

Le reste de la page contiendra les styles Office UI Fabric Core hors étendue. Ainsi, le fichier CSS inclus sera prioritaire dans la balise div du composant WebPart, conformément aux règles de spécificité de CSS. Le composant WebPart et son contenu s’aligneront sur une version spécifique d’Office UI Fabric Core choisie par le développeur.

Le remplacement des styles Fabric Core ne serait pas pris en charge.

// Sample of how the scoping would work.
import { SPComponentLoader } from '@microsoft/sp-loader';

export default class MyWebPart {
    constructor() {
        super();

        SPComponentLoader.loadCss('https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/6.0.0/css/fabric-6.0.0.scoped.css');
    }
}

protected render(): void {
  <div className="ms-Fabric--v6-0-0">
    { // Rest of the web part UI }
  </div>
}

Lacunes de cette stratégie

Après analyse de cette stratégie, il a été décidé que l’approche du sélecteur de descendants présente deux défauts qui empêchent de générer un composant WebPart sans futur dysfonctionnement potentiel.

Absence de prise en charge fiable pour l’imbrication

Cette approche fonctionne uniquement si l’expérience utilisateur Microsoft (composants WebPart internes et de page) utilise la version hors étendue d’Office UI Fabric Core (par exemple, ms-Icon--List) et que les composants WebPart tiers utilisent uniquement le fichier CSS Office UI Fabric Core inclus dans l’étendue comme expliqué précédemment.

En effet, la spécificité du fichier CSS inclus dans l’étendue appliquée sur le composant WebPart remplace le fichier CSS hors étendue sur la page. N’oubliez pas que si la spécificité CSS des deux classes est la même, leur ordre de chargement joue un rôle dans la façon dont les classes CSS sont appliquées. La classe chargée en dernier est prioritaire. Par conséquent, la spécificité la plus élevée du CSS inclus dans l’étendue est importante pour obtenir une expérience cohérente.

Par ailleurs, plusieurs extensions, l’une contenue dans l’autre, ne peuvent pas utiliser différentes versions de Fabric Core. Dans l’exemple suivant, seule la classe ms-Fabric--v6-0-0 est appliquée :

<div className="ms-Fabric--v6-0-0">
  { // Rest of the web part UI }
    { // inside of this SPExtension trying to use different Fabric core version does not work }
    <div className="ms-Fabric--v8-0-0">
    </div>
</div>

Voici un exemple plus simple montrant la difficulté :

<html>
<head>
  <title>CSS specifity test</title>
  <style>
  .myButton {
      background-color: brown;
      color: brown;
      height: 20px;
      width: 40px;
  }
  </style>
  <style>
  .scope2 .myButton {
      background-color: green;
      color: green;
  }
  </style>
  <style>
  .scope3 .myButton {
      background-color: yellow;
      color: yellow;
  }
  </style>
  <style>
  .scope1 .myButton {
      background-color: red;
      color: red;
  }
  </style>
</head>
<body>
  <div>
    <span>These tests demonstrate descendant selectors, nesting and load order problems.</span>

    <div>
      <br/>
      <span>This test depicts that a descendant selector with the same specificity does not allow nesting.
      All buttons below do not take the innermost scope (i.e. they should be different colors), but they are all red.
      Further, if you change the ordering of the style tags, the colors will change. (i.e. the UI is load order dependant.)</span>
      <div class='scope1'>
        <button class='myButton'</button>
        <div class='scope2'>
          <button class='myButton'></button>
          <div class='scope3'>
            <button class='myButton'></button>
          </div>
        </div>
      </div>
    </div>
  </div>
</body>
</html>

Fuite de classes hors étendue

Les sélecteurs de descendants présentent un autre problème. Dans l’exemple précédent, les styles de hauteur et de largeur issus de la classe myButton hors étendue sont appliqués à tous les boutons. Cela implique qu’une modification apportée à ce style peut entraîner une défaillance accidentelle du code HTML en utilisant les marques incluses dans l’étendue.

Supposons, par exemple, que pour une raison quelconque, nous décidons de définir la hauteur sur 0 px dans la classe myButton au niveau de l’application. Résultat : tous les composants WebPart tiers utilisant la classe myButton ont une hauteur de 0 px (impact très négatif sur l’expérience utilisateur).

Utilisation de façon sécurisée des styles Office UI Fabric (après SPFx v1.8.2)

Importante

Les conseils suivants s’appliquent à SharePoint Framework >= 1.8.2

Assurez-vous que le manifeste de composant WebPart demande le chargement des styles Fabric Core sur la page. Cette opération s’effectue en spécifiant loadLegacyFabricCss: true dans le manifeste de solution.

Avant la publication de SPFx v1.8.2, un bogue de page hôte était présent lorsque les styles Fabric Core hérités étaient chargés sans étendue. Par conséquent, si une autre solution demandait les styles, toutes les autres solutions sur la page pouvaient alors les utiliser. Ceci entraînait un fonctionnement « par chance » des solutions lorsqu’elles n’étaient pas rendues en isolation.

Pour régler ce bogue, les styles étaient étendus à la classe .ms-SPLegacyFabricBlock et appliqués aux solutions SPFx qui demandent le chargement de la feuille de style Fabric Core. Pour fournir un chemin d’accès de migration pour les solutions dépendant de l’effet secondaire ci-dessus, la classe .ms-SPLegacyFabricBlock est appliquée à tous les <div> s’exposant à des solutions tierces. Pendant cette période, modifiez la ou les solutions affectées pour déclarer la dépendance sur les styles Fabric Core hérités.

Importante

Finalement, la référence explicite à .ms-SPLegacyFabricBlocksera supprimée du DOM pour les solutions qui ne déclarent pas leur dépendance. Cette modification sera largement communiquée via les canaux existants avant la suppression de cette classe.

Dans l’hypothèse d’une solution fonctionnant dans des éléments Document Object Model qui ne sont pas fournis par le SPFx (lequel n’est généralement pas pris en charge), vous devez appliquer la classe .ms-SPLegacyFabricBlock vous-même.

Utilisation des icônes d’Office UI Fabric dans des composants SPFx

Des modifications ont été apportées à l’utilisation des icônes d’Office UI Fabric dans le rendu des solutions SharePoint Framework depuis SharePoint Framework v1.8.2.

Méthode héritée d’utilisation des icônes (avant SPFx 1.8.2)

<i className={css('ms-Icon', 'ms-Icon--RecurringEvent')}></i>

Méthode mise à jour d’utilisation des icônes (après SPFx 1.8.2)

Solutions générées sans option d’infrastructure JavaScript.

  1. Ajouter un package @uifabric/styling à votre package.json
  2. Apportez des modifications similaires au code ci-dessous pour obtenir l’icône requise dans votre code :
import { getIconClassName } from '@uifabric/styling';

return `<i class="${getIconClassName('Mail')}" />`;

Solutions générées avec l’option Reactréagir ou à l’aide de React en général.

  1. Ajoutez un package office-ui-fabric-react à votre package.json si ce n’est déjà fait.
  2. Apportez des modifications similaires au code ci-dessous pour obtenir l’icône requise dans votre code :
import { Icon } from 'office-ui-fabric-react/lib/Icon';

<Icon iconName='Mail' />

Voir aussi