Partager via

Recommandations concernant l’utilisation de feuilles CSS dans les solutions SharePoint Framework

  • Article

Quand vous générez des solutions SharePoint Framework, vous pouvez utiliser CSS pour définir l’apparence et le comportement de votre personnalisation. Cet article vous explique comment tirer le meilleur parti des fonctionnalités fournies par SharePoint Framework et générer des styles CSS fiables.

Les personnalisations SharePoint Framework font partie de la page

Quand vous générez des personnalisations SharePoint à l’aide du modèle de complément, la solution est isolée des autres éléments de la page. Votre code peut être exécuté dans un iFrame comme un composant de complément ou comme une application immersive qui prend le contrôle de toute la page. Dans les deux cas, votre code n’est pas affecté par d’autres éléments et styles définis sur la page.

Les solutions SharePoint Framework représentent un composant de la page et s’intègrent entièrement dans le DOM de la page. Même si cela supprime un certain nombre de restrictions propres au modèle de complément, votre solution court un risque. Comme la solution représente un composant de la page, sauf si elle a été explicitement isolée, tous les styles CSS présents sur la page s’y appliquent, ce qui peut générer une expérience différente de celle attendue. Pour éviter cela, définissez vos styles CSS pour qu’ils affectent uniquement vos personnalisations.

Organisation des fichiers CSS dans votre solution

L’interface utilisateur de vos solutions comprend souvent plusieurs blocs de construction. Dans de nombreuses bibliothèques JavaScript, ces blocs de construction sont appelés « composants ». Un composant peut être simple et définir uniquement la présentation, ou être plus complexe et inclure des états et d’autres composants. Le fait de fractionner votre solution en plusieurs composants vous permet de simplifier le processus de développement, et de tester et de réutiliser facilement les composants dans votre solution.

Comme les composants définissent la présentation, ils nécessitent souvent des styles CSS. Dans l’idéal, les composants doivent être isolés et pouvoir être utilisés de manière indépendante. Dans cette optique, il est parfaitement logique de stocker les styles CSS pour un composant donné, ainsi que tous les autres fichiers de ressources, à côté du composant. Vous trouverez ci-dessous un exemple de structure d’une application React comprenant plusieurs composants qui comportent tous leur propre fichier CSS.

todoWebPart\components
                      \todoList
                               \todoList.tsx
                               \todoList.module.scss
                      \todoItem
                               \todoItem.tsx
                               \todoItem.module.scss

Utilisation de Sass

Dans SharePoint Framework, vous pouvez utiliser CSS et Sass. Sass est un sur-ensemble de feuilles CSS qui vous offre de nombreuses fonctionnalités, telles que l’utilisation de variables, l’imbrication de sélecteurs ou l’utilisation de mixins, pour simplifier l’utilisation et la gestion des styles CSS sur le long terme.

Pour connaître toutes les fonctionnalités disponibles, consultez lesite web de Sass. Toutes les feuilles valides en CSS le sont également en Sass, ce qui peut être utile si vous n’avez jamais travaillé avec Sass et souhaitez découvrir progressivement ses fonctionnalités.

Utilisation des ID dans les marques de révision non recommandée

Avec SharePoint Framework, vous générez des personnalisations que les utilisateurs finals ajoutent à SharePoint. Il est impossible de savoir à l’avance si une personnalisation donnée est utilisée une ou plusieurs fois sur une page.

Pour éviter tout problème, partez du principe que votre personnalisation est utilisée plusieurs fois sur la même page. Dans cette optique, évitez également d’utiliser des ID dans vos marques de révision. Les ID sont censés être utilisés une seule fois sur une page. Si un utilisateur ajoute votre composant WebPart deux fois sur la page, il ne respecte pas cette règle, pouvant ainsi entraîner des erreurs.

