Nut API

Die nuts-API is 'n Sass-gebaseerde hulpmiddel om nutsklasse te genereer.

Op hierdie bladsy

Bootstrap-nutsprogramme word met ons nuts-API gegenereer en kan gebruik word om ons verstekstel nutsklasse via Sass te wysig of uit te brei. Ons nut-API is gebaseer op 'n reeks Sass-kaarte en -funksies om families van klasse met verskeie opsies te genereer. As jy nie vertroud is met Sass-kaarte nie, lees die amptelike Sass-dokumente om te begin.

Die $utilitieskaart bevat al ons hulpmiddels en word later saamgevoeg met jou persoonlike $utilitieskaart, indien teenwoordig. Die nutskaart bevat 'n sleutellys nutsgroepe wat die volgende opsies aanvaar:

Opsie	Tik	Standaard waarde	Beskrywing
`property`	Vereis	–	Naam van die eiendom, dit kan 'n string of 'n reeks stringe wees (bv. horisontale opvullings of kantlyne).
`values`	Vereis	–	Lys van waardes, of 'n kaart as jy nie wil hê dat die klasnaam dieselfde as die waarde moet wees nie. As `null`word as kaartsleutel gebruik, `class`word nie by die klasnaam aangebring nie.
`class`	Opsioneel	nul	Naam van die gegenereerde klas. As dit nie verskaf word nie en `property`'n reeks stringe is, `class`sal die eerste element van die `property`skikking verstek. As dit nie verskaf word nie en `property`'n string is, word die `values`sleutels vir die `class`name gebruik.
`css-var`	Opsioneel	`false`	Boolean om CSS-veranderlikes in plaas van CSS-reëls te genereer.
`css-variable-name`	Opsioneel	nul	Pasgemaakte naam sonder voorvoegsel vir die CSS-veranderlike binne die reëlstel.
`local-vars`	Opsioneel	nul	Kaart van plaaslike CSS veranderlikes te genereer bykomend tot die CSS reëls.
`state`	Opsioneel	nul	Lys van pseudo-klas variante (bv. `:hover`of `:focus`) om te genereer.
`responsive`	Opsioneel	`false`	Boolean wat aandui of responsiewe klasse gegenereer moet word.
`rfs`	Opsioneel	`false`	Boolean om vloeistofherskaling met RFS moontlik te maak .
`print`	Opsioneel	`false`	Boolean wat aandui of drukklasse gegenereer moet word.
`rtl`	Opsioneel	`true`	Boolean wat aandui of nut in RTL gehou moet word.

API verduidelik

Alle nutsveranderlikes word by die $utilitiesveranderlike in ons _utilities.scssstylblad gevoeg. Elke groep nutsdienste lyk so iets:

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

Wat die volgende uitvoer:

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

Eiendom

Die vereiste propertysleutel moet vir enige hulpprogram gestel word, en dit moet 'n geldige CSS-eienskap bevat. Hierdie eienskap word in die gegenereerde nutsprogram se reëlstel gebruik. Wanneer die classsleutel weggelaat word, dien dit ook as die verstek klasnaam. Oorweeg die text-decorationnut:

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

Uitset:

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

Waardes

Gebruik die valuessleutel om te spesifiseer watter waardes vir die gespesifiseerde propertygebruik moet word in die gegenereerde klasname en reëls. Kan 'n lys of kaart wees (gestel in die nutsprogramme of in 'n Sass-veranderlike).

As 'n lys, soos met text-decorationnutsprogramme :

values: none underline line-through

As 'n kaart, soos met opacitynutsprogramme :

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

As 'n Sass-veranderlike wat die lys of kaart stel, soos in ons positionnutsprogramme :

values: $position-values

Klas

Gebruik die classopsie om die klasvoorvoegsel wat in die saamgestelde CSS gebruik word, te verander. Byvoorbeeld, om te verander van .opacity-*na .o-*:

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

Uitset:

.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, genereer klasse vir elk van die valuessleutels:

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

Uitset:

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

CSS veranderlike nutsprogramme

Stel die css-varBoolese opsie na trueen die API sal plaaslike CSS-veranderlikes genereer vir die gegewe kieser in plaas van die gewone property: valuereëls. Voeg 'n opsioneel css-variable-nameby om 'n ander CSS-veranderlike naam as die klasnaam te stel.

Oorweeg ons .text-opacity-*nutsdienste. As ons die css-variable-nameopsie byvoeg, sal ons 'n pasgemaakte uitset kry.

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

Uitset:

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

Plaaslike CSS veranderlikes

