Utility API

Utility API är ett Sass-baserat verktyg för att generera verktygsklasser.

På den här sidan

Bootstrap-verktyg genereras med vårt verktygs-API och kan användas för att modifiera eller utöka vår standarduppsättning verktygsklasser via Sass. Vårt verktygs-API är baserat på en serie Sass-kartor och funktioner för att generera klassfamiljer med olika alternativ. Om du inte är bekant med Sass-kartor, läs upp de officiella Sass-dokumenten för att komma igång.

Kartan $utilitiesinnehåller alla våra verktyg och slås senare samman med din anpassade $utilitieskarta, om den finns. Verktygskartan innehåller en lista över verktygsgrupper som accepterar följande alternativ:

Alternativ	Typ	Beskrivning
`property`	Nödvändig	Namnet på egenskapen, detta kan vara en sträng eller en rad strängar (t.ex. horisontella stoppningar eller marginaler).
`values`	Nödvändig	Värdelista eller en karta om du inte vill att klassnamnet ska vara detsamma som värdet. Om `null`den används som kartnyckel är den inte kompilerad.
`class`	Frivillig	Variabel för klassnamnet om du inte vill att det ska vara samma som egenskapen. Om du inte tillhandahåller `class`nyckeln och `property`nyckeln är en array av strängar, kommer klassnamnet att vara det första elementet i `property`arrayen.
`state`	Frivillig	Lista över pseudoklassvarianter som `:hover`eller `:focus`att generera för verktyget. Inget standardvärde.
`responsive`	Frivillig	Boolean som indikerar om responsiva klasser behöver genereras. `false`som standard.
`rfs`	Frivillig	Boolean för att möjliggöra vätskeskalning. Ta en titt på RFS- sidan för att ta reda på hur detta fungerar. `false`som standard.
`print`	Frivillig	Boolean som indikerar om utskriftsklasser behöver genereras. `false`som standard.
`rtl`	Frivillig	Boolean som indikerar om nyttan ska behållas i RTL. `true`som standard.

API förklarat

Alla verktygsvariabler läggs till $utilitiesvariabeln i vår _utilities.scssstilmall. Varje grupp av verktyg ser ut ungefär så här:

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

Vilket ger ut följande:

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

Anpassat klassprefix

Använd classalternativet för att ändra klassprefixet som används i den kompilerade CSS:en:

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

Produktion:

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

stater

Använd statealternativet för att generera pseudoklassvariationer. Exempel på pseudoklasser är :hoveroch :focus. När en lista över tillstånd tillhandahålls skapas klassnamn för den pseudoklassen. Till exempel, för att ändra opacitet vid hovring, lägg till state: hoverså får du .opacity-hover:hoverin din kompilerade CSS.

Behöver du flera pseudoklasser? Använd en blankstegsseparerad lista över tillstånd: state: hover focus.

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

Produktion:

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

Responsiva verktyg

Lägg till responsiveboolean för att generera responsiva verktyg (t.ex. .opacity-md-25) över alla brytpunkter .

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

Produktion:

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

Ändra verktyg

Åsidosätt befintliga verktyg genom att använda samma nyckel. Till exempel, om du vill ha ytterligare responsiva överflödesverktygsklasser kan du göra så här:

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

Utskriftsverktyg

Aktivering av printalternativet kommer också att generera verktygsklasser för utskrift, som endast tillämpas inom @media print { ... }mediefrågan.

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

Produktion:

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

Betydelse

Alla verktyg som genereras av API:et inkluderar !importantför att säkerställa att de åsidosätter komponenter och modifieringsklasser som avsett. Du kan växla den här inställningen globalt med $enable-important-utilitiesvariabeln (standard till true).

Använder API

Nu när du är bekant med hur API:et för verktyg fungerar kan du lära dig hur du lägger till dina egna anpassade klasser och ändrar våra standardverktyg.

Lägg till verktyg

Nya verktyg kan läggas till standardkartan $utilitiesmed en map-merge. Se till att våra nödvändiga Sass-filer och _utilities.scssimporteras först, använd sedan för map-mergeatt lägga till dina ytterligare verktyg. Så här lägger du till exempel till ett responsivt cursorverktyg med tre värden.

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

Ändra verktyg

Ändra befintliga verktyg i standardkartan $utilitiesmed map-getoch map-mergefunktioner. I exemplet nedan lägger vi till ett extra värde till widthverktygen. Börja med en initial map-mergeoch ange sedan vilket verktyg du vill ändra. Därifrån hämtar du den kapslade "width"kartan med map-getför att komma åt och ändra verktygets alternativ och värden.

@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%),
        ),
      ),
    ),
  )
);

Aktivera responsiv

Du kan aktivera responsiva klasser för en befintlig uppsättning verktyg som för närvarande inte är responsiva som standard. Till exempel, för att göra borderklasserna responsiva:

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

Detta kommer nu att generera responsiva variationer av .borderoch .border-0för varje brytpunkt. Din genererade CSS kommer att se ut så här:

.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 { ... }
}

Byt namn på verktyg

Saknar du v4-verktyg, eller är du van vid en annan namnkonvention? Utilities API kan användas för att åsidosätta resultatet classav ett givet verktyg – till exempel för att byta namn på .ms-*verktyg till 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 ),
    ),
  )
);

Ta bort verktyg

Ta bort något av standardverktygen genom att ställa in gruppnyckeln till null. Till exempel, för att ta bort alla våra widthverktyg, skapa en $utilities map-mergeoch lägg till "width": nullinom.

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

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

Ta bort verktyget i RTL

Vissa kantfodral gör RTL-styling svår , till exempel radbrytningar på arabiska. Sålunda kan verktyg tas bort från RTL-utgång genom att ställa in rtlalternativet till false:

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

Produktion:

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

Detta matar inte ut något i RTL, tack vare RTLCSS remove-styrdirektivet .