Siirry pääsisältöön Siirry dokumenttien navigointiin
in English

Utility API

Apuohjelma-API on Sass-pohjainen työkalu hyödyllisyysluokkien luomiseen.

Bootstrap-apuohjelmat luodaan apuohjelman API:lla, ja niitä voidaan käyttää oletusapuluokkien muokkaamiseen tai laajentamiseen Sassin kautta. Apuohjelmamme API perustuu sarjaan Sass-karttoja ja funktioita luokkien perheiden luomiseen eri vaihtoehdoilla. Jos Sass-kartat eivät ole sinulle tuttuja, aloita lukemalla viralliset Sass-asiakirjat .

Kartta $utilitiessisältää kaikki apuohjelmamme, ja se yhdistetään myöhemmin mukautettuun $utilitieskarttaasi, jos sellainen on. Apuohjelmakartta sisältää luettelon apuryhmistä, jotka hyväksyvät seuraavat vaihtoehdot:

Vaihtoehto Tyyppi Oletusarvo Kuvaus
property Vaaditaan Ominaisuuden nimi, tämä voi olla merkkijono tai merkkijonojoukko (esim. vaakasuuntaiset täytteet tai marginaalit).
values Vaaditaan Arvoluettelo tai kartta, jos et halua luokan nimen olevan sama kuin arvon. Jos nullsitä käytetään karttaavaimena, sitä ei käännetä.
class Valinnainen tyhjä Luodun luokan nimi. Jos sitä ei ole annettu ja propertyse on merkkijonojono, classse on oletuksena taulukon ensimmäinen elementti property.
css-var Valinnainen false Boolean luomaan CSS-muuttujia CSS-sääntöjen sijaan.
local-vars Valinnainen tyhjä Kartta paikallisista CSS-muuttujista, jotka luodaan CSS-sääntöjen lisäksi.
state Valinnainen tyhjä Luettelo luotavista pseudoluokan muunnelmista (esim. :hovertai :focus).
responsive Valinnainen false Boolen arvo ilmaisee, pitäisikö reagoivia luokkia luoda.
rfs Valinnainen false Boolen arvo mahdollistaa nesteen uudelleenskaalauksen RFS :n avulla .
print Valinnainen false Boolen arvo ilmaisee, onko tulostusluokkia luotava.
rtl Valinnainen true Boolen arvo ilmaisee, pitäisikö apuohjelma säilyttää RTL:ssä.

API selitetty

Kaikki hyödyllisyysmuuttujat lisätään $utilitiesmuuttujaan _utilities.scsstyylitaulukossamme. Jokainen apuohjelmaryhmä näyttää suunnilleen tältä:

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

Joka tulostaa seuraavat:

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

Omaisuus

Vaadittu propertyavain on asetettava mille tahansa apuohjelmalle, ja sen on sisällettävä kelvollinen CSS-ominaisuus. Tätä ominaisuutta käytetään luodun apuohjelman säännöissä. Kun classavain jätetään pois, se toimii myös oletusluokan nimenä. Harkitse text-decorationapuohjelmaa:

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

Lähtö:

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

Arvot

Käytä valuesavainta määrittääksesi, mitä arvoja määritetyille arvoille propertytulee käyttää luoduissa luokan nimissä ja säännöissä. Voi olla luettelo tai kartta (asetettu apuohjelmissa tai Sass-muuttujassa).

Listana, kuten text-decorationapuohjelmien kanssa :

values: none underline line-through

Karttana, kuten opacityapuohjelmien kanssa :

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

Sass-muuttujana, joka asettaa luettelon tai kartan, kuten positionapuohjelmissamme :

values: $position-values

Luokka

Käytä classvaihtoehtoa muuttaaksesi käännetyssä CSS:ssä käytettyä luokan etuliitettä. Voit esimerkiksi vaihtaa arvosta .opacity-*muotoon .o-*:

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

Lähtö:

.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-muuttujan apuohjelmat

Aseta css-varboolen arvoksi trueja API luo paikalliset CSS-muuttujat annetulle valitsimelle tavallisten property: valuesääntöjen sijaan. Harkitse .text-opacity-*apuohjelmiamme:

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

Lähtö:

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

Paikalliset CSS-muuttujat

Käytä local-varsvaihtoehtoa määrittääksesi Sass-kartan, joka luo paikallisia CSS-muuttujia hyödyllisyysluokan säännöissä. Huomaa, että paikallisten CSS-muuttujien käyttäminen luoduissa CSS-säännöissä saattaa vaatia lisätyötä. Harkitse esimerkiksi .bg-*apuohjelmiamme:

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

