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	Standardvärde	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	null	Namnet på den genererade klassen. Om det inte tillhandahålls och `property`är en array av strängar, `class`kommer det att vara det första elementet i `property`arrayen som standard.
`css-var`	Frivillig	`false`	Boolean för att generera CSS-variabler istället för CSS-regler.
`local-vars`	Frivillig	null	Karta över lokala CSS-variabler att generera utöver CSS-reglerna.
`state`	Frivillig	null	Lista över pseudoklassvarianter (t.ex. `:hover`eller `:focus`) att generera.
`responsive`	Frivillig	`false`	Boolean som indikerar om responsiva klasser ska genereras.
`rfs`	Frivillig	`false`	Boolean för att möjliggöra vätskeskalning med RFS .
`print`	Frivillig	`false`	Boolean som indikerar om utskriftsklasser behöver genereras.
`rtl`	Frivillig	`true`	Boolean som indikerar om nyttan ska behållas i RTL.

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

Fast egendom

Den nödvändiga propertynyckeln måste ställas in för alla verktyg och den måste innehålla en giltig CSS-egenskap. Den här egenskapen används i det genererade verktygets regeluppsättning. När classnyckeln utelämnas fungerar den också som standardklassnamn. Tänk på text-decorationnyttan:

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

Produktion:

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

Värderingar

Använd valuesnyckeln för att ange vilka värden för det angivna propertysom ska användas i de genererade klassnamnen och reglerna. Kan vara en lista eller karta (inställd i verktygen eller i en Sass-variabel).

Som en lista, som med text-decorationverktyg :

values: none underline line-through

Som en karta, som med opacityverktyg :

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

Som en Sass-variabel som ställer in listan eller kartan, som i våra positionverktyg :

values: $position-values

Klass

Använd classalternativet för att ändra klassprefixet som används i den kompilerade CSS. Till exempel, för att ändra från .opacity-*till .o-*:

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

Produktion:

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

CSS variabla verktyg

Ställ in det css-varbooleska alternativet till trueså genererar API:et lokala CSS-variabler för den givna väljaren istället för de vanliga property: valuereglerna. Tänk på våra .text-opacity-*verktyg:

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

Produktion:

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

Lokala CSS-variabler

Använd local-varsalternativet för att ange en Sass-karta som genererar lokala CSS-variabler inom verktygsklassens regeluppsättning. Observera att det kan kräva ytterligare arbete för att konsumera de lokala CSS-variablerna i de genererade CSS-reglerna. Tänk till exempel på våra .bg-*verktyg:

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

Produktion:

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

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

Mottaglig

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

Skriva ut

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.

Åsidosätt 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,
  ),
);

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 .