Utility API

Το βοηθητικό API είναι ένα εργαλείο που βασίζεται σε Sass για τη δημιουργία κλάσεων βοηθητικών προγραμμάτων.

Σε αυτήν την σελίδα

Τα βοηθητικά προγράμματα Bootstrap δημιουργούνται με το βοηθητικό μας API και μπορούν να χρησιμοποιηθούν για την τροποποίηση ή την επέκταση του προεπιλεγμένου συνόλου κατηγοριών βοηθητικών προγραμμάτων μέσω Sass. Το βοηθητικό API μας βασίζεται σε μια σειρά από χάρτες και λειτουργίες Sass για τη δημιουργία οικογενειών κλάσεων με διάφορες επιλογές. Εάν δεν είστε εξοικειωμένοι με τους χάρτες Sass, διαβάστε τα επίσημα έγγραφα Sass για να ξεκινήσετε.

Ο $utilitiesχάρτης περιέχει όλα τα βοηθητικά μας προγράμματα και αργότερα συγχωνεύεται με τον προσαρμοσμένο $utilitiesχάρτη σας, εάν υπάρχει. Ο χάρτης βοηθητικών προγραμμάτων περιέχει μια πληκτρολογημένη λίστα ομάδων βοηθητικών προγραμμάτων που αποδέχονται τις ακόλουθες επιλογές:

Επιλογή	Τύπος	Προεπιλεγμένη τιμή	Περιγραφή
`property`	Απαιτείται	–	Το όνομα της ιδιότητας, αυτό μπορεί να είναι μια συμβολοσειρά ή μια σειρά από συμβολοσειρές (π.χ. οριζόντιες επενδύσεις ή περιθώρια).
`values`	Απαιτείται	–	Λίστα τιμών ή χάρτης εάν δεν θέλετε το όνομα της τάξης να είναι ίδιο με την τιμή. Εάν `null`χρησιμοποιείται ως κλειδί χάρτη, `class`δεν προσαρτάται στο όνομα της κλάσης.
`class`	Προαιρετικός	μηδενικό	Όνομα της τάξης που δημιουργήθηκε. Εάν δεν παρέχεται και `property`είναι ένας πίνακας συμβολοσειρών, `class`θα είναι προεπιλογή στο πρώτο στοιχείο του `property`πίνακα. Εάν δεν παρέχεται και `property`είναι συμβολοσειρά, τα `values`κλειδιά χρησιμοποιούνται για τα `class`ονόματα.
`css-var`	Προαιρετικός	`false`	Boolean για τη δημιουργία μεταβλητών CSS αντί κανόνων CSS.
`css-variable-name`	Προαιρετικός	μηδενικό	Προσαρμοσμένο όνομα χωρίς πρόθεμα για τη μεταβλητή CSS μέσα στο σύνολο κανόνων.
`local-vars`	Προαιρετικός	μηδενικό	Χάρτης των τοπικών μεταβλητών CSS για δημιουργία εκτός από τους κανόνες CSS.
`state`	Προαιρετικός	μηδενικό	Λίστα παραλλαγών ψευδο-κλάσης (π.χ. `:hover`ή `:focus`) προς δημιουργία.
`responsive`	Προαιρετικός	`false`	Boolean που υποδεικνύει εάν πρέπει να δημιουργηθούν κλάσεις απόκρισης.
`rfs`	Προαιρετικός	`false`	Boolean για ενεργοποίηση της επανακλιμάκωσης υγρού με RFS .
`print`	Προαιρετικός	`false`	Boolean που υποδεικνύει εάν πρέπει να δημιουργηθούν κλάσεις εκτύπωσης.
`rtl`	Προαιρετικός	`true`	Boolean που υποδεικνύει εάν το βοηθητικό πρόγραμμα πρέπει να διατηρηθεί σε RTL.

Το API εξηγείται

Όλες οι μεταβλητές βοηθητικού προγράμματος προστίθενται στη $utilitiesμεταβλητή στο _utilities.scssφύλλο στυλ μας. Κάθε ομάδα βοηθητικών προγραμμάτων μοιάζει με αυτό:

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

Το οποίο βγάζει τα εξής:

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

Ιδιοκτησία

Το απαιτούμενο propertyκλειδί πρέπει να οριστεί για οποιοδήποτε βοηθητικό πρόγραμμα και πρέπει να περιέχει μια έγκυρη ιδιότητα CSS. Αυτή η ιδιότητα χρησιμοποιείται στο σύνολο κανόνων του βοηθητικού προγράμματος που δημιουργήθηκε. Όταν το classκλειδί παραλείπεται, χρησιμεύει επίσης ως το προεπιλεγμένο όνομα κλάσης. Εξετάστε το text-decorationβοηθητικό πρόγραμμα:

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

