Utility API

Offeryn sy'n seiliedig ar Sass yw'r API cyfleustodau i gynhyrchu dosbarthiadau cyfleustodau.

Ar y dudalen hon

Cynhyrchir cyfleustodau Bootstrap gyda'n API cyfleustodau a gellir eu defnyddio i addasu neu ymestyn ein set ddiofyn o ddosbarthiadau cyfleustodau trwy Sass. Mae ein API cyfleustodau yn seiliedig ar gyfres o fapiau Sass a swyddogaethau ar gyfer cynhyrchu teuluoedd o ddosbarthiadau gydag opsiynau amrywiol. Os ydych chi'n anghyfarwydd â mapiau Sass, darllenwch ar y dogfennau Sass swyddogol i ddechrau.

Mae'r $utilitiesmap yn cynnwys ein holl gyfleustodau ac fe'i cyfunir yn ddiweddarach â'ch $utilitiesmap personol, os yw'n bresennol. Mae'r map cyfleustodau yn cynnwys rhestr allweddi o grwpiau cyfleustodau sy'n derbyn yr opsiynau canlynol:

Opsiwn	Math	Gwerth diofyn	Disgrifiad
`property`	Angenrheidiol	-	Enw'r priodwedd, gall hyn fod yn llinyn neu'n gyfres o linynnau (ee padinau llorweddol neu ymylon).
`values`	Angenrheidiol	-	Rhestr o werthoedd, neu fap os nad ydych am i enw'r dosbarth fod yr un fath â'r gwerth. Os `null`yw'n cael ei ddefnyddio fel allwedd map, `class`nid yw wedi'i ragpendynnu i enw'r dosbarth.
`class`	Dewisol	null	Enw'r dosbarth a gynhyrchwyd. Os na ddarperir ac `property`mae'n amrywiaeth o linynnau, `class`bydd yn ddiofyn i elfen gyntaf yr `property`arae. Os na chaiff ei ddarparu a'i `property`fod yn llinyn, defnyddir yr `values`allweddi ar gyfer yr `class`enwau.
`css-var`	Dewisol	`false`	Boolean i gynhyrchu newidynnau CSS yn lle rheolau CSS.
`css-variable-name`	Dewisol	null	Enw personol heb ei ragnodi ar gyfer y newidyn CSS yn y set reolau.
`local-vars`	Dewisol	null	Map o newidynnau CSS lleol i'w cynhyrchu yn ychwanegol at y rheolau CSS.
`state`	Dewisol	null	Rhestr o amrywiadau ffug-ddosbarth (ee, `:hover`neu `:focus`) i'w cynhyrchu.
`responsive`	Dewisol	`false`	Boolean yn nodi a ddylid cynhyrchu dosbarthiadau ymatebol.
`rfs`	Dewisol	`false`	Boole i alluogi ail-raddio hylif gyda RFS .
`print`	Dewisol	`false`	Boolean yn nodi a oes angen cynhyrchu dosbarthiadau argraffu.
`rtl`	Dewisol	`true`	Boolean yn nodi a ddylid cadw cyfleustodau yn RTL.

Esboniad API

Mae'r holl newidynnau cyfleustodau yn cael eu hychwanegu at y $utilitiesnewidyn yn ein _utilities.scsstaflen arddull. Mae pob grŵp o gyfleustodau yn edrych rhywbeth fel hyn:

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

Sy'n allbynnu'r canlynol:

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

Eiddo

Rhaid gosod yr allwedd ofynnol propertyar gyfer unrhyw gyfleustodau, a rhaid iddo gynnwys priodwedd CSS dilys. Defnyddir yr eiddo hwn yn set reolau'r cyfleustodau a gynhyrchir. Pan fydd yr classallwedd yn cael ei hepgor, mae hefyd yn gwasanaethu fel yr enw dosbarth rhagosodedig. Ystyriwch y text-decorationcyfleustodau:

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

Allbwn:

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

Gwerthoedd

