Saltar al contenido principal Saltar a la navegación de documentos
in English

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 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 nullse usa como clave de mapa, no se compila.
class Opcional Variable para el nombre de la clase si no desea que sea igual a la propiedad. En caso de que no proporcione la classclave y la propertyclave sea una matriz de cadenas, el nombre de la clase será el primer elemento de la propertymatriz.
state Opcional Lista de variantes de pseudoclase como :hovero :focuspara generar para la utilidad. Sin valor predeterminado.
responsive Opcional Booleano que indica si es necesario generar clases receptivas. falsepor defecto.
rfs Opcional Booleano para habilitar el cambio de escala fluido. Eche un vistazo a la página de RFS para averiguar cómo funciona. falsepor defecto.
print Opcional Booleano que indica si es necesario generar clases de impresión. falsepor defecto.
rtl Opcional Booleano que indica si la utilidad debe mantenerse en RTL. truepor defecto.

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

Prefijo de clase personalizado

Utilice la classopción para cambiar el prefijo de clase utilizado en el CSS compilado:

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

Producción:

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

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

Utilidades receptivas

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

Cambio de 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,
  ),
);

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.

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

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

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

$utilities: map-merge(
  $utilities,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

Habilitar receptivo

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

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

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

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

Eliminar utilidades

Elimine cualquiera de las utilidades predeterminadas configurando la clave de grupo en null. Por ejemplo, para eliminar todas nuestras widthutilidades, cree un $utilities map-mergey agregue "width": nulldentro.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

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 .