Utility API

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

Tällä sivulla

Bootstrap-apuohjelmat luodaan apuohjelman API:lla, ja niitä voidaan käyttää oletusapuluokkien muokkaamiseen tai laajentamiseen Sassin kautta. Apuohjelmamme API perustuu Sass-karttojen ja toimintojen sarjaan luokkaperheiden 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 `null`käytetään `class`karttaavaimena, sitä ei ole liitetty luokan nimeen.
`class`	Valinnainen	tyhjä	Luodun luokan nimi. Jos sitä ei ole annettu ja `property`se on merkkijonojono, `class`se on oletuksena taulukon ensimmäinen elementti `property`. Jos sitä ei ole annettu ja `property`se on merkkijono, `values`avaimia käytetään `class`nimissä.
`css-var`	Valinnainen	`false`	Boolean luomaan CSS-muuttujia CSS-sääntöjen sijaan.
`css-variable-name`	Valinnainen	tyhjä	Muokattu nimi ilman etuliitteitä CSS-muuttujalle säännön sisällä.
`local-vars`	Valinnainen	tyhjä	Kartta paikallisista CSS-muuttujista, jotka luodaan CSS-sääntöjen lisäksi.
`state`	Valinnainen	tyhjä	Luettelo luotavista pseudoluokan muunnelmista (esim. `:hover`tai `: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; }

Jos class: null, luo luokat kullekin valuesavaimelle:

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

Lähtö:

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

CSS-muuttujan apuohjelmat

Aseta css-varboolen arvoksi trueja API luo paikalliset CSS-muuttujat annetulle valitsimelle tavallisten property: valuesääntöjen sijaan. Lisää valinnainen css-variable-name, jos haluat määrittää eri CSS-muuttujan nimen kuin luokan nimi.

Harkitse .text-opacity-*apuohjelmiamme. Jos lisäämme css-variable-namevaihtoehdon, saamme mukautetun tulosteen.

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

Lähtö:

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

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 haluat esimerkiksi 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 hyödyllisyysluokkia, 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/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";

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. Sieltä hae 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/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";

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

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

Poista apuohjelmat

Poista kaikki map-remove()oletusapuohjelmat Sass-toiminnolla .

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

Voit myös poistaa apuohjelman käyttämällä map-merge()Sass-toimintoa ja asettaa ryhmäavaimen kohtaan .null

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

Lisää, poista, muokkaa

Voit lisätä, poistaa ja muokata useita apuohjelmia kerralla map-merge()Sass-toiminnolla . Näin voit yhdistää edelliset esimerkit yhdeksi suuremmaksi kartaksi.

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

Poista apuohjelma RTL:stä

Jotkut reunakotelot tekevät RTL-tyylistä vaikeaa , kuten arabian rivinvaihdot. Näin 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 .