Utility API

Utility API er et Sass-basert verktøy for å generere verktøyklasser.

På denne siden

Bootstrap-verktøy genereres med vårt verktøy-API og kan brukes til å endre eller utvide vårt standardsett med verktøyklasser via Sass. Vårt verktøy-API er basert på en serie Sass-kart og funksjoner for å generere familier av klasser med ulike alternativer. Hvis du ikke er kjent med Sass-kart, kan du lese de offisielle Sass-dokumentene for å komme i gang.

Kartet $utilitiesinneholder alle våre verktøy og blir senere slått sammen med ditt tilpassede $utilitieskart, hvis det finnes. Verktøykartet inneholder en nøkkelliste over hjelpegrupper som godtar følgende alternativer:

Alternativ	Type	Standardverdi	Beskrivelse
`property`	Obligatorisk	–	Navnet på egenskapen, dette kan være en streng eller en rekke strenger (f.eks. horisontale utfyllinger eller marger).
`values`	Obligatorisk	–	Liste over verdier, eller et kart hvis du ikke vil at klassenavnet skal være det samme som verdien. If `null`brukes som `class`kartnøkkel, står ikke foran klassenavnet.
`class`	Valgfri	null	Navnet på den genererte klassen. Hvis det ikke er angitt og `property`er en rekke strenger, `class`vil det som standard brukes til det første elementet i `property`matrisen. Hvis det ikke er oppgitt og `property`er en streng, brukes `values`nøklene for `class`navnene.
`css-var`	Valgfri	`false`	Boolean for å generere CSS-variabler i stedet for CSS-regler.
`css-variable-name`	Valgfri	null	Egendefinert navn uten prefiks for CSS-variabelen i regelsettet.
`local-vars`	Valgfri	null	Kart over lokale CSS-variabler å generere i tillegg til CSS-reglene.
`state`	Valgfri	null	Liste over pseudoklassevarianter (f.eks. `:hover`eller `:focus`) som skal genereres.
`responsive`	Valgfri	`false`	Boolsk angir om responsive klasser skal genereres.
`rfs`	Valgfri	`false`	Boolsk for å muliggjøre reskalering av væske med RFS .
`print`	Valgfri	`false`	Boolsk angir om utskriftsklasser må genereres.
`rtl`	Valgfri	`true`	Boolsk som indikerer om verktøyet skal beholdes i RTL.

API forklart

Alle verktøyvariabler legges til $utilitiesvariabelen i _utilities.scssstilarket vårt. Hver gruppe verktøy ser omtrent slik ut:

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

Som gir ut følgende:

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

Eiendom

Den nødvendige propertynøkkelen må angis for ethvert verktøy, og den må inneholde en gyldig CSS-egenskap. Denne egenskapen brukes i det genererte verktøyets regelsett. Når classnøkkelen er utelatt, fungerer den også som standard klassenavn. Vurder text-decorationverktøyet:

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

Produksjon:

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

Verdier

Bruk valuesnøkkelen for å spesifisere hvilke verdier for den spesifiserte som propertyskal brukes i de genererte klassenavnene og reglene. Kan være en liste eller et kart (sett i verktøyene eller i en Sass-variabel).

Som en liste, som med text-decorationverktøy :

values: none underline line-through

Som et kart, som med opacityverktøy :

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

Som en Sass-variabel som setter listen eller kartet, som i våre positionverktøy :

values: $position-values

Klasse

Bruk classalternativet for å endre klasseprefikset som brukes i den kompilerte CSS. For eksempel, for å endre fra .opacity-*til .o-*:

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

Produksjon:

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

If class: null, genererer klasser for hver av valuesnøklene:

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

Produksjon:

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

CSS-variable verktøy

Sett det css-varboolske alternativet til true, og API vil generere lokale CSS-variabler for den gitte velgeren i stedet for de vanlige property: valuereglene. Legg til et valgfritt css-variable-namefor å angi et annet CSS-variabelnavn enn klassenavnet.

Vurder våre .text-opacity-*hjelpemidler. Hvis vi legger til css-variable-namealternativet, får vi en tilpasset utgang.

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

