Utila API

La utileco API estas Sass-bazita ilo por generi utilajn klasojn.

Sur ĉi tiu paĝo

Bootstrap-servaĵoj estas generitaj per nia utileco API kaj povas esti uzataj por modifi aŭ etendi nian defaŭltan aron de utilecaj klasoj per Sass. Nia utileco API baziĝas sur serio de Sass-mapoj kaj funkcioj por generi familiojn de klasoj kun diversaj opcioj. Se vi ne konas Sass-mapojn, legu la oficialajn Sass-dokumentojn por komenci.

La $utilitiesmapo enhavas ĉiujn niajn utilecojn kaj poste estas kunfandita kun via kutima $utilitiesmapo, se ĉeestas. La servaĵomapo enhavas klava listo de servaĵogrupoj kiuj akceptas la sekvajn opciojn:

Opcio	Tajpu	Defaŭlta valoro	Priskribo
`property`	Bezonata	–	Nomo de la posedaĵo, ĉi tio povas esti ĉeno aŭ tabelo de ĉenoj (ekz., horizontalaj kompletigoj aŭ randoj).
`values`	Bezonata	–	Listo de valoroj, aŭ mapo se vi ne volas, ke la klasnomo estu la sama kiel la valoro. Se `null`estas uzata kiel mapŝlosilo, `class`ne estas antaŭmetita al la klasnomo.
`class`	Laŭvola	nulo	Nomo de la generita klaso. Se ne provizita kaj `property`estas tabelo de ŝnuroj, `class`defaŭlte al la unua elemento de la `property`tabelo. Se ne provizita kaj `property`estas ĉeno, la `values`ŝlosiloj estas uzataj por la `class`nomoj.
`css-var`	Laŭvola	`false`	Bulea por generi CSS-variablojn anstataŭ CSS-regulojn.
`css-variable-name`	Laŭvola	nulo	Propra neprefiksita nomo por la CSS-variablo ene de la reguloj.
`local-vars`	Laŭvola	nulo	Mapo de lokaj CSS-variabloj por generi krom la CSS-reguloj.
`state`	Laŭvola	nulo	Listo de pseŭdoklasaj variantoj (ekz. `:hover`aŭ `:focus`) por generi.
`responsive`	Laŭvola	`false`	Bulea indikanta ĉu respondemaj klasoj devus esti generitaj.
`rfs`	Laŭvola	`false`	Bulea por ebligi fluidan reskalon per RFS .
`print`	Laŭvola	`false`	Bulea indikanta ĉu presitaj klasoj devas esti generitaj.
`rtl`	Laŭvola	`true`	Bulea indikanta ĉu utileco devus esti konservita en RTL.

API klarigis

Ĉiuj utilecaj variabloj estas aldonitaj al la $utilitiesvariablo ene de nia _utilities.scssstilfolio. Ĉiu grupo de utilecoj aspektas kiel ĉi tio:

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

Kiu eligas la jenon:

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

Proprieto

La bezonata propertyŝlosilo devas esti agordita por iu ajn utileco, kaj ĝi devas enhavi validan CSS-posedaĵon. Ĉi tiu posedaĵo estas uzata en la regularo de la generita utileco. Kiam la classŝlosilo estas ellasita, ĝi ankaŭ funkcias kiel la defaŭlta klasnomo. Konsideru la text-decorationutilecon:

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

Eligo:

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

Valoroj

Uzu la valuesŝlosilon por specifi kiuj valoroj por la specifita propertydevas esti uzataj en la generitaj klasnomoj kaj reguloj. Povas esti listo aŭ mapo (aro en la utilecoj aŭ en Sass-variablo).

Kiel listo, kiel kun text-decorationiloj :

values: none underline line-through

Kiel mapo, kiel kun opacityutilecoj :

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

Kiel Sass-variablo kiu fiksas la liston aŭ mapon, kiel en niaj positioniloj :

values: $position-values

Klaso

Uzu la classopcion por ŝanĝi la klasprefikson uzatan en la kompilita CSS. Ekzemple, ŝanĝi de .opacity-*al .o-*:

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

Eligo:

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

Se class: null, generas klasojn por ĉiu el la valuesŝlosiloj:

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

Eligo:

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

CSS-variaj utilecoj

Agordu la css-varbulean opcion al truekaj la API generos lokajn CSS-variablojn por la donita elektilo anstataŭ la kutimaj property: valuereguloj. Aldonu laŭvolan css-variable-namepor agordi malsaman CSS-variablan nomon ol la klasnomo.

Konsideru niajn .text-opacity-*utilecojn. Se ni aldonas la css-variable-nameopcion, ni ricevos kutiman eligon.

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

