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	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`den bruges som kortnøgle, er den ikke kompileret.
`class`	Valgfri	Variabel for klassenavnet, hvis du ikke ønsker, at det skal være det samme som egenskaben. Hvis du ikke angiver `class`nøglen, og `property`nøglen er en række strenge, vil klassenavnet være det første element i `property`arrayet.
`state`	Valgfri	Liste over pseudo-klasse varianter som `:hover`eller `:focus`til at generere til værktøjet. Ingen standardværdi.
`responsive`	Valgfri	Boolean angiver, om der skal genereres responsive klasser. `false`som standard.
`rfs`	Valgfri	Boolean for at muliggøre reskalering af væske. Tag et kig på RFS- siden for at finde ud af, hvordan dette virker. `false`som standard.
`print`	Valgfri	Boolean angiver, om printklasser skal genereres. `false`som standard.
`rtl`	Valgfri	Boolean angiver, om utility skal beholdes i RTL. `true`som standard.

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

Brugerdefineret klassepræfiks

Brug classmuligheden for at ændre det klassepræfiks, der bruges i den kompilerede CSS:

$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

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

Responsive hjælpeprogrammer

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

Ændring af 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,
  ),
);

Udskrivningsværktøjer

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.

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

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

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

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

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

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

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

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

Fjern hjælpeprogrammer

Fjern alle standardværktøjerne ved at indstille gruppenøglen til null. For eksempel, for at fjerne alle vores widthhjælpeprogrammer, skal du oprette en $utilities map-mergeog tilføje "width": nullindenfor.

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

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

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 .