Utility API
Utility API er et Sass-basert verktøy for å generere verktøyklasser.
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 $utilities
inneholder alle våre verktøy og blir senere slått sammen med ditt tilpassede $utilities
kart, 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. Hvis null den brukes som kartnøkkel, er den ikke kompilert. |
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. |
css-var |
Valgfri | false |
Boolean for å generere CSS-variabler i stedet for CSS-regler. |
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 $utilities
variabelen i _utilities.scss
stilarket 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 property
nø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 class
nøkkelen er utelatt, fungerer den også som standard klassenavn. Vurder text-decoration
verktø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 values
nøkkelen for å spesifisere hvilke verdier for den spesifiserte som property
skal 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-decoration
verktøy :
values: none underline line-through
Som et kart, som med opacity
verktø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 position
verktøy :
values: $position-values
Klasse
Bruk class
alternativet 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; }
CSS-variable verktøy
Sett det css-var
boolske alternativet til true
, og API vil generere lokale CSS-variabler for den gitte velgeren i stedet for de vanlige property: value
reglene. Vurder våre .text-opacity-*
hjelpemidler:
$utilities: (
"text-opacity": (
css-var: true,
class: text-opacity,
values: (
25: .25,
50: .5,
75: .75,
100: 1
)
),
);
Produksjon:
.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; }
Lokale CSS-variabler
Bruk local-vars
alternativet 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 state
alternativet for å generere pseudoklassevariasjoner. Eksempler på pseudoklasser er :hover
og :focus
. Når en liste over tilstander er gitt, opprettes klassenavn for den pseudoklassen. For eksempel, for å endre opasitet ved sveving, legg til state: hover
og du får .opacity-hover:hover
inn 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 responsive
boolsk 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 print
alternativet 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 !important
for å sikre at de overstyrer komponenter og modifikasjonsklasser som tiltenkt. Du kan bytte denne innstillingen globalt med $enable-important-utilities
variabelen (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 $utilities
med en map-merge
. Sørg for at våre nødvendige Sass-filer og _utilities.scss
importeres først, og bruk deretter for map-merge
å legge til ekstra verktøy. For eksempel, her er hvordan du legger til et responsivt cursor
verktø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 $utilities
med map-get
og map-merge
funksjoner. I eksemplet nedenfor legger vi til en ekstra verdi til width
verktøyene. Start med en initial map-merge
og 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 border
klassene 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 .border
og .border-0
for 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 class
av 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 width
verktøy, opprette en $utilities
map-merge
og legge til "width": null
innenfor.
@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 rtl
alternativet 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 .