Lähtö:

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

osavaltioissa

Käytä statevaihtoehtoa pseudoluokkamuunnelmien luomiseen. Esimerkki pseudo-luokista ovat :hoverja :focus. Kun tilaluettelo tarjotaan, tälle pseudoluokalle luodaan luokan nimet. Jos esimerkiksi haluat muuttaa peittävyyttä viemällä hiiri, lisää state: hover, niin saat .opacity-hover:hoverkäännetyn CSS:n.

Tarvitsetko useita pseudo-luokkia? Käytä välilyönnillä eroteltua tilojen luetteloa: state: hover focus.

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

Lähtö:

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

Responsiivinen

Lisää responsivelooginen arvo luodaksesi reagoivia apuohjelmia (esim. .opacity-md-25) kaikissa keskeytyspisteissä .

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

Lähtö:

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

Tulosta

printVaihtoehdon ottaminen käyttöön luo myös tulostukseen käytettävät hyötyluokat, joita käytetään vain @media print { ... }mediakyselyssä.

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

Lähtö:

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

Merkitys

Kaikki API:n luomat apuohjelmat !importantvarmistavat, että ne ohittavat komponentit ja muokkausluokat tarkoitetulla tavalla. Voit vaihtaa tämän asetuksen maailmanlaajuisesti $enable-important-utilitiesmuuttujalla (oletusarvo true).

API:n käyttö

Nyt kun olet perehtynyt apuohjelmien API:n toimintaan, opi lisäämään omia mukautettuja luokkia ja muokkaamaan oletusapuohjelmiamme.

Ohita apuohjelmat

Ohita olemassa olevat apuohjelmat käyttämällä samaa avainta. Jos esimerkiksi haluat lisää responsiivisia ylivuotoapuluokkia, voit tehdä näin:

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

Lisää apuohjelmia

Uusia apuohjelmia voidaan lisätä oletuskarttaan $utilitieskäyttämällä map-merge. Varmista, että vaaditut Sass-tiedostomme ja _utilities.scsson tuotu ensin, ja map-mergelisää sitten lisäapuohjelmat -painikkeella. Näin voit esimerkiksi lisätä reagoivan cursorapuohjelman kolmella arvolla.

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

Muokkaa apuohjelmia

Muokkaa oletuskartan olemassa olevia apuohjelmia $utilitiesja map-getfunktioilla map-merge. widthAlla olevassa esimerkissä lisäämme apuohjelmiin lisäarvon . Aloita alkukirjaimella map-mergeja määritä sitten, mitä apuohjelmaa haluat muokata. Nouda sieltä sisäkkäinen "width"kartta, map-getjotta voit käyttää ja muokata apuohjelman asetuksia ja arvoja.

@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%),
        ),
      ),
    ),
  )
);

Ota reagoiva käyttöön

Voit ottaa käyttöön reagoivat luokat olemassa oleville apuohjelmille, jotka eivät ole tällä hetkellä reagoivia. Jos haluat esimerkiksi tehdä borderluokista reagoivia:

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

Tämä luo nyt responsiiviset muunnelmat kullekin keskeytyspisteelle .borderja . .border-0Luotu CSS näyttää tältä:

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

Nimeä apuohjelmat uudelleen

Puuttuuko v4-apuohjelmat tai oletko tottunut toiseen nimeämiskäytäntöön? Apuohjelmien API:ta voidaan käyttää ohittamaan classtietyn apuohjelman tulos – esimerkiksi nimeämään .ms-*apuohjelmat vanhaksi .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 ),
    ),
  )
);

Poista apuohjelmat

Poista kaikki oletusapuohjelmat asettamalla ryhmäavaimeksi null. Jos esimerkiksi haluat poistaa kaikki widthapuohjelmamme, luo a $utilities map-mergeja lisää "width": nullsisällä.

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

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

Poista apuohjelma RTL:stä

Jotkut reunakotelot tekevät RTL-tyylistä vaikeaa , kuten arabian rivinvaihdot. Siten apuohjelmat voidaan poistaa RTL-lähdöstä asettamalla rtlvaihtoehdoksi false:

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

Lähtö:

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

Tämä ei tulosta mitään RTL: ssä RTLCSS-ohjausdirektiivin removeansiosta .