Gebruik die local-varsopsie om 'n Sass-kaart te spesifiseer wat plaaslike CSS-veranderlikes binne die nutsklas se reëlstel sal genereer. Neem asseblief kennis dat dit bykomende werk kan verg om daardie plaaslike CSS-veranderlikes in die gegenereerde CSS-reëls te gebruik. Oorweeg byvoorbeeld ons .bg-*hulpprogramme:

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

Uitset:

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

State

Gebruik die stateopsie om pseudo-klas variasies te genereer. Voorbeeld pseudo-klasse is :hoveren :focus. Wanneer 'n lys van state verskaf word, word klasname vir daardie pseudo-klas geskep. Byvoorbeeld, om ondeursigtigheid te verander wanneer jy beweeg, voeg by state: hoveren jy kry .opacity-hover:hoverjou saamgestelde CSS.

Het jy veelvuldige pseudo-klasse nodig? Gebruik 'n spasie-geskeide lys van state: state: hover focus.

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

Uitset:

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

Responsief

Voeg die responsiveboolean by om responsiewe nutsprogramme (bv. .opacity-md-25) oor alle breekpunte te genereer .

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

Uitset:

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

Druk

Deur die printopsie te aktiveer, sal ook nutsklasse vir druk gegenereer word, wat slegs binne die @media print { ... }medianavraag toegepas word.

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

Uitset:

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

Belangrikheid

Alle nutsprogramme wat deur die API gegenereer word, sluit in !importantom te verseker dat hulle komponente en wysigerklasse ignoreer soos bedoel. Jy kan hierdie instelling wêreldwyd wissel met die $enable-important-utilitiesveranderlike (verstek na true).

Gebruik die API

Noudat jy vertroud is met hoe die utilities API werk, leer hoe om jou eie pasgemaakte klasse by te voeg en ons verstekhulpprogramme te verander.

Ignoreer nutsprogramme

Ignoreer bestaande nutsprogramme deur dieselfde sleutel te gebruik. Byvoorbeeld, as jy bykomende responsiewe oorloop-nutsklasse wil hê, kan jy dit doen:

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

Voeg nutsprogramme by

Nuwe nutsprogramme kan by die verstekkaart gevoeg word $utilitiesmet 'n map-merge. Maak seker dat ons vereiste Sass-lêers en _utilities.scsseers ingevoer is, gebruik dan die map-mergeom jou bykomende nutsprogramme by te voeg. Byvoorbeeld, hier is hoe om 'n responsiewe cursorhulpprogram met drie waardes by te voeg.

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

Verander nutsprogramme

Verander bestaande nutsprogramme in die verstekkaart $utilitiesmet map-geten map-mergefunksies. In die voorbeeld hieronder voeg ons 'n bykomende waarde by die widthnutsprogramme. Begin met 'n voorletter map-mergeen spesifiseer dan watter hulpprogram jy wil verander. Van daar af, haal die geneste "width"kaart mee map-getom toegang tot die nutsprogram se opsies en waardes te verkry en te verander.

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

Aktiveer responsief

Jy kan responsiewe klasse aktiveer vir 'n bestaande stel nutsprogramme wat tans nie by verstek reageer nie. Byvoorbeeld, om die borderklasse responsief te maak:

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

Dit sal nou responsiewe variasies van .borderen .border-0vir elke breekpunt genereer. Jou gegenereerde CSS sal soos volg lyk:

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

Hernoem nutsprogramme

Mis jy v4-hulpprogramme, of gewoond aan 'n ander naamkonvensie? Die nuts-API kan gebruik word om die resultaat classvan 'n gegewe nutsprogram te ignoreer—byvoorbeeld om .ms-*nutsprogramme te hernoem na 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";

Verwyder nutsprogramme

Verwyder enige van die verstekhulpprogramme met die map-remove()Sass-funksie .

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

Jy kan ook die map-merge()Sass-funksie gebruik en die groepsleutel op stel nullom die hulpprogram te verwyder.

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

Voeg by, verwyder, wysig

Jy kan baie nutsprogramme gelyktydig byvoeg, verwyder en wysig met die map-merge()Sass-funksie . Hier is hoe jy die vorige voorbeelde in een groter kaart kan kombineer.

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

Verwyder nut in RTL

Sommige randsake maak RTL-stilering moeilik , soos lynbreuke in Arabies. Hulpprogramme kan dus van RTL-uitvoer laat val word deur die rtlopsie te stel op false:

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

Uitset:

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

Dit lewer niks in RTL uit nie, danksy die RTLCSS remove-beheerdirektief .