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	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. Hvis `null`den brukes som kartnøkkel, er den ikke kompilert.
`class`	Valgfri	Variabel for klassenavnet hvis du ikke vil at det skal være det samme som egenskapen. I tilfelle du ikke oppgir `class`nøkkelen og `property`nøkkelen er en rekke strenger, vil klassenavnet være det første elementet i `property`matrisen.
`state`	Valgfri	Liste over pseudoklassevarianter som `:hover`eller `:focus`å generere for verktøyet. Ingen standardverdi.
`responsive`	Valgfri	Boolsk som indikerer om responsive klasser må genereres. `false`som standard.
`rfs`	Valgfri	Boolsk for å muliggjøre reskalering av væske. Ta en titt på RFS - siden for å finne ut hvordan dette fungerer. `false`som standard.
`print`	Valgfri	Boolsk angir om utskriftsklasser må genereres. `false`som standard.
`rtl`	Valgfri	Boolsk som indikerer om verktøyet skal beholdes i RTL. `true`som standard.

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

Egendefinert klasseprefiks

Bruk classalternativet for å endre klasseprefikset som brukes i den kompilerte CSS:en:

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

Produksjon:

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

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

Responsive verktøy

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

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

Utskriftsverktøy

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.

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

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

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

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

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

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

Fjern verktøy

Fjern alle standardverktøyene ved å sette gruppenøkkelen til null. For eksempel, for å fjerne alle våre widthverktøy, opprette en $utilities map-mergeog legge til "width": nullinnenfor.

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

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

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 .