API de utilitário
A API de utilitário é uma ferramenta baseada em Sass para gerar classes de utilitário.
Os utilitários de bootstrap são gerados com nossa API de utilitários e podem ser usados para modificar ou estender nosso conjunto padrão de classes de utilitários via Sass. Nossa API utilitária é baseada em uma série de mapas e funções Sass para geração de famílias de classes com várias opções. Se você não estiver familiarizado com os mapas Sass, leia os documentos oficiais do Sass para começar.
O $utilities
mapa contém todos os nossos utilitários e é posteriormente mesclado com seu $utilities
mapa personalizado, se houver. O mapa de utilitários contém uma lista codificada de grupos de utilitários que aceitam as seguintes opções:
Opção | Modelo | Valor padrão | Descrição |
---|---|---|---|
property |
Requeridos | – | Nome da propriedade, pode ser uma string ou um array de strings (por exemplo, preenchimentos horizontais ou margens). |
values |
Requeridos | – | Lista de valores ou um mapa se você não quiser que o nome da classe seja igual ao valor. Se null for usado como chave de mapa, não será compilado. |
class |
Opcional | nulo | Nome da classe gerada. Se não for fornecido e property for um array de strings, class o padrão será o primeiro elemento do property array. |
css-var |
Opcional | false |
Boolean para gerar variáveis CSS em vez de regras CSS. |
local-vars |
Opcional | nulo | Mapa de variáveis CSS locais para gerar além das regras CSS. |
state |
Opcional | nulo | Lista de variantes de pseudoclasse (por exemplo, :hover ou :focus ) a serem geradas. |
responsive |
Opcional | false |
Booleano indicando se classes responsivas devem ser geradas. |
rfs |
Opcional | false |
Boolean para habilitar o reescalonamento de fluidos com RFS . |
print |
Opcional | false |
Booleano indicando se classes de impressão precisam ser geradas. |
rtl |
Opcional | true |
Booleano indicando se o utilitário deve ser mantido em RTL. |
API explicada
Todas as variáveis de utilitário são adicionadas à $utilities
variável em nossa _utilities.scss
folha de estilo. Cada grupo de utilitários se parece com isto:
$utilities: (
"opacity": (
property: opacity,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Que produz o seguinte:
.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }
Propriedade
A property
chave necessária deve ser definida para qualquer utilitário e deve conter uma propriedade CSS válida. Esta propriedade é usada no conjunto de regras do utilitário gerado. Quando a class
chave é omitida, ela também serve como nome de classe padrão. Considere o text-decoration
utilitário:
$utilities: (
"text-decoration": (
property: text-decoration,
values: none underline line-through
)
);
Resultado:
.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 a values
chave para especificar quais valores para o especificado property
devem ser usados nos nomes e regras das classes geradas. Pode ser uma lista ou mapa (definido nos utilitários ou em uma variável Sass).
Como uma lista, como com text-decoration
utilitários :
values: none underline line-through
Como um mapa, como com opacity
utilitários :
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
Como uma variável Sass que define a lista ou mapa, como em nossos position
utilitários :
values: $position-values
Classe
Use a class
opção para alterar o prefixo de classe usado no CSS compilado. Por exemplo, para mudar de .opacity-*
para .o-*
:
$utilities: (
"opacity": (
property: opacity,
class: o,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Resultado:
.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; }
Utilitários de variável CSS
Defina a css-var
opção booleana como true
e a API gerará variáveis CSS locais para o seletor fornecido em vez das property: value
regras usuais. Considere nossos .text-opacity-*
utilitários:
$utilities: (
"text-opacity": (
css-var: true,
class: text-opacity,
values: (
25: .25,
50: .5,
75: .75,
100: 1
)
),
);
Resultado:
.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; }
Variáveis CSS locais
Use a local-vars
opção para especificar um mapa Sass que irá gerar variáveis CSS locais dentro do conjunto de regras da classe do utilitário. Observe que pode exigir trabalho adicional para consumir essas variáveis CSS locais nas regras CSS geradas. Por exemplo, considere nossos .bg-*
utilitários:
$utilities: (
"background-color": (
property: background-color,
class: bg,
local-vars: (
"bg-opacity": 1
),
values: map-merge(
$utilities-bg-colors,
(
"transparent": transparent
)
)
)
);
Resultado:
.bg-primary {
--bs-bg-opacity: 1;
background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important;
}
Estados
Use a state
opção para gerar variações de pseudoclasse. As pseudoclasses de exemplo são :hover
e :focus
. Quando uma lista de estados é fornecida, os nomes de classe são criados para essa pseudoclasse. Por exemplo, para alterar a opacidade ao passar o mouse, adicione state: hover
e você obterá .opacity-hover:hover
seu CSS compilado.
Precisa de várias pseudo-classes? Use uma lista de estados separados por espaços: state: hover focus
.
$utilities: (
"opacity": (
property: opacity,
class: opacity,
state: hover,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Resultado:
.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; }
Responsivo
Adicione o responsive
booleano para gerar utilitários responsivos (por exemplo, .opacity-md-25
) em todos os pontos de interrupção .
$utilities: (
"opacity": (
property: opacity,
responsive: true,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Resultado:
.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; }
}
Imprimir
Ativar a print
opção também gerará classes de utilitários para impressão, que são aplicadas apenas na @media print { ... }
consulta de mídia.
$utilities: (
"opacity": (
property: opacity,
print: true,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Resultado:
.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; }
}
Importância
Todos os utilitários gerados pela API incluem !important
para garantir que eles substituam componentes e classes modificadoras conforme pretendido. Você pode alternar essa configuração globalmente com a $enable-important-utilities
variável (o padrão é true
).
Usando a API
Agora que você está familiarizado com o funcionamento da API de utilitários, saiba como adicionar suas próprias classes personalizadas e modificar nossos utilitários padrão.
Substituir utilitários
Substitua os utilitários existentes usando a mesma chave. Por exemplo, se você quiser classes de utilitário de estouro responsivo adicionais, você pode fazer isso:
$utilities: (
"overflow": (
responsive: true,
property: overflow,
values: visible hidden scroll auto,
),
);
Adicionar utilitários
$utilities
Novos utilitários podem ser adicionados ao mapa padrão com uma extensão map-merge
. Certifique-se de que nossos arquivos Sass necessários _utilities.scss
sejam importados primeiro e, em seguida, use o map-merge
para adicionar seus utilitários adicionais. Por exemplo, veja como adicionar um cursor
utilitário responsivo com três 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 utilitários
Modifique os utilitários existentes no $utilities
mapa padrão com map-get
e map-merge
funções. No exemplo abaixo, estamos adicionando um valor adicional aos width
utilitários. Comece com uma inicial map-merge
e especifique qual utilitário você deseja modificar. A partir daí, busque o "width"
mapa aninhado map-get
para acessar e modificar as opções e valores do utilitário.
@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%),
),
),
),
)
);
Ativar responsivo
Você pode habilitar classes responsivas para um conjunto existente de utilitários que não são responsivos atualmente por padrão. Por exemplo, para tornar as border
classes responsivas:
@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 ),
),
)
);
Isso agora gerará variações responsivas de .border
e .border-0
para cada ponto de interrupção. Seu CSS gerado ficará assim:
.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 { ... }
}
Renomear utilitários
Utilitários v4 ausentes ou usado para outra convenção de nomenclatura? A API de utilitários pode ser usada para substituir o resultado class
de um determinado utilitário, por exemplo, para renomear .ms-*
utilitários para 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 ),
),
)
);
Remover utilitários
Remova qualquer um dos utilitários padrão definindo a chave do grupo como null
. Por exemplo, para remover todos os nossos width
utilitários, crie um $utilities
map-merge
e adicione "width": null
dentro.
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";
$utilities: map-merge(
$utilities,
(
"width": null
)
);
Remover utilitário em RTL
Alguns casos extremos dificultam o estilo RTL , como quebras de linha em árabe. Assim, os utilitários podem ser descartados da saída RTL definindo a rtl
opção para false
:
$utilities: (
"word-wrap": (
property: word-wrap word-break,
class: text,
values: (break: break-word),
rtl: false
),
);
Resultado:
/* rtl:begin:remove */
.text-break {
word-wrap: break-word !important;
word-break: break-word !important;
}
/* rtl:end:remove */
Isso não produz nada em RTL, graças à diretiva de controle RTLCSSremove
.