Salta al contenuto principale Passa alla navigazione dei documenti
in English

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 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 nullviene utilizzata come chiave della mappa, non viene compilata.
class Opzionale Variabile per il nome della classe se non si desidera che sia uguale alla proprietà. Nel caso in cui non fornisci la classchiave e la propertychiave è un array di stringhe, il nome della classe sarà il primo elemento propertydell'array.
state Opzionale Elenco di varianti di pseudo-classi simili a :hovero :focusda generare per l'utilità. Nessun valore predefinito.
responsive Opzionale Booleano che indica se è necessario generare classi reattive. falseper impostazione predefinita.
rfs Opzionale Booleano per abilitare il ridimensionamento fluido. Dai un'occhiata alla pagina RFS per scoprire come funziona. falseper impostazione predefinita.
print Opzionale Booleano che indica se è necessario generare classi di stampa. falseper impostazione predefinita.
rtl Opzionale Booleano che indica se l'utilità deve essere mantenuta in RTL. trueper impostazione predefinita.

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; }

Prefisso di classe personalizzato

Utilizzare l' classopzione per modificare il prefisso di classe utilizzato nel CSS compilato:

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

Produzione:

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

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; }

Utilità reattive

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; }
}

Cambiare 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,
  ),
);

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.

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/utilities";

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

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/utilities";

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

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/utilities";

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

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/utilities";

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

Rimuovere le utilità

Rimuovere qualsiasi utilità predefinita impostando la chiave di gruppo su null. Ad esempio, per rimuovere tutte le nostre widthutilità, crea un $utilities map-mergee aggiungi "width": nullall'interno.

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

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

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 .