Déconseillé

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div id="helloWorld">
        Hello world
      </div>`;
  }

  // ...
}

Recommandé

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

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

  // ...
}

Utilisation des modules CSS permettant d’éviter les conflits de style

SharePoint Framework solutions font partie de la page. Pour vous assurer que les styles CSS d’un composant n’affectent pas les autres éléments de la page, vous devez définir vos sélecteurs CSS de manière à ce qu’ils s’appliquent uniquement au DOM de votre solution. Il est fastidieux et source d’erreurs de le faire manuellement, mais SharePoint Framework pouvez le faire automatiquement pour vous.

Pour éviter les conflits de style, SharePoint Framework utilise les modules CSS. Pendant la génération du projet, la chaîne d’outils SharePoint Framework traite tous les fichiers ayant l’extension .module.scss. Pour chaque fichier, elle lit tous les sélecteurs de classe et leur ajoute une valeur de hachage unique. Ensuite, elle écrit les sélecteurs mis à jour dans des fichiers CSS intermédiaires qui sont inclus dans l’ensemble de composants WebPart généré.

Comme dans l’exemple précédent, supposons que vous avez les deux fichiers Sass suivants :

todoList.module.scss

.todoList {
  margin: 1em 0;

  .text {
    font-weight: bold;
    font-size: 1.5em;
  }
}

todoItem.module.scss

.todoItem {
  padding: 0.5em 1em;

  .text {
    font-size: 0.9em;
  }
}

Une fois un projet créé, les deux fichiers CSS suivants seront générés dans le dossierlib (ajout de sauts de ligne et de retraits pour une meilleure lisibilité) :

todoList.module.css

.todoList_3e9d35f0 {
  margin:1em 0
}

.todoList_3e9d35f0 .text_3e9d35f0 {
  font-weight:700;
  font-size:1.5em
}

todoItem.module.css

.todoItem_f7081cc4 {
  padding:.5em 1em
}

.todoItem_f7081cc4 .text_f7081cc4 {
  font-size:.9em
}

Bien qu’une classe .text soit définie dans les deux fichiers Sass, notez que dans les fichiers CSS générés, deux codes de hachage différents ont été ajoutés pour créer un nom de classe unique propre à chaque composant.

Les noms des classes CSS dans les modules CSS sont générés dynamiquement, ce qui vous empêche d’y faire référence directement dans votre code. Au lieu de cela, lors du traitement des modules CSS, la chaîne d’outils SharePoint Framework génère un fichier JavaScript avec des références aux noms de classe générés.

todoList.module.scss.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
/* tslint:disable */
require('./todoList.module.css');
var styles = {
    todoList: 'todoList_3e9d35f0',
    text: 'text_3e9d35f0',
};
exports.default = styles;
/* tslint:enable */

//# sourceMappingURL=todoList.module.scss.js.map

Pour vous servir des noms de classe générés dans votre code, importez d’abord les styles de votre composant, puis utilisez la propriété désignant cette classe :

import styles from './todoList.module.scss';
// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        <div className={styles.text}>Hello world</div>
      </div>
    );
  }
}

Pour que les modules CSS fonctionnent correctement, les conditions suivantes doivent être remplies :

  • Vos fichiers Sass doivent porter l’extension . module.scss. Si vous utilisez l’extension .scss sans .module, un avertissement s’affiche dans le processus de génération. Le fichier Sass est transpilé en un fichier CSS intermédiaire, mais les noms de classe ne sont pas uniques. Si vous avez besoin de remplacer des styles CSS tiers, cela peut être volontaire.

  • Les noms de classe CSS doivent être des noms de variables JavaScript valides. Par exemple, ils ne peuvent pas contenir de traits d’union : todoList est correct, mais todo-list ne l’est pas.

  • Nous vous recommandons d’utiliser les appellations de classe en casse mixte, mais ceci n’est pas obligatoire.

Placer vos styles CSS dans une classe portant le nom du composant

En combinant des modules CSS avec un support Sass pour imbriquer des ensembles de règles, vous pouvez simplifier vos styles CSS et vérifier qu’ils n’affectent pas les autres éléments de la page.

Quand vous générez des styles CSS pour un composant, intégrez-les dans une classe portant le nom du composant. Ensuite, dans le composant, affectez cette classe à l’élément racine du composant.

todoList.module.scss

.todoList {
  a {
    display: block;
  }
}

TodoList.tsx

// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        ...
      </div>
    );
  }
}

Après la transpilation, le fichier CSS généré ressemble à ceci :

.todoList_3e9d35f0 a {
  display: block;
}

Étant donné que le sélecteur commence par le nom de classe unique propre à votre composant, la présentation alternative s’applique uniquement aux liens hypertexte présents à l’intérieur de votre composant.

Gestion du préfixe de fournisseur CSS

Dans SharePoint Framework, aucune propriété de style de préfixe de fournisseur n’est requise dans les fichiers Sass ou CSS d’un projet. Si certains navigateurs pris en charge par SharePoint Framework exigent des préfixes, ils ont été ajoutés automatiquement après la compilation de Sass en CSS. Cette méthode, également appelée « auto-prefixing » (préfixe automatique), fait partie intégrante de la chaîne de génération CSS dans SharePoint Framework.

Si un composant WebPart doit utiliser le nouveau modèle de boîte flexible définie par la déclaration display: flex, d’anciennes versions d’Internet Explorer basées sur le WebKit nécessitent un certain préfixe de fournisseur défini dans le fichier CSS.

.container{
  display: flex;
}

Le code Sass de l’artefact SharePoint Framework n’a pas besoin d’inclure des préfixes de fournisseur. Après la compilation Sass-CSS, ces préfixes ont été ajoutés automatiquement, générant la déclaration CSS suivante.

.container_7e976ae1 {
  display: -webkit-box; // older Safari on MacOS and iOS
  display: -ms-flexbox; // IE 10 - 11
  display: flex;
}

La suppression des préfixes déjà appliqués rend le code de l’artefact plus clair, plus facile à lire et évolutif. Ce processus est également configuré pour uniquement prendre en charge les navigateurs pris en charge par SharePoint Framework et le préserve d’autres erreurs.

Si des préfixes de fournisseur sont déjà inclus dans les fichiers Sass d’un composant WebPart alors qu’ils ne sont plus nécessaires, le même processus supprime automatiquement ces déclarations.

L’exemple suivant utilise la propriété border-radius, qui ne nécessite pas de préfixes de fournisseur sur les systèmes pris en charge.

.container {
  /* Safari 3-4, iOS 1-3.2, Android 1.6- */
  -webkit-border-radius: 7px;
  /* Firefox 1-3.6 */
  -moz-border-radius: 7px;
  /* Opera 10.5, IE 9, Safari 5, Chrome, Firefox 4, iOS 4, Android 2.1+ */
  border-radius: 7px;
}

Le fichier CSS obtenu dans le package est converti sous la forme du code suivant.

.container_9e54c0b0 {
  border-radius: 7px
}

Pour en savoir plus sur les préfixes automatiques, consultez le référentiel GitHub autoprefixer. La base de données de ce processus est disponible sur la page Can I use__?.

Intégration d’Office UI Fabric

En rendant l’apparence et le comportement de vos personnalisations semblables à la fonctionnalité standard de SharePoint et Office 365, vous permettez aux utilisateurs finals de les utiliser plus facilement. Office UI Fabric vous propose un ensemble de contrôles et de styles à utiliser dans vos personnalisations pour les intégrer de façon transparente avec l’expérience utilisateur existante.

Pour en savoir plus sur l’utilisation d’Office UI Fabric dans SharePoint Framework, consultez l’article Utilisation des structures d’interface utilisateur Office UI Fabric et Fabric React dans SharePoint Framework.

Utilisation des couleurs de thème

SharePoint permet aux utilisateurs de choisir la couleur de thème de leurs sites. Dans vos personnalisations SharePoint Framework, respectez le thème sélectionné par les utilisateurs pour que votre personnalisation se fonde dans le reste du site sans ressortir inutilement.

Étant donné que le thème est défini par les utilisateurs sur leur site, vous ne pouvez pas savoir à l’avance quelles couleurs utiliser pour votre personnalisation. Heureusement, SharePoint Framework peut charger le modèle de couleurs actif dynamiquement et automatiquement.

Pour en savoir plus sur cette fonctionnalité, consultez l’article Utilisation des couleurs de thème dans vos personnalisations SharePoint Framework.