Παραγωγή:

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

Αξίες

Χρησιμοποιήστε το valuesκλειδί για να καθορίσετε ποιες τιμές για τα καθορισμένα propertyθα πρέπει να χρησιμοποιούνται στα ονόματα και τους κανόνες κλάσεων που δημιουργούνται. Μπορεί να είναι λίστα ή χάρτης (ορίζεται στα βοηθητικά προγράμματα ή σε μια μεταβλητή Sass).

Ως λίστα, όπως με τα text-decorationβοηθητικά προγράμματα :

values: none underline line-through

Ως χάρτης, όπως με opacityβοηθητικά προγράμματα :

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

Ως μεταβλητή Sass που ορίζει τη λίστα ή τον χάρτη, όπως στα positionβοηθητικά μας προγράμματα :

values: $position-values

Τάξη

Χρησιμοποιήστε την classεπιλογή για να αλλάξετε το πρόθεμα κλάσης που χρησιμοποιείται στο μεταγλωττισμένο CSS. Για παράδειγμα, για αλλαγή από .opacity-*σε .o-*:

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

Παραγωγή:

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

Το If class: null, δημιουργεί κλάσεις για καθένα από τα valuesκλειδιά:

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

Παραγωγή:

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

Βοηθητικά προγράμματα μεταβλητής CSS

Ορίστε την css-varεπιλογή boolean σε trueκαι το API θα δημιουργήσει τοπικές μεταβλητές CSS για τον συγκεκριμένο επιλογέα αντί για τους συνήθεις property: valueκανόνες. Προσθέστε ένα προαιρετικό css-variable-nameγια να ορίσετε ένα διαφορετικό όνομα μεταβλητής CSS από το όνομα της κλάσης.

Εξετάστε τα .text-opacity-*βοηθητικά μας προγράμματα. Εάν προσθέσουμε την css-variable-nameεπιλογή, θα λάβουμε μια προσαρμοσμένη έξοδο.

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

Παραγωγή:

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

Τοπικές μεταβλητές CSS

Χρησιμοποιήστε την local-varsεπιλογή για να καθορίσετε έναν χάρτη Sass που θα δημιουργεί τοπικές μεταβλητές CSS εντός του συνόλου κανόνων της κλάσης βοηθητικού προγράμματος. Λάβετε υπόψη ότι ενδέχεται να απαιτηθεί πρόσθετη εργασία για την κατανάλωση αυτών των τοπικών μεταβλητών CSS στους δημιουργηθέντες κανόνες CSS. Για παράδειγμα, εξετάστε τα .bg-*βοηθητικά μας προγράμματα:

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

Παραγωγή:

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

κράτη

Χρησιμοποιήστε την stateεπιλογή για να δημιουργήσετε παραλλαγές ψευδο-κλάσης. Παραδείγματα ψευδο-τάξεων είναι :hoverκαι :focus. Όταν παρέχεται μια λίστα καταστάσεων, δημιουργούνται ονόματα κλάσεων για αυτήν την ψευδο-κλάση. Για παράδειγμα, για να αλλάξετε την αδιαφάνεια στο δείκτη του ποντικιού, προσθέστε state: hoverκαι θα μεταβείτε .opacity-hover:hoverστο μεταγλωττισμένο CSS.

Χρειάζεστε πολλαπλές ψευδο-τάξεις; Χρησιμοποιήστε μια λίστα καταστάσεων διαχωρισμένη με διάστημα: state: hover focus.

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

Παραγωγή:

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

Ευαίσθητος

Προσ��έστε το responsiveboolean για να δημιουργήσετε βοηθητικά προγράμματα με απόκριση (π.χ. .opacity-md-25) σε όλα τα σημεία διακοπής .

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

Παραγωγή:

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

Τυπώνω

Η ενεργοποίηση της printεπιλογής θα δημιουργήσει επίσης κατηγορίες βοηθητικών προγραμμάτων για εκτύπωση, οι οποίες εφαρμόζονται μόνο στο @media print { ... }ερώτημα πολυμέσων.

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

Παραγωγή:

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

Σημασια

Όλα τα βοηθητικά προγράμματα που δημιουργούνται από το API περιλαμβάνουν !importantτη διασφάλιση ότι παρακάμπτουν τα στοιχεία και τις κατηγορίες τροποποιητών όπως προβλέπεται. Μπορείτε να αλλάξετε αυτήν τη ρύθμιση καθολικά με τη $enable-important-utilitiesμεταβλητή (προεπιλογή σε true).

Χρησιμοποιώντας το API

