API de utilidad

La API de utilidad es una herramienta basada en Sass para generar clases de utilidad.

En esta página

Las utilidades Bootstrap se generan con nuestra API de utilidades y se pueden usar para modificar o ampliar nuestro conjunto predeterminado de clases de utilidades a través de Sass. Nuestra API de utilidad se basa en una serie de mapas y funciones de Sass para generar familias de clases con varias opciones. Si no está familiarizado con los mapas de Sass, lea los documentos oficiales de Sass para comenzar.

El $utilitiesmapa contiene todas nuestras utilidades y luego se fusiona con su $utilitiesmapa personalizado, si está presente. El mapa de servicios contiene una lista codificada de grupos de servicios que aceptan las siguientes opciones:

Opción	Escribe	Valor por defecto	Descripción
`property`	Requerido	–	Nombre de la propiedad, puede ser una cadena o una matriz de cadenas (p. ej., márgenes o rellenos horizontales).
`values`	Requerido	–	Lista de valores o un mapa si no desea que el nombre de la clase sea el mismo que el valor. Si `null`se usa como clave de mapa, `class`no se antepone al nombre de la clase.
`class`	Opcional	nulo	Nombre de la clase generada. Si no se proporciona y `property`es una matriz de cadenas, `class`el valor predeterminado será el primer elemento de la `property`matriz. Si no se proporciona y `property`es una cadena, las `values`claves se utilizan para los `class`nombres.
`css-var`	Opcional	`false`	Boolean para generar variables CSS en lugar de reglas CSS.
`css-variable-name`	Opcional	nulo	Nombre personalizado sin prefijo para la variable CSS dentro del conjunto de reglas.
`local-vars`	Opcional	nulo	Mapa de variables CSS locales para generar además de las reglas CSS.
`state`	Opcional	nulo	Lista de variantes de pseudoclase (por ejemplo, `:hover`o `:focus`) para generar.
`responsive`	Opcional	`false`	Booleano que indica si se deben generar clases receptivas.
`rfs`	Opcional	`false`	Booleano para habilitar el cambio de escala fluido con RFS .
`print`	Opcional	`false`	Booleano que indica si es necesario generar clases de impresión.
`rtl`	Opcional	`true`	Booleano que indica si la utilidad debe mantenerse en RTL.

API explicada

Todas las variables de utilidad se agregan a la $utilitiesvariable dentro de nuestra _utilities.scsshoja de estilo. Cada grupo de utilidades se parece a esto:

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

Lo que genera lo siguiente:

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

Propiedad

La propertyclave necesaria debe configurarse para cualquier utilidad y debe contener una propiedad CSS válida. Esta propiedad se utiliza en el conjunto de reglas de la utilidad generada. Cuando classse omite la clave, también sirve como nombre de clase predeterminado. Considere la text-decorationutilidad:

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

Producción:

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

Valores

Use la valuesclave para especificar qué valores para el especificado propertydeben usarse en los nombres y reglas de clase generados. Puede ser una lista o un mapa (establecido en las utilidades o en una variable Sass).

Como una lista, como con text-decorationlas utilidades :

values: none underline line-through

Como un mapa, como con las opacityutilidades :

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

Como una variable de Sass que establece la lista o el mapa, como en nuestras positionutilidades :

values: $position-values

Clase

Utilice la classopción para cambiar el prefijo de clase utilizado en el CSS compilado. Por ejemplo, para cambiar de .opacity-*a .o-*:

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

Producción:

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

Si class: null, genera clases para cada una de las valuesclaves:

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

Producción:

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

Utilidades de variables CSS

Establezca la css-varopción booleana en truey la API generará variables CSS locales para el selector dado en lugar de las property: valuereglas habituales. Agregue un opcional css-variable-namepara establecer un nombre de variable CSS diferente al nombre de la clase.

Considere nuestras .text-opacity-*utilidades. Si agregamos la css-variable-nameopción, obtendremos una salida personalizada.

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

