Hulpprogramma-API

De hulpprogramma-API is een op Sass gebaseerd hulpmiddel om hulpprogrammaklassen te genereren.

Op deze pagina

Bootstrap-hulpprogramma's worden gegenereerd met onze hulpprogramma-API en kunnen worden gebruikt om onze standaardset hulpprogrammaklassen via Sass te wijzigen of uit te breiden. Onze hulpprogramma-API is gebaseerd op een reeks Sass-kaarten en -functies voor het genereren van klassen van klassen met verschillende opties. Als je niet bekend bent met Sass-kaarten, lees dan de officiële Sass-documenten om aan de slag te gaan.

De $utilitieskaart bevat al onze hulpprogramma's en wordt later samengevoegd met uw aangepaste $utilitieskaart, indien aanwezig. De utiliteitskaart bevat een ingetoetste lijst van utiliteitsgroepen die de volgende opties accepteren:

Keuze	Type	Standaardwaarde	Beschrijving
`property`	Verplicht	–	Naam van de eigenschap, dit kan een string zijn of een array van strings (bijv. horizontale opvullingen of marges).
`values`	Verplicht	–	Zoeklijst of een kaart als u niet wilt dat de klassenaam hetzelfde is als de waarde. Als `null`wordt gebruikt als kaartsleutel, `class`wordt niet toegevoegd aan de klassenaam.
`class`	Optioneel	nul	Naam van de gegenereerde klasse. Indien niet opgegeven en `property`een array van strings is, `class`wordt standaard het eerste element van de `property`array gebruikt. Indien niet opgegeven en `property`een tekenreeks is, `values`worden de sleutels gebruikt voor de `class`namen.
`css-var`	Optioneel	`false`	Boolean om CSS-variabelen te genereren in plaats van CSS-regels.
`css-variable-name`	Optioneel	nul	Aangepaste naam zonder prefix voor de CSS-variabele in de regelset.
`local-vars`	Optioneel	nul	Kaart met lokale CSS-variabelen die naast de CSS-regels moeten worden gegenereerd.
`state`	Optioneel	nul	Lijst met pseudo-klasse varianten (bijv. `:hover`of `:focus`) die moeten worden gegenereerd.
`responsive`	Optioneel	`false`	Booleaanse waarde die aangeeft of responsieve klassen moeten worden gegenereerd.
`rfs`	Optioneel	`false`	Boolean om vloeistofherschalen met RFS in te schakelen .
`print`	Optioneel	`false`	Booleaanse waarde die aangeeft of er printklassen moeten worden gegenereerd.
`rtl`	Optioneel	`true`	Booleaanse waarde die aangeeft of het hulpprogramma in RTL moet worden bewaard.

API uitgelegd

Alle utility-variabelen worden toegevoegd aan de $utilitiesvariabele in onze _utilities.scssstylesheet. Elke groep hulpprogramma's ziet er ongeveer zo uit:

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

Wat het volgende oplevert:

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

Eigendom

De vereiste propertysleutel moet voor elk hulpprogramma worden ingesteld en moet een geldige CSS-eigenschap bevatten. Deze eigenschap wordt gebruikt in de regelset van het gegenereerde hulpprogramma. Wanneer de classsleutel wordt weggelaten, dient deze ook als de standaardklassenaam. Overweeg het text-decorationnut:

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

Uitgang:

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

Waarden

