Moduli SASS

Questo articolo spiega i moduli SASS.

Spieghiamo come modularizzare SASS usando @use e @forward, e come riutilizzare variabili, mixin, funzioni, impostazioni di tema e API pubbliche.

YouTube Video

Moduli SASS

Il sistema di moduli di SASS aiuta a delimitare chiaramente gli stili e offre una struttura facile da riutilizzare e mantenere.

Concetti base dei moduli

I moduli SASS risolvono i problemi di inquinamento dello spazio dei nomi globale e dipendenze poco chiare che erano presenti con il vecchio @import. Ogni file viene caricato come modulo con un proprio namespace, e solo gli elementi esplicitamente esportati sono accessibili dagli altri file.

Esempio di struttura dei file

Innanzitutto, ecco un esempio di una struttura di progetto realistica. Di seguito un esempio di un piccolo sistema di 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

• Questa struttura facilita la modularizzazione, così come il testing e la sostituzione delle parti.
• I file parziali hanno un underscore all'inizio del nome file.

Basi di @use

@use carica un modulo e fornisce un namespace. Questo previene collisioni di nomi e chiarisce il modulo di origine.

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

• Questo file è semplice e definisce solo variabili. Le variabili pubblicate da un modulo possono essere referenziate direttamente usando @use.

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

• Qui, il modulo variables viene referenziato con il namespace variables.. Questo approccio rende chiara l'origine di ogni elemento.

Abbreviare o dare alias ai namespace

L'uso di as consente di abbreviare il namespace.

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

• Ecco un esempio di importazione di variables usando l'alias più breve vars. Scegli i nomi in base a se dai priorità alla leggibilità o alla facilità di digitazione.

Definizione di Mixin

Anche i mixin e le funzioni possono essere definiti e utilizzati all'interno dei moduli. Mantenere i commenti coerenti con le convenzioni del progetto aiuta la chiarezza.

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}

• Questo file definisce un mixin per i container. Accetta argomenti e fornisce valori predefiniti.

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

• Questo è un esempio di utilizzo di un mixin con @include.

Definizione di funzioni

Le funzioni vengono utilizzate per restituire valori e possono essere definite e riutilizzate all'interno dei moduli. Racchiudendo i calcoli dei valori di design nelle funzioni, gli stili diventano più stabili e facili da mantenere.

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}

• Questo file definisce una funzione che converte i valori in pixel in rem. Viene anche specificato un valore base predefinito.

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

• Ecco un esempio di come chiamare una funzione tramite @use e applicare il risultato a uno stile.

Esportazione dei moduli e @forward (progettazione API)

Quando vuoi esporre più file interni all'esterno, puoi usare @forward per creare una 'API pubblica'.

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

• Più file interni possono essere raggruppati come un unico punto di ingresso, che fornirà la API pubblica. Questo consente agli utenti di accedere a tutte le funzionalità necessarie importando solo un punto di ingresso.

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

• I contenuti di variables e mixins sono accessibili collettivamente tramite index. @forward rende index il livello pubblico.

Controllo dell'API con le opzioni show / hide di @forward

Se vuoi esporre solo specifiche variabili, utilizza l'opzione show o hide.

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

• L'aggiunta di !default ti permette di pubblicare un valore che può essere sovrascritto.

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

• Usando show con @forward, puoi limitare l'API esposta solo agli elementi necessari. Variabili e funzioni usate internamente non saranno visibili dall'esterno.

Rendere i moduli configurabili (con with)

Se usi !default nel modulo, i valori possono essere sovrascritti usando with lato importazione.

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 modulo con valori predefiniti definiti tramite !default può accettare configurazioni tramite 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}

• with in @use consente di sovrascrivere le variabili predefinite di un modulo al momento dell'importazione. Questo è utile per il cambio del tema.
• Nota che with ha effetto solo al momento dell'importazione e non puoi modificare quei valori in seguito.

Esempio pratico: componente bottone (esempio completo)

Proviamo a progettare stili per i bottoni usando i moduli. Per prima cosa, separa variabili e mixin in moduli distinti.

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;

• Le variabili predefinite per i bottoni sono definite qui. L'uso di !default consente agli utenti di sovrascrivere questi valori.

 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}

• Il mixin base per i bottoni è definito qui. Sono separati per favorirne il riutilizzo.

 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}

• Gli stili dei bottoni sono creati usando riferimenti di namespace con @use. Una variante viene definita come .button--large.

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

• Importando il modulo button, puoi usare subito gli stili dei bottoni.

Cambio del tema (utilizzo di più file tema)

Il cambio del tema può essere effettuato mediante configurazione tramite with oppure creando moduli separati e cambiando quale viene usato con @use.

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

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

• Definisci i colori del brand e altre impostazioni in diversi file tema e cambiali durante la build o l'importazione.

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

• Scegli il tema utilizzando with o importando, ad esempio, @use 'themes/light' durante il processo di build.

Privato e pubblico (prefisso _ e !default)

In SASS, aggiungere un trattino basso all'inizio del nome di un file lo contrassegna come parziale. Tuttavia, per gestire la visibilità dell'esportazione dei moduli, usa show e hide con @forward per controllare cosa viene esportato.

Puoi usare @forward per organizzare l'API pubblica e nascondere le implementazioni interne dall'esterno.

Best practice per l'uso reale

Di seguito sono riportati alcuni concetti di base utili quando si utilizza SASS in situazioni pratiche. Tutte queste linee guida aiutano a ridurre la confusione durante lo sviluppo e a mantenere il codice organizzato.

• Se è probabile che alcune variabili cambino come parte di un tema, aggiungi !default. Questo facilita agli utenti la sovrascrittura dei valori.
• I moduli dovrebbero essere divisi per responsabilità e focalizzati su uno scopo unico. Diventa più facile da gestire separando variabili, mixin e componenti.
• Gestisci i contenuti pubblici con @forward e usa show o hide se necessario. Definire l'ambito di ciò che è pubblico porta a un design più sicuro.
• Usa i namespace per rendere chiaro a quale modulo appartiene ogni funzione. Questo evita confusione con altri codici.
• Ricorda che with funziona solo al momento di @use. Dato che non puoi cambiarli successivamente, imposta le configurazioni al momento dell'importazione.
• Aggiungi un underscore all'inizio dei nomi file per renderli parziali, così non vengono compilati singolarmente. Questo rende più facile combinare i file in una struttura più grande.
• Includere esempi di utilizzo nel modulo index aiuta per il testing e la documentazione. Diventa più facile per gli utenti comprendere il comportamento.

Tenendo a mente questi punti, ti sarà più facile gestire grandi progetti e mantenere codice leggibile come team.

Riepilogo

Il sistema di moduli SASS organizza il codice degli stili tramite spazi dei nomi, API pubbliche e configurazione semplificata. Utilizzare abilmente @use e @forward rende più facile lo sviluppo in team, il cambio di tema e la progettazione di librerie.

Puoi seguire l'articolo sopra utilizzando Visual Studio Code sul nostro canale YouTube. Controlla anche il nostro canale YouTube.

YouTube Video