Modules SASS

Cet article explique les modules SASS.

Nous expliquons comment modulariser SASS en utilisant @use et @forward, et comment réutiliser des variables, des mixins, des fonctions, des paramètres de thème et des API publiques.

YouTube Video

Modules SASS

Le système de modules de SASS permet de définir clairement la portée des styles et offre une conception facile à réutiliser et à maintenir.

Concepts de base des modules

Les modules SASS résolvent les problèmes de pollution globale de l’espace de noms et de dépendances peu claires qui existaient avec l'ancien @import. Chaque fichier est chargé comme un module avec son propre espace de noms, et seuls les éléments explicitement exportés sont accessibles depuis d’autres fichiers.

Exemple de structure de fichiers

Tout d’abord, voici un exemple de structure de projet réaliste. Voici un exemple d’un petit système de design.

 1styles/
 2├─ _variables.scss
 3├─ _mixins.scss
 4├─ _functions.scss
 5├─ components/
 6│  ├─ _button.scss
 7│  └─ _card.scss
 8├─ utilities/
 9│  └─ _helpers.scss
10└─ main.scss

• Cette structure facilite la modularisation ainsi que les tests et le remplacement des parties.
• Les fichiers partiels commencent par un trait de soulignement dans leur nom.

Bases de @use

@use charge un module et fournit un espace de noms. Cela évite les conflits de noms et clarifie le module source.

1// _variables.scss
2$primary-color: #0a74da;
3$padding-base: 12px;

• Ce fichier est simple et ne définit que des variables. Les variables publiées depuis un module peuvent être référencées directement via @use.

1// main.scss
2@use 'variables';
3
4.example {
5  color: variables.$primary-color;
6  padding: variables.$padding-base;
7}

• Ici, le module variables est référencé avec l’espace de noms variables.. Cette approche permet de clarifier l’origine de chaque élément.

Raccourcir ou créer des alias pour les espaces de noms

L’utilisation de as permet de raccourcir l’espace de noms.

1@use 'variables' as vars;
2
3.btn {
4  color: vars.$primary-color;
5}

• Voici un exemple d’importation de variables en utilisant l’alias plus court vars. Choisissez les noms en fonction de la priorité donnée à la lisibilité ou à la facilité de saisie.

Définition d’un mixin

Les mixins et fonctions peuvent également être définis et utilisés dans des modules. Des commentaires cohérents avec les conventions du projet favorisent la clarté.

1// _mixins.scss
2// Create a simple responsive container mixin
3@mixin container($max-width: 1200px) {
4  width: 100%;
5  margin-left: auto;
6  margin-right: auto;
7  max-width: $max-width;
8}

• Ce fichier définit un mixin pour les conteneurs. Il prend des arguments et fournit des valeurs par défaut.

1// main.scss
2@use 'mixins' as m;
3
4.wrapper {
5  @include m.container(1000px);
6}

• Voici un exemple d’utilisation d’un mixin avec @include.

Définition de fonctions

Les fonctions sont utilisées pour retourner des valeurs et peuvent être définies et réutilisées dans des modules. En encapsulant les calculs des valeurs de conception dans des fonctions, les styles deviennent plus stables et plus faciles à maintenir.

1// _functions.scss
2@use 'sass:math';
3
4// Create a simple px-to-rem converter function
5@function to-rem($px, $base: 16) {
6  @return math.div($px, $base) * 1rem;
7}

• Ce fichier définit une fonction qui convertit des valeurs en pixels en rem. Une valeur de base par défaut est également spécifiée.

1// main.scss
2@use 'functions' as f;
3
4.title {
5  font-size: f.to-rem(24);
6}

• Voici un exemple d’appel d’une fonction via @use et d’application du résultat à un style.

Exportation de module et @forward (Conception d’API)

Lorsque vous souhaitez exposer plusieurs fichiers internes à l’extérieur, vous pouvez utiliser @forward pour créer une « API publique ».

1// _index.scss (module entry)
2@forward 'variables';
3@forward 'mixins';
4@forward 'functions';

• Plusieurs fichiers internes peuvent être regroupés via un unique point d’entrée, qui fournit alors l’API publique. Cela permet aux utilisateurs d’accéder à toutes les fonctionnalités requises en important un seul point d’entrée.

1// main.scss
2@use 'index' as ds; // ds = design system
3
4.button {
5  color: ds.$primary-color;
6  @include ds.container();
7}

• Le contenu de variables et mixins est accessible collectivement via le fichier index. @forward fait de index la couche publique.

Contrôler l’API avec les options show / hide de @forward

Si vous souhaitez n’exposer que certaines variables, utilisez les options show ou hide.

1// _variables.scss
2$internal-thing: 10px !default; // for internal use
3$primary-color: #0a74da !default;
4$secondary-color: #f5f5f5 !default;

• Ajouter !default permet de publier une valeur qui peut être surchargée.

1// _index.scss
2@forward 'variables' show $primary-color, $secondary-color;
3@forward 'mixins';

• En utilisant show avec @forward, vous pouvez limiter l’API exposée aux seuls éléments nécessaires. Les variables et fonctions utilisées en interne ne seront pas visibles de l’extérieur.

Rendre les modules configurables (avec with)

Si vous utilisez !default dans le module, les valeurs peuvent être surchargées avec with lors de l’import.

