API de utilidad
La API de utilidad es una herramienta basada en Sass para generar clases de utilidad.
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 $utilities
mapa contiene todas nuestras utilidades y luego se fusiona con su $utilities
mapa 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, no se compila. |
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. |
css-var |
Opcional | false |
Boolean para generar variables CSS en lugar de reglas CSS. |
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 $utilities
variable dentro de nuestra _utilities.scss
hoja 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 property
clave 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 class
se omite la clave, también sirve como nombre de clase predeterminado. Considere la text-decoration
utilidad:
$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 values
clave para especificar qué valores para el especificado property
deben 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-decoration
las utilidades :
values: none underline line-through
Como un mapa, como con las opacity
utilidades :
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 position
utilidades :
values: $position-values
Clase
Utilice la class
opció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; }
Utilidades de variables CSS
Establezca la css-var
opción booleana en true
y la API generará variables CSS locales para el selector dado en lugar de las property: value
reglas habituales. Considere nuestras .text-opacity-*
utilidades:
$utilities: (
"text-opacity": (
css-var: true,
class: text-opacity,
values: (
25: .25,
50: .5,
75: .75,
100: 1
)
),
);
Producción:
.text-opacity-25 { --bs-text-opacity: .25; }
.text-opacity-50 { --bs-text-opacity: .5; }
.text-opacity-75 { --bs-text-opacity: .75; }
.text-opacity-100 { --bs-text-opacity: 1; }
Variables CSS locales
Utilice la local-vars
opció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 state
opción para generar variaciones de pseudoclase. Ejemplos de pseudoclases son :hover
y :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: hover
y obtendrá .opacity-hover:hover
su 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 responsive
valor 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 print
opció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 !important
para garantizar que anulan los componentes y las clases de modificadores según lo previsto. Puede alternar esta configuración globalmente con la $enable-important-utilities
variable (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 $utilities
mapa predeterminado con un archivo map-merge
. Asegúrese de que nuestros archivos Sass requeridos y _utilities.scss
se importen primero, luego use map-merge
para agregar sus utilidades adicionales. Por ejemplo, aquí se explica cómo agregar una cursor
utilidad 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
$utilities
Modifique las utilidades existentes en el mapa predeterminado con map-get
y map-merge
funciones. En el siguiente ejemplo, estamos agregando un valor adicional a las width
utilidades. Comience con una inicial map-merge
y luego especifique qué utilidad desea modificar. "width"
Desde allí, obtenga el mapa anidado map-get
para 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 border
clases 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 .border
y .border-0
para 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 class
de 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 width
utilidades, cree un $utilities
map-merge
y agregue "width": null
dentro.
@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 rtl
opció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
.