Eligo:

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

Lokaj CSS-variabloj

Uzu la local-varsopcion por specifi Sass-mapon, kiu generos lokajn CSS-variablojn ene de la reguloj de la utileca klaso. Bonvolu noti, ke eble postulas plian laboron por konsumi tiujn lokajn CSS-variablojn en la generitaj CSS-reguloj. Ekzemple, konsideru niajn .bg-*utilecojn:

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

Eligo:

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

ŝtatoj

Uzu la stateopcion por generi pseŭdoklasajn variaĵojn. Ekzemplaj pseŭdoklasoj estas :hoverkaj :focus. Kiam listo de ŝtatoj estas disponigita, klasnomoj estas kreitaj por tiu pseŭdoklaso. Ekzemple, por ŝanĝi opakecon sur ŝvebado, aldonu state: hoverkaj vi eniros .opacity-hover:hovervian kompilitan CSS.

Ĉu vi bezonas plurajn pseŭdoklasojn? Uzu spaco-disigitan liston de ŝtatoj: state: hover focus.

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

Eligo:

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

Respondema

Aldonu la responsivebulean por generi respondemajn ilojn (ekz., .opacity-md-25) tra ĉiuj rompopunktoj .

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

Eligo:

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

Presi

Ebligi la printopcion ankaŭ generos utilajn klasojn por presado, kiuj estas nur aplikataj ene de la @media print { ... }amaskomunikila demando.

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

Eligo:

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

Graveco

Ĉiuj utilecoj generitaj de la API inkluzivas !importantcertigi, ke ili superregas komponentojn kaj modifklasojn kiel celite. Vi povas ŝanĝi ĉi tiun agordon tutmonde kun la $enable-important-utilitiesvariablo (defaŭlte al true).

Uzante la API

Nun kiam vi konas kiel funkcias la API de utilecoj, lernu kiel aldoni viajn proprajn kutimajn klasojn kaj modifi niajn defaŭltajn ilojn.

Anstataŭigi utilecojn

Anstataŭigi ekzistantajn ilojn uzante la saman ŝlosilon. Ekzemple, se vi volas pliajn respondemajn superfluajn utilajn klasojn, vi povas fari ĉi tion:

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

Aldonu utilecojn

Novaj iloj povas esti aldonitaj al la defaŭlta $utilitiesmapo per map-merge. Certigu, ke niaj bezonataj Sass-dosieroj kaj _utilities.scssunue estas importitaj, poste uzu la map-mergepor aldoni viajn pliajn ilojn. Ekzemple, jen kiel aldoni respondeman cursorilon kun tri valoroj.

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

Modifi utilecojn

Modifi ekzistantajn utilecojn en la defaŭlta $utilitiesmapo kun map-getkaj map-mergefunkcioj. En la malsupra ekzemplo, ni aldonas plian valoron al la widthutilecoj. Komencu per komenca map-mergekaj poste specifu kiun ilon vi volas modifi. De tie, alportu la nestitan "width"mapon kun map-getpor aliri kaj modifi la opciojn kaj valorojn de la utileco.

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

Ebligu respondema

Vi povas ebligi respondemajn klasojn por ekzistanta aro de iloj kiuj ne estas aktuale respondemaj defaŭlte. Ekzemple, por igi la borderklasojn respondemaj:

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

Ĉi tio nun generos respondemajn variojn de .borderkaj .border-0por ĉiu rompopunkto. Via generita CSS aspektos jene:

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

Alinomi ilojn

Mankas v4-servaĵoj, aŭ uzataj al alia nomkonvencio? La utilaĵoj API povas esti uzata por superregi la rezulton classde antaŭfiksita servaĵo—ekzemple, por renomi .ms-*servaĵojn al 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";

Forigi ilojn

Forigu iun ajn el la defaŭltaj iloj per la map-remove()funkcio Sass .

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

Vi ankaŭ povas uzi la map-merge()funkcion Sass kaj agordi la grupklavon nullpor forigi la ilon.

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

Aldoni, forigi, modifi

Vi povas aldoni, forigi kaj modifi multajn ilojn samtempe per la map-merge()funkcio Sass . Jen kiel vi povas kombini la antaŭajn ekzemplojn en unu pli grandan mapon.

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

Forigi ilon en RTL

Kelkaj randkazoj malfaciligas RTL-stiladon , kiel liniorompoj en la araba. Tiel servaĵoj povas esti forigitaj de RTL-produktaĵo fiksante la rtlopcion al false:

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

Eligo:

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

Ĉi tio ne eligas ion ajn en RTL, danke al la RTLCSS- removekontroldirektivo .