Ga naar hoofdinhoud Ga naar navigatie in documenten
in English

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 nullhet wordt gebruikt als kaartsleutel, wordt het niet gecompileerd.
class Optioneel nul Naam van de gegenereerde klasse. Indien niet opgegeven en propertyeen array van strings is, classwordt standaard het eerste element van de propertyarray gebruikt.
css-var Optioneel false Boolean om CSS-variabelen te genereren in plaats van CSS-regels.
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. :hoverof :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; }

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. Denk aan onze .text-opacity-*hulpprogramma's:

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

Uitgang:

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

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

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

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

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

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

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

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

Hulpprogramma's verwijderen

Verwijder alle standaardhulpprogramma's door de groepssleutel in te stellen op null. Als u bijvoorbeeld al onze widthhulpprogramma's wilt verwijderen, maakt u een $utilities map-mergeen voegt u "width": nullbinnen toe.

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

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

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 .