Ir ao contido principal Ir á navegación de documentos
in English

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 $utilitiesmapa contén todas as nosas utilidades e posteriormente fusionarase co teu $utilitiesmapa 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 nullse 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 classclave e a propertyclave sexa unha matriz de cadeas, o nome da clase será o primeiro elemento da propertymatriz.
state Opcional Lista de variantes de pseudo-clase como :hoverou :focuspara xerar para a utilidade. Sen valor predeterminado.
responsive Opcional Booleano que indica se é necesario xerar clases de resposta. falsepor defecto.
rfs Opcional Booleano para activar o reescalado do fluído. Bótalle un ollo á páxina RFS para descubrir como funciona isto. falsepor defecto.
print Opcional Booleano que indica se é necesario xerar clases de impresión. falsepor defecto.
rtl Opcional Booleano que indica se a utilidade debe manterse en RTL. truepor defecto.

API explicada

Todas as variables de utilidade engádense á $utilitiesvariable dentro da nosa _utilities.scssfolla 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 classopció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 stateopción para xerar variacións de pseudo-clase. Exemplos de pseudoclases son :hovere :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: hovere accederás .opacity-hover:hoverao 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 responsivebooleano 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,
  ),
);

Ao activar a printopció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 !importantpara garantir que anulan os compoñentes e as clases modificadoras segundo o previsto. Podes cambiar esta configuración globalmente coa $enable-important-utilitiesvariable (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 $utilitiesmapa predeterminado cun map-merge. Asegúrate de que _utilities.scssprimeiro se importan os nosos ficheiros Sass necesarios e, despois, usa o map-mergepara engadir as túas utilidades adicionais. Por exemplo, aquí tes como engadir unha cursorutilidade 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 $utilitiesmapa predeterminado con map-gete map-mergefuncións. No seguinte exemplo, estamos engadindo un valor adicional ás widthutilidades. Comeza cunha inicial map-mergee despois especifique que utilidade quere modificar. A partir de aí, obtén o mapa aniñado "width"con map-getpara 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 borderclases 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 .bordere .border-0para 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 classdunha 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 widthutilidades, cree un $utilities map-mergee engádeo "width": nulldentro.

@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 rtlopció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 .