API de utilitário

A API de utilitário é uma ferramenta baseada em Sass para gerar classes de utilitário.

Nesta página

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 $utilitiesmapa contém todos os nossos utilitários e é posteriormente mesclado com seu $utilitiesmapa 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	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	Variável para o nome da classe se você não quiser que seja igual à propriedade. Caso você não forneça a `class`chave e a `property`chave seja um array de strings, o nome da classe será o primeiro elemento do `property`array.
`state`	Opcional	Lista de variantes de pseudo-classe como `:hover`ou `:focus`para gerar para o utilitário. Sem valor padrão.
`responsive`	Opcional	Booleano indicando se classes responsivas precisam ser geradas. `false`por padrão.
`rfs`	Opcional	Boolean para habilitar o reescalonamento do fluido. Dê uma olhada na página RFS para descobrir como isso funciona. `false`por padrão.
`print`	Opcional	Booleano indicando se classes de impressão precisam ser geradas. `false`por padrão.
`rtl`	Opcional	Booleano indicando se o utilitário deve ser mantido em RTL. `true`por padrão.

API explicada

Todas as variáveis de utilitário são adicionadas à $utilitiesvariável em nossa _utilities.scssfolha 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,
    )
  )
 );

O que gera o seguinte:

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

Prefixo de classe personalizada

Use a classopção para alterar o prefixo de classe usado no CSS compilado:

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

Resultado:

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

Estados

Use a stateopção para gerar variações de pseudoclasse. As pseudoclasses de exemplo são :hovere :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: hovere você obterá .opacity-hover:hoverseu 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; }

Utilitários responsivos

Adicione o responsivebooleano 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; }
}

Alterando 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,
  ),
);

Utilitários de impressão

Ativar a printopçã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 !importantpara garantir que eles substituam componentes e classes modificadoras conforme pretendido. Você pode alternar essa configuração globalmente com a $enable-important-utilitiesvariá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.

Adicionar utilitários

$utilitiesNovos utilitários podem ser adicionados ao mapa padrão com uma extensão map-merge. Certifique-se de que nossos arquivos Sass necessários e _utilities.scsssejam importados primeiro, depois use o map-mergepara adicionar seus utilitários adicionais. Por exemplo, veja como adicionar um cursorutilitá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 $utilitiesmapa padrão com map-gete map-mergefunções. No exemplo abaixo, estamos adicionando um valor adicional aos widthutilitários. Comece com uma inicial map-mergee especifique qual utilitário você deseja modificar. A partir daí, busque o "width"mapa aninhado map-getpara 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 borderclasses 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 .bordere .border-0para 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 classde 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 widthutilitários, crie um $utilities map-mergee adicione "width": nulldentro.

@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 rtlopçã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 .