Utility API

Utility API er et Sass-baseret værktøj til at generere hjælpeklasser.

På denne side

Bootstrap-værktøjer genereres med vores hjælpeprogram API og kan bruges til at ændre eller udvide vores standardsæt af hjælpeprogrammer via Sass. Vores utility API er baseret på en række Sass-kort og funktioner til generering af familier af klasser med forskellige muligheder. Hvis du ikke er bekendt med Sass-kort, kan du læse de officielle Sass-dokumenter for at komme i gang.

Kortet $utilitiesindeholder alle vores hjælpeprogrammer og fusioneres senere med dit brugerdefinerede $utilitieskort, hvis det findes. Hjælpekortet indeholder en nøgleliste over hjælpegrupper, som accepterer følgende muligheder:

Mulighed	Type	Standard værdi	Beskrivelse
`property`	Påkrævet	–	Egenskabens navn, dette kan være en streng eller en række strenge (f.eks. vandrette polstringer eller marginer).
`values`	Påkrævet	–	Liste over værdier eller et kort, hvis du ikke ønsker, at klassenavnet skal være det samme som værdien. Hvis `null`bruges som kortnøgle, `class`står ikke foran klassens navn.
`class`	Valgfri	nul	Navn på den genererede klasse. Hvis det ikke er angivet og `property`er et array af strenge, `class`vil det som standard være det første element i `property`arrayet. Hvis det ikke er angivet og `property`er en streng, `values`bruges tasterne til `class`navnene.
`css-var`	Valgfri	`false`	Boolean til at generere CSS-variabler i stedet for CSS-regler.
`css-variable-name`	Valgfri	nul	Brugerdefineret navn uden præfiks for CSS-variablen i regelsættet.
`local-vars`	Valgfri	nul	Kort over lokale CSS-variabler, der skal genereres ud over CSS-reglerne.
`state`	Valgfri	nul	Liste over pseudo-klasse varianter (f.eks. `:hover`eller `:focus`) til at generere.
`responsive`	Valgfri	`false`	Boolean angiver, om der skal genereres responsive klasser.
`rfs`	Valgfri	`false`	Boolean for at muliggøre væskeskalering med RFS .
`print`	Valgfri	`false`	Boolean angiver, om printklasser skal genereres.
`rtl`	Valgfri	`true`	Boolean angiver, om utility skal beholdes i RTL.

API forklaret

Alle hjælpevariabler tilføjes til $utilitiesvariablen i vores _utilities.scssstylesheet. Hver gruppe af hjælpeprogrammer ser sådan ud:

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

Som udsender følgende:

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

Ejendom

Den nødvendige propertynøgle skal indstilles til ethvert hjælpeprogram, og det skal indeholde en gyldig CSS-egenskab. Denne egenskab bruges i det genererede hjælpeprograms regelsæt. Når classnøglen udelades, fungerer den også som standard klassenavn. Overvej text-decorationværktøjet:

$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ærdier

Brug valuesnøglen til at angive, hvilke værdier for den angivne propertyder skal bruges i de genererede klassenavne og regler. Kan være en liste eller et kort (indstillet i hjælpeprogrammerne eller i en Sass-variabel).

Som en liste, ligesom med text-decorationhjælpeprogrammer :

values: none underline line-through

Som et kort, ligesom med opacityhjælpeprogrammer :

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

Som en Sass-variabel, der sætter listen eller kortet, som i vores positionhjælpeprogrammer :

values: $position-values

Klasse

Brug classmuligheden for at ændre det klassepræfiks, der bruges i den kompilerede CSS. For eksempel for at skifte fra .opacity-*til .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; }

If class: null, genererer klasser for hver af valuesnøglerne:

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

Produktion:

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

CSS variable hjælpeprogrammer

Indstil den css-varbooleske indstilling til, trueog API'en vil generere lokale CSS-variabler for den givne vælger i stedet for de sædvanlige property: valueregler. Tilføj en valgfri css-variable-nameindstilling for at angive et andet CSS-variabelnavn end klassenavnet.

Overvej vores .text-opacity-*forsyningsselskaber. Hvis vi tilføjer css-variable-namemuligheden, får vi et tilpasset output.

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

