API de utilidade
A API de utilidade é unha ferramenta baseada en Sass para xerar clases de utilidade.
As utilidades de arranque xéranse coa nosa API de utilidades e pódense usar para modificar ou ampliar o noso conxunto predeterminado de clases de utilidades a través de Sass. A nosa API de utilidade baséase nunha serie de mapas e funcións Sass para xerar familias de clases con varias opcións. Se non estás familiarizado cos mapas de Sass, consulta os documentos oficiais de Sass para comezar.
O $utilities
mapa contén todas as nosas utilidades e posteriormente fusionarase co teu $utilities
mapa personalizado, se está presente. O mapa de utilidades contén unha lista con claves de grupos de utilidades que aceptan as seguintes opcións:
Opción | Tipo | Descrición |
---|---|---|
property |
Obrigatorio | Nome da propiedade, pode ser unha cadea ou unha matriz de cadeas (por exemplo, recheos ou marxes horizontais). |
values |
Obrigatorio | Lista de valores ou un mapa se non queres que o nome da clase sexa o mesmo que o valor. Se null se usa como clave de mapa, non se compila. |
class |
Opcional | Variable para o nome da clase se non queres que sexa o mesmo que a propiedade. No caso de que non forneces a class clave e a property clave sexa unha matriz de cadeas, o nome da clase será o primeiro elemento da property matriz. |
state |
Opcional | Lista de variantes de pseudo-clase como :hover ou :focus para xerar para a utilidade. Sen valor predeterminado. |
responsive |
Opcional | Booleano que indica se é necesario xerar clases de resposta. false por defecto. |
rfs |
Opcional | Booleano para activar o reescalado do fluído. Bótalle un ollo á páxina RFS para descubrir como funciona isto. false por defecto. |
print |
Opcional | Booleano que indica se é necesario xerar clases de impresión. false por defecto. |
rtl |
Opcional | Booleano que indica se a utilidade debe manterse en RTL. true por defecto. |
API explicada
Todas as variables de utilidade engádense á $utilities
variable dentro da nosa _utilities.scss
folla de estilo. Cada grupo de utilidades ten un aspecto así:
$utilities: (
"opacity": (
property: opacity,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
O que saca o seguinte:
.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }
Prefixo de clase personalizado
Use a class
opción para cambiar o prefixo de clase usado no CSS compilado:
$utilities: (
"opacity": (
property: opacity,
class: o,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Saída:
.o-0 { opacity: 0; }
.o-25 { opacity: .25; }
.o-50 { opacity: .5; }
.o-75 { opacity: .75; }
.o-100 { opacity: 1; }
Estados
Use a state
opción para xerar variacións de pseudo-clase. Exemplos de pseudoclases son :hover
e :focus
. Cando se proporciona unha lista de estados, créanse nomes de clase para esa pseudo-clase. Por exemplo, para cambiar a opacidade ao pasar o cursor, engade state: hover
e accederás .opacity-hover:hover
ao teu CSS compilado.
Necesitas varias pseudoclases? Use unha lista de estados separados por espazos: state: hover focus
.
$utilities: (
"opacity": (
property: opacity,
class: opacity,
state: hover,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Saída:
.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 sensibles
Engade o responsive
booleano para xerar utilidades sensibles (por exemplo, .opacity-md-25
) en todos os puntos de interrupción .
$utilities: (
"opacity": (
property: opacity,
responsive: true,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Saída:
.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
Anular as utilidades existentes usando a mesma clave. Por exemplo, se queres clases de utilidade de desbordamento de resposta adicionais, podes facer isto:
$utilities: (
"overflow": (
responsive: true,
property: overflow,
values: visible hidden scroll auto,
),
);
Utilidades de impresión
Ao activar a print
opción tamén se xerarán clases de utilidade para a impresión, que só se aplican dentro da @media print { ... }
consulta de medios.
$utilities: (
"opacity": (
property: opacity,
print: true,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Saída:
.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 as utilidades xeradas pola API inclúen !important
para garantir que anulan os compoñentes e as clases modificadoras segundo o previsto. Podes cambiar esta configuración globalmente coa $enable-important-utilities
variable (por defecto é true
).
Usando a API
Agora que estás familiarizado co funcionamento da API de utilidades, aprende a engadir as túas propias clases personalizadas e a modificar as nosas utilidades predeterminadas.
Engadir utilidades
Pódense engadir novas utilidades ao $utilities
mapa predeterminado cun map-merge
. Asegúrate de que _utilities.scss
primeiro se importan os nosos ficheiros Sass necesarios e, despois, usa o map-merge
para engadir as túas utilidades adicionais. Por exemplo, aquí tes como engadir unha cursor
utilidade 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
Modifica as utilidades existentes no $utilities
mapa predeterminado con map-get
e map-merge
funcións. No seguinte exemplo, estamos engadindo un valor adicional ás width
utilidades. Comeza cunha inicial map-merge
e despois especifique que utilidade quere modificar. A partir de aí, obtén o mapa aniñado "width"
con map-get
para acceder e modificar as opcións e os valores da utilidade.
@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%),
),
),
),
)
);
Activar a resposta
Pode activar as clases de resposta para un conxunto existente de utilidades que non responden actualmente de forma predeterminada. Por exemplo, para que as 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 ),
),
)
);
Isto xerará agora variacións de resposta de .border
e .border-0
para cada punto de interrupción. O teu CSS xerado terá o seguinte aspecto:
.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 { ... }
}
Cambiar o nome das utilidades
Faltan as utilidades v4 ou están acostumados a outra convención de nomenclatura? A API de utilidades pódese usar para anular o resultado class
dunha utilidade determinada, por exemplo, para renomear .ms-*
as utilidades a antiga .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
Elimina calquera das utilidades predeterminadas configurando a chave do grupo como null
. Por exemplo, para eliminar todas as nosas width
utilidades, cree un $utilities
map-merge
e engádeo "width": null
dentro.
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";
$utilities: map-merge(
$utilities,
(
"width": null
)
);
Eliminar a utilidade en RTL
Algúns casos extremos dificultan o estilo RTL , como os saltos de liña en árabe. Así, as utilidades pódense eliminar da saída RTL configurando a rtl
opción en false
:
$utilities: (
"word-wrap": (
property: word-wrap word-break,
class: text,
values: (break: break-word),
rtl: false
),
);
Saída:
/* rtl:begin:remove */
.text-break {
word-wrap: break-word !important;
word-break: break-word !important;
}
/* rtl:end:remove */
Isto non mostra nada en RTL, grazas á directiva de control RTLCSSremove
.