API di utilità

L'API di utilità è uno strumento basato su Sass per generare classi di utilità.

Su questa pagina

Le utilità Bootstrap sono generate con la nostra API di utilità e possono essere utilizzate per modificare o estendere il nostro set predefinito di classi di utilità tramite Sass. La nostra utility API si basa su una serie di mappe e funzioni Sass per la generazione di famiglie di classi con varie opzioni. Se non hai dimestichezza con le mappe di Sass, leggi i documenti ufficiali di Sass per iniziare.

La $utilitiesmappa contiene tutte le nostre utilità e viene successivamente unita alla tua $utilitiesmappa personalizzata, se presente. La mappa delle utilità contiene un elenco con chiave di gruppi di utilità che accettano le seguenti opzioni:

Opzione	Tipo	Valore di default	Descrizione
`property`	Necessario	–	Nome della proprietà, può essere una stringa o un array di stringhe (ad es. spaziatura interna o margini).
`values`	Necessario	–	Elenco di valori o una mappa se non si desidera che il nome della classe sia uguale al valore. Se `null`viene utilizzato come chiave della mappa, `class`non viene anteposto al nome della classe.
`class`	Opzionale	nullo	Nome della classe generata. Se non viene fornito ed `property`è un array di stringhe, `class`verrà impostato automaticamente il primo elemento `property`dell'array. Se non viene fornito ed `property`è una stringa, le `values`chiavi vengono utilizzate per i `class`nomi.
`css-var`	Opzionale	`false`	Booleano per generare variabili CSS invece delle regole CSS.
`css-variable-name`	Opzionale	nullo	Nome personalizzato senza prefisso per la variabile CSS all'interno del set di regole.
`local-vars`	Opzionale	nullo	Mappa delle variabili CSS locali da generare in aggiunta alle regole CSS.
`state`	Opzionale	nullo	Elenco di varianti di pseudo-classi (ad es. `:hover`o `:focus`) da generare.
`responsive`	Opzionale	`false`	Booleano che indica se devono essere generate classi reattive.
`rfs`	Opzionale	`false`	Booleano per abilitare il rescaling fluido con RFS .
`print`	Opzionale	`false`	Booleano che indica se è necessario generare classi di stampa.
`rtl`	Opzionale	`true`	Booleano che indica se l'utilità deve essere mantenuta in RTL.

Spiegazione dell'API

Tutte le variabili di utilità vengono aggiunte alla $utilitiesvariabile all'interno del nostro _utilities.scssfoglio di stile. Ogni gruppo di utilità ha un aspetto simile a questo:

$utilities: (
  "opacity": (
    property: opacity,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Che produce quanto segue:

.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

Proprietà

La propertychiave richiesta deve essere impostata per qualsiasi utilità e deve contenere una proprietà CSS valida. Questa proprietà viene utilizzata nel set di regole dell'utilità generata. Quando la classchiave viene omessa, funge anche da nome di classe predefinito. Considera l' text-decorationutilità:

$utilities: (
  "text-decoration": (
    property: text-decoration,
    values: none underline line-through
  )
);

Produzione:

.text-decoration-none { text-decoration: none !important; }
.text-decoration-underline { text-decoration: underline !important; }
.text-decoration-line-through { text-decoration: line-through !important; }

I valori

Utilizzare la valueschiave per specificare quali valori per l'oggetto specificato propertydevono essere utilizzati nei nomi e nelle regole delle classi generate. Può essere una lista o una mappa (impostata nelle utilità o in una variabile Sass).

Come elenco, come con text-decorationle utilità :

values: none underline line-through

Come una mappa, come con opacityle utilità :

values: (
  0: 0,
  25: .25,
  50: .5,
  75: .75,
  100: 1,
)

Come variabile Sass che imposta l'elenco o la mappa, come nelle nostre positionutilità :

values: $position-values

Classe

Utilizzare l' classopzione per modificare il prefisso di classe utilizzato nel CSS compilato. Ad esempio, per passare da .opacity-*a .o-*:

$utilities: (
  "opacity": (
    property: opacity,
    class: o,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Produzione:

.o-0 { opacity: 0 !important; }
.o-25 { opacity: .25 !important; }
.o-50 { opacity: .5 !important; }
.o-75 { opacity: .75 !important; }
.o-100 { opacity: 1 !important; }

Se class: null, genera classi per ciascuna delle valueschiavi:

$utilities: (
  "visibility": (
    property: visibility,
    class: null,
    values: (
      visible: visible,
      invisible: hidden,
    )
  )
);

Produzione:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !important; }

Utilità delle variabili CSS

Imposta l' css-varopzione booleana su truee l'API genererà variabili CSS locali per il selettore specificato invece delle normali property: valueregole. Aggiungi un optional css-variable-nameper impostare un nome di variabile CSS diverso dal nome della classe.

Considera le nostre .text-opacity-*utilità. Se aggiungiamo l' css-variable-nameopzione, otterremo un output personalizzato.

$utilities: (
  "text-opacity": (
    css-var: true,
    css-variable-name: text-alpha,
    class: text-opacity,
    values: (
      25: .25,
      50: .5,
      75: .75,
      100: 1
    )
  ),
);

Produzione:

.text-opacity-25 { --bs-text-alpha: .25; }
.text-opacity-50 { --bs-text-alpha: .5; }
.text-opacity-75 { --bs-text-alpha: .75; }
.text-opacity-100 { --bs-text-alpha: 1; }

Variabili CSS locali

Utilizzare l' local-varsopzione per specificare una mappa Sass che genererà variabili CSS locali all'interno del set di regole della classe di utilità. Tieni presente che potrebbe essere necessario un lavoro aggiuntivo per utilizzare quelle variabili CSS locali nelle regole CSS generate. Ad esempio, considera le nostre .bg-*utilità:

$utilities: (
  "background-color": (
    property: background-color,
    class: bg,
    local-vars: (
      "bg-opacity": 1
    ),
    values: map-merge(
      $utilities-bg-colors,
      (
        "transparent": transparent
      )
    )
  )
);

Produzione:

.bg-primary {
  --bs-bg-opacity: 1;
  background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important;
}

stati

Utilizzare l' stateopzione per generare variazioni di pseudo-classe. Esempi di pseudo-classi sono :hovere :focus. Quando viene fornito un elenco di stati, i nomi delle classi vengono creati per quella pseudo-classe. Ad esempio, per modificare l'opacità al passaggio del mouse, aggiungi state: hovere otterrai .opacity-hover:hoveril tuo CSS compilato.

Hai bisogno di più pseudo-classi? Utilizzare un elenco di stati separati da spazi: state: hover focus.

$utilities: (
  "opacity": (
    property: opacity,
    class: opacity,
    state: hover,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Produzione:

.opacity-0-hover:hover { opacity: 0 !important; }
.opacity-25-hover:hover { opacity: .25 !important; }
.opacity-50-hover:hover { opacity: .5 !important; }
.opacity-75-hover:hover { opacity: .75 !important; }
.opacity-100-hover:hover { opacity: 1 !important; }

reattivo

Aggiungi il responsivebooleano per generare utilità reattive (ad es. .opacity-md-25) su tutti i punti di interruzione .

$utilities: (
  "opacity": (
    property: opacity,
    responsive: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Produzione:

.opacity-0 { opacity: 0 !important; }
.opacity-25 { opacity: .25 !important; }
.opacity-50 { opacity: .5 !important; }
.opacity-75 { opacity: .75 !important; }
.opacity-100 { opacity: 1 !important; }

@media (min-width: 576px) {
  .opacity-sm-0 { opacity: 0 !important; }
  .opacity-sm-25 { opacity: .25 !important; }
  .opacity-sm-50 { opacity: .5 !important; }
  .opacity-sm-75 { opacity: .75 !important; }
  .opacity-sm-100 { opacity: 1 !important; }
}

@media (min-width: 768px) {
  .opacity-md-0 { opacity: 0 !important; }
  .opacity-md-25 { opacity: .25 !important; }
  .opacity-md-50 { opacity: .5 !important; }
  .opacity-md-75 { opacity: .75 !important; }
  .opacity-md-100 { opacity: 1 !important; }
}

@media (min-width: 992px) {
  .opacity-lg-0 { opacity: 0 !important; }
  .opacity-lg-25 { opacity: .25 !important; }
  .opacity-lg-50 { opacity: .5 !important; }
  .opacity-lg-75 { opacity: .75 !important; }
  .opacity-lg-100 { opacity: 1 !important; }
}

@media (min-width: 1200px) {
  .opacity-xl-0 { opacity: 0 !important; }
  .opacity-xl-25 { opacity: .25 !important; }
  .opacity-xl-50 { opacity: .5 !important; }
  .opacity-xl-75 { opacity: .75 !important; }
  .opacity-xl-100 { opacity: 1 !important; }
}

@media (min-width: 1400px) {
  .opacity-xxl-0 { opacity: 0 !important; }
  .opacity-xxl-25 { opacity: .25 !important; }
  .opacity-xxl-50 { opacity: .5 !important; }
  .opacity-xxl-75 { opacity: .75 !important; }
  .opacity-xxl-100 { opacity: 1 !important; }
}

Stampa

L'abilitazione printdell'opzione genererà anche classi di utilità per la stampa, che vengono applicate solo all'interno della @media print { ... }media query.

$utilities: (
  "opacity": (
    property: opacity,
    print: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Produzione:

.opacity-0 { opacity: 0 !important; }
.opacity-25 { opacity: .25 !important; }
.opacity-50 { opacity: .5 !important; }
.opacity-75 { opacity: .75 !important; }
.opacity-100 { opacity: 1 !important; }

@media print {
  .opacity-print-0 { opacity: 0 !important; }
  .opacity-print-25 { opacity: .25 !important; }
  .opacity-print-50 { opacity: .5 !important; }
  .opacity-print-75 { opacity: .75 !important; }
  .opacity-print-100 { opacity: 1 !important; }
}

Importanza

Tutte le utilità generate dall'API includono !importantper garantire che sostituiscano i componenti e le classi di modifica come previsto. È possibile attivare o disattivare questa impostazione globalmente con la $enable-important-utilitiesvariabile (predefinita su true).

Utilizzando l'API

Ora che hai familiarità con il funzionamento dell'API delle utilità, scopri come aggiungere le tue classi personalizzate e modificare le nostre utilità predefinite.

Sostituisci utilità

Sostituisci le utilità esistenti utilizzando la stessa chiave. Ad esempio, se desideri classi di utilità di overflow reattive aggiuntive, puoi farlo:

$utilities: (
  "overflow": (
    responsive: true,
    property: overflow,
    values: visible hidden scroll auto,
  ),
);

Aggiungi utilità

È possibile aggiungere nuove utilità alla $utilitiesmappa predefinita con un file map-merge. Assicurati che i nostri file Sass richiesti e _utilities.scsssiano prima importati, quindi usa map-mergeper aggiungere le tue utilità aggiuntive. Ad esempio, ecco come aggiungere cursorun'utilità reattiva con tre valori.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

Modifica utilità

Modifica le utilità esistenti nella mappa predefinita $utilitiescon le funzioni map-gete map-merge. Nell'esempio seguente, stiamo aggiungendo un valore aggiuntivo alle widthutenze. Inizia con un'iniziale map-mergee quindi specifica quale utilità desideri modificare. Da lì, recupera la mappa nidificata "width"con map-getper accedere e modificare le opzioni e i valori dell'utilità.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Abilita reattivo

È possibile abilitare classi reattive per un insieme esistente di utilità che attualmente non sono reattive per impostazione predefinita. Ad esempio, per rendere le borderclassi reattive:

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Questo genererà ora variazioni reattive di .bordere .border-0per ogni punto di interruzione. Il tuo CSS generato sarà simile a questo:

.border { ... }
.border-0 { ... }

@media (min-width: 576px) {
  .border-sm { ... }
  .border-sm-0 { ... }
}

@media (min-width: 768px) {
  .border-md { ... }
  .border-md-0 { ... }
}

@media (min-width: 992px) {
  .border-lg { ... }
  .border-lg-0 { ... }
}

@media (min-width: 1200px) {
  .border-xl { ... }
  .border-xl-0 { ... }
}

@media (min-width: 1400px) {
  .border-xxl { ... }
  .border-xxl-0 { ... }
}

Rinomina utilità

Utilità v4 mancanti o abituati a un'altra convenzione di denominazione? L'API delle utilità può essere utilizzata per sovrascrivere il risultato classdi una determinata utilità, ad esempio per rinominare .ms-*le utilità in oldish .ml-*:

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Rimuovere le utilità

Rimuovere qualsiasi utilità di default con la map-remove()funzione Sass .

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

// Remove multiple utilities with a comma-separated list
$utilities: map-remove($utilities, "width", "float");

@import "bootstrap/scss/utilities/api";

È inoltre possibile utilizzare la map-merge()funzione Sass e impostare la chiave di gruppo su nullper rimuovere l'utilità.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

@import "bootstrap/scss/utilities/api";

Aggiungi, rimuovi, modifica

Puoi aggiungere, rimuovere e modificare molte utilità contemporaneamente con la map-merge()funzione Sass . Ecco come puoi combinare gli esempi precedenti in una mappa più grande.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    // Remove the `width` utility
    "width": null,

    // Make an existing utility responsive
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),

    // Add new utilities
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

Rimuovere l'utilità in RTL

Alcuni casi limite rendono difficile lo stile RTL , come le interruzioni di riga in arabo. Pertanto le utilità possono essere eliminate dall'output RTL impostando l' rtlopzione su false:

$utilities: (
  "word-wrap": (
    property: word-wrap word-break,
    class: text,
    values: (break: break-word),
    rtl: false
  ),
);

Produzione:

/* rtl:begin:remove */
.text-break {
  word-wrap: break-word !important;
  word-break: break-word !important;
}
/* rtl:end:remove */

Questo non produce nulla in RTL, grazie alla direttiva di controllo RTLCSSremove .