1// _theme.scss
2$brand-color: #ff6600 !default;
3$radius: 4px !default;
4
5@mixin button-style() {
6  background-color: $brand-color;
7  border-radius: $radius;
8}

• Un module avec des valeurs par défaut définies par !default peut accepter des configurations via with.

1// main.scss
2@use 'theme' with (
3  $brand-color: #2288ff,
4  $radius: 8px
5);
6
7.my-btn {
8  @include theme.button-style();
9}

• L’option with dans @use permet de surcharger les variables par défaut d’un module lors de l’importation. Cela est utile pour le changement de thème.
• Notez que with n’a d’effet qu’au moment de l’import et que vous ne pourrez plus changer ces valeurs par la suite.

Exemple pratique : composant bouton (exemple complet)

Essayons de concevoir des styles de boutons en utilisant des modules. Commencez par séparer les variables et les mixins dans leurs propres modules.

1// _variables.scss
2$btn-padding-y: 8px !default;
3$btn-padding-x: 16px !default;
4$btn-font-size: 14px !default;
5$btn-primary-bg: #0a74da !default;
6$btn-primary-color: #fff !default;

• Les variables par défaut des boutons sont définies ici. L’utilisation de !default permet aux utilisateurs de surcharger ces valeurs.

 1// _mixins.scss
 2@use "variables" as v;
 3
 4@mixin btn-base() {
 5  display: inline-flex;
 6  align-items: center;
 7  justify-content: center;
 8  padding: v.$btn-padding-y v.$btn-padding-x;
 9  font-size: v.$btn-font-size;
10  border: none;
11  cursor: pointer;
12}

• Le mixin de base pour les boutons est défini ici. Ils sont séparés pour faciliter leur réutilisation.

 1// _button.scss
 2@use 'variables' as v;
 3@use 'mixins' as m;
 4
 5.button {
 6  @include m.btn-base();
 7  background: v.$btn-primary-bg;
 8  color: v.$btn-primary-color;
 9  border-radius: 4px;
10  transition: opacity 0.15s ease;
11  &:hover { opacity: 0.9; }
12}
13
14.button--large {
15  padding: calc(v.$btn-padding-y * 1.5) calc(v.$btn-padding-x * 1.5);
16  font-size: v.$btn-font-size * 1.25;
17}

• Les styles des boutons sont créés à l’aide de références d’espace de noms avec @use. Une variante est définie en tant que .button--large.

1// main.scss
2@use 'button'; // or @use 'index' that forwards button, variables, mixins

• En important le module button, vous pouvez immédiatement utiliser les styles de boutons.

Changement de thème (utilisation de plusieurs fichiers de thème)

Le changement de thème peut se faire via la configuration avec with ou en créant des modules séparés et en modifiant celui utilisé avec @use.

1// themes/_light.scss
2$brand-color: #0a74da !default;

1// themes/_dark.scss
2$brand-color: #111827 !default;

• Définissez les couleurs de marque et autres paramètres dans plusieurs fichiers de thème et changez-les lors de la compilation ou de l’import.

1// main.scss (light theme)
2@use 'theme' with ($brand-color: #0a74da);
3@use 'button';

• Choisissez le thème soit via with, soit en important, par exemple, @use 'themes/light' lors du processus de compilation.

Privé et public (préfixe _ et !default)

Dans SASS, l’ajout d’un underscore au début du nom d’un fichier l’identifie comme une partial. Cependant, pour gérer la visibilité de l’export de modules, utilisez show et hide avec @forward pour contrôler ce qui est exporté.

Vous pouvez utiliser @forward pour organiser l’API publique et masquer les implémentations internes.

Bonnes pratiques pour une utilisation concrète

Voici quelques concepts de base utiles lors de l’utilisation de SASS dans des situations pratiques. Toutes ces recommandations contribueront à réduire la confusion pendant le développement et à organiser votre code.

• Si des variables sont susceptibles de changer dans le cadre d’un thème, ajoutez !default. Cela facilite la surcharge des valeurs par les utilisateurs.
• Les modules doivent être divisés par responsabilité et axés sur un objectif unique. La gestion devient plus facile en séparant les variables, les mixins, et les composants.
• Gérez les contenus publics avec @forward et utilisez show ou hide selon les besoins. Définir la portée de ce qui est public conduit à une conception plus sûre.
• Utilisez les espaces de noms pour clarifier à quel module appartient chaque fonction. Cela évite toute confusion avec d’autres codes.
• Rappelez-vous que with ne fonctionne qu’au moment de @use. Puisque vous ne pouvez pas les modifier ensuite, définissez la configuration au moment de l’import.
• Utilisez un trait de soulignement en début de nom de fichier pour en faire des partiels, afin qu’ils ne soient pas compilés individuellement. Cela facilite la combinaison de fichiers dans une structure plus large.
• Inclure des exemples d’utilisation dans le module index aide aux tests et à la documentation. Les utilisateurs comprennent alors plus facilement le comportement.

En gardant ces points à l’esprit, vous pourrez gérer de grands projets et maintenir un code lisible en équipe.

Résumé

Le système de modules SASS organise le code des styles via des espaces de noms, des API publiques et une configuration simplifiée. Bien utiliser @use et @forward facilite grandement le travail en équipe, le changement de thème et la conception de bibliothèques.

Vous pouvez suivre l'article ci-dessus avec Visual Studio Code sur notre chaîne YouTube. Veuillez également consulter la chaîne YouTube.

YouTube Video