Produksjon:

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

Lokale CSS-variabler

Bruk local-varsalternativet til å spesifisere et Sass-kart som vil generere lokale CSS-variabler innenfor verktøyklassens regelsett. Vær oppmerksom på at det kan kreve mer arbeid å konsumere de lokale CSS-variablene i de genererte CSS-reglene. Vurder for eksempel våre .bg-*hjelpemidler:

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

Produksjon:

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

stater

Bruk statealternativet for å generere pseudoklassevariasjoner. Eksempler på pseudoklasser er :hoverog :focus. Når en liste over tilstander er gitt, opprettes klassenavn for den pseudoklassen. For eksempel, for å endre opasitet ved sveving, legg til state: hoverog du får .opacity-hover:hoverinn din kompilerte CSS.

Trenger du flere pseudo-klasser? Bruk en mellomromseparert liste over tilstander: state: hover focus.

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

Produksjon:

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

Mottakelig

Legg til responsiveboolsk verdi for å generere responsive verktøy (f.eks. .opacity-md-25) på tvers av alle bruddpunkter .

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

Produksjon:

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

Skrive ut

Aktivering av printalternativet vil også generere verktøyklasser for utskrift, som bare brukes i @media print { ... }mediespørringen.

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

Produksjon:

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

Betydning

Alle verktøy generert av API-en inkluderer !importantfor å sikre at de overstyrer komponenter og modifikasjonsklasser som tiltenkt. Du kan bytte denne innstillingen globalt med $enable-important-utilitiesvariabelen (standard til true).

Ved hjelp av API

Nå som du er kjent med hvordan utilities API fungerer, kan du lære hvordan du legger til dine egne tilpassede klasser og endrer standardverktøyene våre.

Overstyr verktøy

Overstyr eksisterende verktøy ved å bruke samme nøkkel. Hvis du for eksempel vil ha flere responsive overflow-verktøyklasser, kan du gjøre dette:

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

Legg til verktøy

Nye verktøy kan legges til standardkartet $utilitiesmed en map-merge. Sørg for at våre nødvendige Sass-filer og _utilities.scssimporteres først, og bruk deretter for map-mergeå legge til ekstra verktøy. For eksempel, her er hvordan du legger til et responsivt cursorverktøy med tre verdier.

@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";

Endre verktøy

Endre eksisterende verktøy i standardkartet $utilitiesmed map-getog map-mergefunksjoner. I eksemplet nedenfor legger vi til en ekstra verdi til widthverktøyene. Start med en initial map-mergeog spesifiser deretter hvilket verktøy du vil endre. Derfra henter du det nestede "width"kartet for map-getå få tilgang til og endre verktøyets alternativer og verdier.

@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";

Aktiver responsiv

Du kan aktivere responsive klasser for et eksisterende sett med verktøy som for øyeblikket ikke er responsive som standard. For eksempel, for å gjøre borderklassene responsive:

@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";

Dette vil nå generere responsive variasjoner av .borderog .border-0for hvert bruddpunkt. Din genererte CSS vil se slik ut:

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

Gi nytt navn til verktøy

Mangler du v4-verktøy, eller er du vant til en annen navnekonvensjon? Utilities API kan brukes til å overstyre resultatet classav et gitt verktøy - for eksempel for å gi nytt navn .ms-*til verktøy til 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";

Fjern verktøy

Fjern alle standardverktøyene med map-remove()Sass-funksjonen .

@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";

Du kan også bruke map-merge()Sass-funksjonen og sette gruppetasten til for nullå fjerne verktøyet.

@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";

Legg til, fjern, modifiser

Du kan legge til, fjerne og endre mange verktøy samtidig med map-merge()Sass-funksjonen . Slik kan du kombinere de forrige eksemplene til ett større kart.

@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";

Fjern verktøyet i RTL

Noen kantsaker gjør RTL-styling vanskelig , for eksempel linjeskift på arabisk. Dermed kan verktøy droppes fra RTL-utgang ved å sette rtlalternativet til false:

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

Produksjon:

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

Dette sender ikke ut noe i RTL, takket være RTLCSS remove-kontrolldirektivet .