Produktion:

.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

Brug local-varsindstillingen til at angive et Sass-kort, der genererer lokale CSS-variabler i hjælpeklassens regelsæt. Bemærk venligst, at det kan kræve yderligere arbejde at forbruge de lokale CSS-variabler i de genererede CSS-regler. Overvej for eksempel vores .bg-*hjælpeprogrammer:

$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

Brug statemuligheden for at generere pseudo-klasse variationer. Eksempler på pseudoklasser er :hoverog :focus. Når der er angivet en liste over tilstande, oprettes klassenavne for den pseudoklasse. For eksempel, for at ændre opacitet ved svævning, tilføj, state: hoverog du får .opacity-hover:hoverdin kompilerede CSS.

Har du brug for flere pseudo-klasser? Brug en mellemrumssepareret liste over tilstande: 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; }

Lydhør

Tilføj responsiveboolean for at generere responsive hjælpeprogrammer (f.eks. .opacity-md-25) på tværs af alle breakpoints .

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

Print

Aktivering af printindstillingen vil også generere hjælpeklasser til print, som kun anvendes i @media print { ... }medieforespørgslen.

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

Betydning

Alle hjælpeprogrammer, der genereres af API'et, inkluderer !importantfor at sikre, at de tilsidesætter komponenter og modifikationsklasser som tilsigtet. Du kan skifte denne indstilling globalt med $enable-important-utilitiesvariablen (standard til true).

Brug af API

Nu hvor du er bekendt med, hvordan utilities API fungerer, kan du lære, hvordan du tilføjer dine egne brugerdefinerede klasser og ændrer vores standardværktøjer.

Tilsidesæt hjælpeprogrammer

Tilsidesæt eksisterende hjælpeprogrammer ved at bruge den samme nøgle. For eksempel, hvis du ønsker yderligere responsive overflow-værktøjsklasser, kan du gøre dette:

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

Tilføj hjælpeprogrammer

Nye hjælpeprogrammer kan tilføjes til standardkortet $utilitiesmed en map-merge. Sørg for, at vores nødvendige Sass-filer og _utilities.scssimporteres først, og brug derefter til map-mergeat tilføje dine yderligere hjælpeprogrammer. For eksempel, her er, hvordan du tilføjer et responsivt cursorhjælpeprogram med tre værdier.

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

Rediger hjælpeprogrammer

Rediger eksisterende hjælpeprogrammer i standardkortet $utilitiesmed map-getog map-mergefunktioner. I eksemplet nedenfor tilføjer vi en ekstra værdi til widthhjælpeprogrammerne. Start med en initial map-mergeog angiv derefter, hvilket hjælpeprogram du vil ændre. Derfra skal du hente det indlejrede "width"kort med map-getfor at få adgang til og ændre værktøjets muligheder og værdier.

@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 sæt af hjælpeprogrammer, der som standard ikke er responsive i øjeblikket. For eksempel for at gøre borderklasserne 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 nu generere responsive variationer af .borderog .border-0for hvert brudpunkt. Din genererede CSS vil se sådan ud:

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

Omdøb hjælpeprogrammer

Mangler du v4-værktøjer, eller er du vant til en anden navnekonvention? Utilities API kan bruges til at tilsidesætte resultatet classaf et givet hjælpeprogram - for eksempel til at omdøbe .ms-*hjælpeprogrammer 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 hjælpeprogrammer

Fjern alle standardværktøjerne med map-remove()Sass-funktionen .

@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å bruge map-merge()Sass-funktionen og indstille gruppetasten til nullfor at fjerne hjælpeprogrammet.

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

Tilføj, fjern, rediger

Du kan tilføje, fjerne og ændre mange hjælpeprogrammer på én gang med map-merge()Sass-funktionen . Sådan kan du kombinere de tidligere eksempler til et større kort.

@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 hjælpeprogrammet i RTL

Nogle kantcovers gør RTL-styling vanskelig , såsom linjeskift på arabisk. Hjælpeprogrammer kan således fjernes fra RTL-output ved at indstille rtlindstillingen til 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 */

Dette udsender ikke noget i RTL, takket være RTLCSS remove-kontroldirektivet .