Producción:

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

Variables CSS locales

Utilice la local-varsopción para especificar un mapa Sass que generará variables CSS locales dentro del conjunto de reglas de la clase de utilidad. Tenga en cuenta que puede requerir trabajo adicional consumir esas variables CSS locales en las reglas CSS generadas. Por ejemplo, considere nuestras .bg-*utilidades:

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

Producción:

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

estados

Utilice la stateopción para generar variaciones de pseudoclase. Ejemplos de pseudoclases son :hovery :focus. Cuando se proporciona una lista de estados, se crean nombres de clase para esa pseudoclase. Por ejemplo, para cambiar la opacidad al pasar el mouse, agregue state: hovery obtendrá .opacity-hover:hoversu CSS compilado.

¿Necesita varias pseudoclases? Utilice una lista de estados separados por espacios: state: hover focus.

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

Producción:

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

Sensible

Agregue el responsivevalor booleano para generar utilidades de respuesta (p. ej., .opacity-md-25) en todos los puntos de interrupción .

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

Producción:

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

Impresión

Habilitar la printopción también generará clases de utilidad para imprimir, que solo se aplican dentro de la @media print { ... }consulta de medios.

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

Producción:

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

Importancia

Todas las utilidades generadas por la API se incluyen !importantpara garantizar que anulan los componentes y las clases de modificadores según lo previsto. Puede alternar esta configuración globalmente con la $enable-important-utilitiesvariable (predeterminada en true).

Uso de la API

Ahora que está familiarizado con el funcionamiento de la API de utilidades, aprenda cómo agregar sus propias clases personalizadas y modificar nuestras utilidades predeterminadas.

Anular utilidades

Anule las utilidades existentes utilizando la misma clave. Por ejemplo, si desea clases de utilidad de desbordamiento receptivas adicionales, puede hacer esto:

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

Agregar utilidades

Se pueden agregar nuevas utilidades al $utilitiesmapa predeterminado con un archivo map-merge. Asegúrese de que nuestros archivos Sass requeridos y _utilities.scssse importen primero, luego use map-mergepara agregar sus utilidades adicionales. Por ejemplo, aquí se explica cómo agregar una cursorutilidad receptiva con tres valores.

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

Modificar utilidades

$utilitiesModifique las utilidades existentes en el mapa predeterminado con map-gety map-mergefunciones. En el siguiente ejemplo, estamos agregando un valor adicional a las widthutilidades. Comience con una inicial map-mergey luego especifique qué utilidad desea modificar. "width"Desde allí, obtenga el mapa anidado map-getpara acceder y modificar las opciones y valores de la utilidad.

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

Habilitar receptivo

Puede habilitar clases receptivas para un conjunto existente de utilidades que actualmente no responden de forma predeterminada. Por ejemplo, para hacer que las borderclases respondan:

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

Esto ahora generará variaciones de respuesta de .bordery .border-0para cada punto de interrupción. Su CSS generado se verá así:

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

Renombrar utilidades

¿Falta utilidades v4 o está acostumbrado a otra convención de nomenclatura? La API de utilidades se puede usar para anular el resultado classde una utilidad dada, por ejemplo, para cambiar el nombre de las .ms-*utilidades a 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";

Eliminar utilidades

Elimina cualquiera de las utilidades predeterminadas con la map-remove()función 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";

También puede usar la map-merge()función Sass y configurar la clave de grupo nullpara eliminar la utilidad.

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

Agregar, quitar, modificar

Puede agregar, eliminar y modificar muchas utilidades a la vez con la map-merge()función Sass . Así es como puede combinar los ejemplos anteriores en un mapa más grande.

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

Eliminar utilidad en RTL

Algunos casos extremos dificultan el estilo RTL , como los saltos de línea en árabe. Por lo tanto, las utilidades se pueden eliminar de la salida RTL configurando la rtlopción en false:

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

Producción:

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

Esto no genera nada en RTL, gracias a la directiva de control RTLCSSremove .