Τώρα που είστε εξοικειωμένοι με τον τρόπο λειτουργίας του API βοηθητικών προγραμμάτων, μάθετε πώς να προσθέτετε τις δικές σας προσαρμοσμένες κλάσεις και να τροποποιείτε τα προεπιλεγμένα βοηθητικά προγράμματα.

Παράκαμψη βοηθητικών προγραμμάτων

Αντικαταστήστε τα υπάρχοντα βοηθητικά προγράμματα χρησιμοποιώντας το ίδιο κλειδί. Για παράδειγμα, εάν θέλετε πρόσθετες αποκριτικές κλάσεις βοηθητικού προγράμματος υπερχείλισης, μπορείτε να το κάνετε αυτό:

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

Προσθήκη βοηθητικών προγραμμάτων

Μπορούν να προστεθούν νέα βοηθητικά προγράμματα στον προεπιλεγμένο $utilitiesχάρτη με ένα map-merge. Βεβαιωθείτε ότι τα απαιτούμενα αρχεία Sass _utilities.scssέχουν εισαχθεί πρώτα και, στη συνέχεια, χρησιμοποιήστε το map-mergeγια να προσθέσετε τα πρόσθετα βοηθητικά προγράμματα. Για παράδειγμα, δείτε πώς μπορείτε να προσθέσετε ένα cursorβοηθητικό πρόγραμμα που αποκρίνεται με τρεις τιμές.

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

Τροποποίηση βοηθητικών προγραμμάτων

Τροποποιήστε τα υπάρχοντα βοηθητικά προγράμματα στον προεπιλεγμένο $utilitiesχάρτη με map-getκαι map-mergeλειτουργίες. Στο παρακάτω παράδειγμα, προσθέτουμε μια επιπλέον αξία στα widthβοηθητικά προγράμματα. Ξεκινήστε με ένα αρχικό map-mergeκαι, στη συνέχεια, καθορίστε ποιο βοηθητικό πρόγραμμα θέλετε να τροποποιήσετε. Από εκεί, ανακτήστε τον ένθετο "width"χάρτη με map-getγια να αποκτήσετε πρόσβαση και να τροποποιήσετε τις επιλογές και τις τιμές του βοηθητικού προγράμματος.

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

Ενεργοποίηση απόκρισης

Μπορείτε να ενεργοποιήσετε αποκριτικές κλάσεις για ένα υπάρχον σύνολο βοηθητικών προγραμμάτων που δεν αποκρίνονται αυτήν τη στιγμή από προεπιλογή. Για παράδειγμα, για να κάνετε τις borderτάξεις να ανταποκρίνονται:

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

Αυτό θα δημιουργήσει τώρα παραλλαγές απόκρισης .borderκαι .border-0για κάθε σημείο διακοπής. Το CSS που δημιουργήσατε θα μοιάζει με αυτό:

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

Μετονομασία βοηθητικών προγραμμάτων

Λείπουν βοηθητικά προγράμματα v4 ή έχετε συνηθίσει σε άλλη σύμβαση ονομασίας; Το API βοηθητικών προγραμμάτων μπορεί να χρησιμοποιηθεί για να παρακάμψει το αποτέλεσμα classενός δεδομένου βοηθητικού προγράμματος—για παράδειγμα, για να μετονομάσετε .ms-*τα βοηθητικά προγράμματα σε παλιό .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";

Κατάργηση βοηθητικών προγραμμάτων

Καταργήστε οποιοδήποτε από τα προεπιλεγμένα βοηθητικά προγράμματα με τη map-remove()συνάρτηση 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";

Μπορείτε επίσης να χρησιμοποιήσετε τη map-merge()συνάρτηση Sass και να ορίσετε το πλήκτρο ομάδας για 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";

Προσθήκη, αφαίρεση, τροποποίηση

Μπορείτε να προσθέσετε, να αφαιρέσετε και να τροποποιήσετε πολλά βοηθητικά προγράμματα ταυτόχρονα με τη map-merge()συνάρτηση Sass . Δείτε πώς μπορείτε να συνδυάσετε τα προηγούμενα παραδείγματα σε έναν μεγαλύτερο χάρτη.

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

Κατάργηση βοηθητι��ού προγράμματος στο RTL

Ορισμένες θήκες άκρων κάνουν το στυλ RTL δύσκολο , όπως οι αλλαγές γραμμής στα αραβικά. Έτσι, τα βοηθητικά προγράμματα μπορούν να διαγραφούν από την έξοδο RTL ορίζοντας την rtlεπιλογή σε false:

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

Παραγωγή:

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

Αυτό δεν βγάζει τίποτα στο RTL, χάρη στην οδηγία ελέγχου RTLCSSremove .