Defnyddiwch yr valuesallwedd i nodi pa werthoedd ar gyfer y rhai penodedig y propertydylid eu defnyddio yn yr enwau a'r rheolau dosbarth a gynhyrchir. Gall fod yn rhestr neu'n fap (wedi'i osod yn y cyfleustodau neu mewn newidyn Sass).

Fel rhestr, fel gyda text-decorationchyfleustodau :

values: none underline line-through

Fel map, fel gyda opacitychyfleustodau :

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

Fel newidyn Sass sy'n gosod y rhestr neu'r map, fel yn ein positioncyfleustodau :

values: $position-values

Dosbarth

Defnyddiwch yr classopsiwn i newid y rhagddodiad dosbarth a ddefnyddir yn y CSS a luniwyd. Er enghraifft, i newid o .opacity-*i .o-*:

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

Allbwn:

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

Os class: null, yn cynhyrchu dosbarthiadau ar gyfer pob un o'r valuesallweddi:

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

Allbwn:

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

Cyfleustodau amrywiol CSS

Gosodwch yr css-varopsiwn boolean i a bydd yr API yn cynhyrchu newidynnau CSS lleol ar gyfer y dewiswr a roddir yn lle'r rheolau truearferol . property: valueYchwanegwch ddewisol css-variable-namei osod enw newidyn CSS gwahanol nag enw'r dosbarth.

Ystyriwch ein .text-opacity-*cyfleustodau. Os byddwn yn ychwanegu'r css-variable-nameopsiwn, byddwn yn cael allbwn wedi'i deilwra.

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

Allbwn:

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

Newidynnau CSS lleol

Defnyddiwch yr local-varsopsiwn i nodi map Sass a fydd yn cynhyrchu newidynnau CSS lleol o fewn set reolau'r dosbarth cyfleustodau. Sylwch y gallai fod angen gwaith ychwanegol i ddefnyddio'r newidynnau CSS lleol hynny yn y rheolau CSS a gynhyrchir. Er enghraifft, ystyriwch ein .bg-*cyfleustodau:

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

Allbwn:

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

Gwladwriaethau

Defnyddiwch yr stateopsiwn i gynhyrchu amrywiadau ffug-ddosbarth. Esiamplau ffug-ddosbarthiadau yw :hovera :focus. Pan ddarperir rhestr o daleithiau, crëir enwau dosbarth ar gyfer y ffug-ddosbarth hwnnw. Er enghraifft, i newid didreiddedd ar hofran, ychwanegwch state: hovera byddwch yn dod i .opacity-hover:hovermewn i'ch CSS a luniwyd.

Angen dosbarthiadau ffug lluosog? Defnyddiwch restr o gyflyrau wedi'u gwahanu gan ofod: state: hover focus.

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

Allbwn:

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

Ymatebol

Ychwanegwch y responsiveboolean i gynhyrchu cyfleustodau ymatebol (ee, .opacity-md-25) ar draws pob torbwynt .

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

Allbwn:

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

Argraffu

Bydd galluogi'r printopsiwn hefyd yn cynhyrchu dosbarthiadau cyfleustodau i'w hargraffu, a ddefnyddir yn yr @media print { ... }ymholiad cyfryngau yn unig.

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

Allbwn:

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

Pwysigrwydd

Mae'r holl gyfleustodau a gynhyrchir gan yr API yn cynnwys !importantsicrhau eu bod yn diystyru cydrannau a dosbarthiadau addasu yn ôl y bwriad. Gallwch newid y gosodiad hwn yn fyd-eang gyda'r $enable-important-utilitiesnewidyn (rhagosodiadau i true).

Gan ddefnyddio'r API

Nawr eich bod chi'n gyfarwydd â sut mae'r API cyfleustodau yn gweithio, dysgwch sut i ychwanegu eich dosbarthiadau arfer eich hun ac addasu ein cyfleustodau diofyn.

Diystyru cyfleustodau

Diystyru cyfleustodau presennol trwy ddefnyddio'r un allwedd. Er enghraifft, os ydych chi eisiau dosbarthiadau cyfleustodau gorlif ymatebol ychwanegol, gallwch chi wneud hyn:

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

Ychwanegu cyfleustodau

Gellir ychwanegu cyfleustodau newydd at y $utilitiesmap rhagosodedig gyda map-merge. Gwnewch yn siŵr bod ein ffeiliau Sass gofynnol ac _utilities.scssyn cael eu mewnforio yn gyntaf, yna defnyddiwch y map-mergei ychwanegu eich cyfleustodau ychwanegol. Er enghraifft, dyma sut i ychwanegu cursorcyfleustodau ymatebol gyda thri gwerth.

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

Addasu cyfleustodau

Addasu cyfleustodau presennol yn y $utilitiesmap rhagosodedig gyda map-geta map-mergeswyddogaethau. Yn yr enghraifft isod, rydym yn ychwanegu gwerth ychwanegol at y widthcyfleustodau. Dechreuwch gyda cychwynnol map-mergeac yna nodwch pa gyfleustodau rydych chi am eu haddasu. "width"O'r fan honno, ewch â'r map nythu map-geti gyrchu ac addasu opsiynau a gwerthoedd y cyfleustodau.

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

Galluogi ymatebol

Gallwch alluogi dosbarthiadau ymatebol ar gyfer set bresennol o gyfleustodau nad ydynt yn ymatebol yn ddiofyn ar hyn o bryd. Er enghraifft, i wneud y borderdosbarthiadau'n ymatebol:

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

Bydd hyn nawr yn cynhyrchu amrywiadau ymatebol o .borderac .border-0ar gyfer pob torbwynt. Bydd eich CSS a gynhyrchwyd yn edrych fel hyn:

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

Ail-enwi cyfleustodau

Cyfleustodau v4 ar goll, neu wedi arfer â chonfensiwn enwi arall? Gellir defnyddio'r API cyfleustodau i ddiystyru canlyniad classcyfleustodau penodol - er enghraifft, i ailenwi .ms-*cyfleustodau i hen .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";

Dileu cyfleustodau

Tynnwch unrhyw un o'r cyfleustodau rhagosodedig gyda'r map-remove()swyddogaeth 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";

Gallwch hefyd ddefnyddio'r map-merge()swyddogaeth Sass a gosod yr allwedd grŵp nulli gael gwared ar y cyfleustodau.

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

Ychwanegu, dileu, addasu

Gallwch ychwanegu, dileu, ac addasu llawer o gyfleustodau i gyd ar unwaith gyda'r map-merge()swyddogaeth Sass . Dyma sut y gallwch gyfuno'r enghreifftiau blaenorol yn un map mwy.

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

Dileu cyfleustodau yn RTL

Mae rhai achosion ymyl yn gwneud steilio RTL yn anodd , fel toriadau llinell mewn Arabeg. Felly gellir gollwng cyfleustodau o allbwn RTL trwy osod yr rtlopsiwn i false:

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

Allbwn:

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

Nid yw hyn yn allbwn unrhyw beth yn RTL, diolch i gyfarwyddeb reoli RTLCSSremove .