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	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, `class`não será anexado ao nome da classe.
`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. Se não for fornecido e `property`for uma string, as `values`chaves serão usadas para os `class`nomes.
`css-var`	Opcional	`false`	Boolean para gerar variáveis CSS em vez de regras CSS.
`css-variable-name`	Opcional	nulo	Nome personalizado sem prefixo para a variável CSS dentro do conjunto de regras.
`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 à $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,
    )
  )
);

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 propertychave 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 classchave é omitida, ela também serve como nome de classe padrão. Considere o text-decorationutilitá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 valueschave para especificar quais valores para o especificado propertydevem 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-decorationutilitários :

values: none underline line-through

Como um mapa, como com opacityutilitá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 positionutilitários :

values: $position-values

Classe

Use a classopçã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; }

Se class: null, gera classes para cada uma das valueschaves:

$utilities: (
  "visibility": (
    property: visibility,
    class: null,
    values: (
      visible: visible,
      invisible: hidden,
    )
  )
);

Resultado:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !important; }

Utilitários de variável CSS

Defina a css-varopção booleana como truee a API gerará variáveis CSS locais para o seletor fornecido em vez das property: valueregras usuais. Adicione um opcional css-variable-namepara definir um nome de variável CSS diferente do nome da classe.

Considere nossos .text-opacity-*utilitários. Se adicionarmos a css-variable-nameopção, obteremos uma saída personalizada.

$utilities: (
  "text-opacity": (
    css-var: true,
    css-variable-name: text-alpha,
    class: text-opacity,
    values: (
      25: .25,
      50: .5,
      75: .75,
      100: 1
    )
  ),
);

Resultado:

.text-opacity-25 { --bs-text-alpha: .25; }
.text-opacity-50 { --bs-text-alpha: .5; }
.text-opacity-75 { --bs-text-alpha: .75; }
.text-opacity-100 { --bs-text-alpha: 1; }

Variáveis CSS locais

Use a local-varsopçã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 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; }

Responsivo

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

Imprimir

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.

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

$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 _utilities.scsssejam importados primeiro e, em seguida, 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/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

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

@import "bootstrap/scss/utilities/api";

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/maps";
@import "bootstrap/scss/mixins";
@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%),
        ),
      ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

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/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

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

@import "bootstrap/scss/utilities/api";

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/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

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

@import "bootstrap/scss/utilities/api";

Remover utilitários

Remova qualquer um dos utilitários padrão com a map-remove()função Sass .

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

// Remove multiple utilities with a comma-separated list
$utilities: map-remove($utilities, "width", "float");

@import "bootstrap/scss/utilities/api";

Você também pode usar a map-merge()função Sass e definir a chave de grupo como nullpara remover o utilitário.

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

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

@import "bootstrap/scss/utilities/api";

Adicionar, remover, modificar

Você pode adicionar, remover e modificar muitos utilitários de uma só vez com a map-merge()função Sass . Veja como você pode combinar os exemplos anteriores em um mapa maior.

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

$utilities: map-merge(
  $utilities,
  (
    // Remove the `width` utility
    "width": null,

    // Make an existing utility responsive
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),

    // Add new utilities
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

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 .

API de utilitário

API explicada

Propriedade

Valores

Classe

Utilitários de variável CSS

Variáveis ​​CSS locais

Estados

Responsivo

Imprimir

Importância

Usando a API

Substituir utilitários

Adicionar utilitários

Modificar utilitários

Ativar responsivo

Renomear utilitários

Remover utilitários

Adicionar, remover, modificar

Remover utilitário em RTL

Variáveis CSS locais