Gebruik de valuessleutel om op te geven welke waarden voor de opgegeven waarden propertymoeten worden gebruikt in de gegenereerde klassenamen en regels. Kan een lijst of kaart zijn (ingesteld in de hulpprogramma's of in een Sass-variabele).

Als een lijst, zoals bij text-decorationhulpprogramma's :

values: none underline line-through

Als een kaart, zoals bij opacityhulpprogramma's :

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

Als een Sass-variabele die de lijst of kaart instelt, zoals in onze positionhulpprogramma's :

values: $position-values

Klas

Gebruik de classoptie om het klassenvoorvoegsel te wijzigen dat in de gecompileerde CSS wordt gebruikt. Bijvoorbeeld om te veranderen van .opacity-*naar .o-*:

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

Uitgang:

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

Als class: null, genereert klassen voor elk van de valuessleutels:

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

Uitgang:

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

Hulpprogramma's voor CSS-variabelen

Stel de css-varbooleaanse optie in op trueen de API zal lokale CSS-variabelen genereren voor de gegeven selector in plaats van de gebruikelijke property: valueregels. Voeg optioneel css-variable-nametoe om een andere CSS-variabelenaam in te stellen dan de klassenaam.

Denk aan onze .text-opacity-*nutsvoorzieningen. Als we de css-variable-nameoptie toevoegen, krijgen we een aangepaste uitvoer.

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

Uitgang:

.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-variabelen

Gebruik de local-varsoptie om een Sass-kaart op te geven die lokale CSS-variabelen genereert binnen de regelset van de utility-klasse. Houd er rekening mee dat het extra werk kan vergen om die lokale CSS-variabelen te gebruiken in de gegenereerde CSS-regels. Denk bijvoorbeeld aan onze .bg-*hulpprogramma's:

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

Uitgang:

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

Staten

Gebruik de stateoptie om variaties van pseudo-klassen te genereren. Voorbeeld pseudo-klassen zijn :hoveren :focus. Wanneer een lijst met toestanden wordt verstrekt, worden klassenamen gemaakt voor die pseudo-klasse. Als u bijvoorbeeld de dekking bij het zweven wilt wijzigen, voegt state: hoveru toe en komt u .opacity-hover:hoverin uw gecompileerde CSS.

Meerdere pseudo-klassen nodig? Gebruik een door spaties gescheiden lijst met statussen: state: hover focus.

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

Uitgang:

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

Snel reagerend

Voeg de responsiveboolean toe om responsieve hulpprogramma's (bijv. .opacity-md-25) voor alle onderbrekingspunten te genereren .

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

Uitgang:

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

Afdrukken

printAls u de optie inschakelt , worden ook hulpprogrammaklassen voor afdrukken gegenereerd, die alleen worden toegepast binnen de @media print { ... }mediaquery.

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

Uitgang:

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

Belang

Alle hulpprogramma's die door de API worden gegenereerd !important, zorgen ervoor dat ze componenten en modificatieklassen overschrijven zoals bedoeld. U kunt deze instelling globaal wijzigen met de $enable-important-utilitiesvariabele (standaard ingesteld op true).

De API gebruiken

Nu u bekend bent met hoe de hulpprogramma's-API werkt, leert u hoe u uw eigen aangepaste klassen kunt toevoegen en onze standaardhulpprogramma's kunt wijzigen.

Hulpprogramma's overschrijven

Overschrijf bestaande hulpprogramma's door dezelfde sleutel te gebruiken. Als u bijvoorbeeld extra responsieve overflow-hulpprogrammaklassen wilt, kunt u dit doen:

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

Hulpprogramma's toevoegen

Nieuwe hulpprogramma's kunnen aan de standaardkaart worden toegevoegd $utilitiesmet een map-merge. Zorg ervoor dat onze vereiste Sass-bestanden _utilities.scsseerst zijn geïmporteerd en gebruik vervolgens de map-mergeom uw extra hulpprogramma's toe te voegen. Hier leest u bijvoorbeeld hoe u een responsief cursorhulpprogramma met drie waarden toevoegt.

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

Hulpprogramma's wijzigen

Wijzig bestaande hulpprogramma's in de standaardkaart $utilitiesmet map-geten map-mergefuncties. In het onderstaande voorbeeld voegen we een extra waarde toe aan de widthhulpprogramma's. Begin met een initiaal map-mergeen geef vervolgens op welk hulpprogramma u wilt wijzigen. Van daaruit haalt u de geneste "width"kaart op met map-getom de opties en waarden van het hulpprogramma te openen en te wijzigen.

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

Responsief inschakelen

U kunt responsieve klassen inschakelen voor een bestaande set hulpprogramma's die momenteel niet standaard reageren. Om de borderklassen bijvoorbeeld responsief te maken:

@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 genereert nu responsieve variaties van .borderen .border-0voor elk breekpunt. Uw gegenereerde CSS ziet er als volgt uit:

.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 hulpprogramma's

Ontbrekende v4-hulpprogramma's of gewend aan een andere naamgevingsconventie? De hulpprogramma's-API kan worden gebruikt om het resultaat van een bepaald hulpprogramma te overschrijven class, bijvoorbeeld om hulpprogramma's te hernoemen .ms-*naar 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";

Hulpprogramma's verwijderen

Verwijder alle standaardhulpprogramma's met de map-remove()Sass-functie .

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

U kunt ook de map-merge()Sass-functie gebruiken en de groepstoets instellen nullop om het hulpprogramma te verwijderen.

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

Toevoegen, verwijderen, wijzigen

U kunt veel hulpprogramma's in één keer toevoegen, verwijderen en wijzigen met de map-merge()Sass-functie . Hier leest u hoe u de vorige voorbeelden kunt combineren tot één grotere kaart.

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

Hulpprogramma verwijderen in RTL

Sommige randgevallen maken RTL-styling moeilijk , zoals regeleinden in het Arabisch. Zo kunnen hulpprogramma's uit de RTL-uitvoer worden verwijderd door de rtloptie in te stellen op false:

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

Uitgang:

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

Dit levert niets op in RTL, dankzij de RTLCSS remove-besturingsrichtlijn .