API de utilidade

A API de utilidade é unha ferramenta baseada en Sass para xerar clases de utilidade.

Nesta páxina

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	Valor predeterminado	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	nulo	Nome da clase xerada. Se non se proporciona e `property`é unha matriz de cadeas, `class`será o primeiro elemento da `property`matriz por defecto.
`css-var`	Opcional	`false`	Booleano para xerar variables CSS en lugar de regras CSS.
`local-vars`	Opcional	nulo	Mapa de variables CSS locais para xerar ademais das regras CSS.
`state`	Opcional	nulo	Lista de variantes de pseudo-clase (por exemplo, `:hover`ou `:focus`) para xerar.
`responsive`	Opcional	`false`	Booleano que indica se se deben xerar clases receptivas.
`rfs`	Opcional	`false`	Booleano para habilitar o reescalado de fluídos con RFS .
`print`	Opcional	`false`	Booleano que indica se é necesario xerar clases de impresión.
`rtl`	Opcional	`true`	Booleano que indica se a utilidade debe manterse en RTL.

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

Propiedade

A propertyclave necesaria debe establecerse para calquera utilidade e debe conter unha propiedade CSS válida. Esta propiedade úsase no conxunto de regras da utilidade xerada. Cando classse omite a chave, tamén serve como nome de clase predeterminado. Considere a text-decorationutilidade:

$utilities: (
  "text-decoration": (
    property: text-decoration,
    values: none underline line-through
  )
);

Saída:

.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 que valores para o especificado propertydeben usarse nos nomes e regras das clases xeradas. Pode ser unha lista ou un mapa (establecido nas utilidades ou nunha variable Sass).

Como lista, como coas text-decorationutilidades :

values: none underline line-through

Como mapa, como coas opacityutilidades :

values: (
  0: 0,
  25: .25,
  50: .5,
  75: .75,
  100: 1,
)

Como unha variable Sass que establece a lista ou o mapa, como nas nosas positionutilidades :

values: $position-values

Clase

Use a classopción para cambiar o prefixo de clase usado no CSS compilado. Por exemplo, para cambiar de .opacity-*a .o-*:

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

Saída:

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

Utilidades variables CSS

Establece a css-varopción booleana truee a API xerará variables CSS locais para o selector indicado en lugar das property: valueregras habituais. Considere as nosas .text-opacity-*utilidades:

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

Saída:

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

Variables CSS locais

Use a local-varsopción para especificar un mapa Sass que xerará variables CSS locais dentro do conxunto de regras da clase de utilidade. Teña en conta que pode requirir traballo adicional consumir esas variables CSS locais nas regras CSS xeradas. Por exemplo, considere as nosas .bg-*utilidades:

$utilities: (
  "background-color": (
    property: background-color,
    class: bg,
    local-vars: (
      "bg-opacity": 1
    ),
    values: map-merge(
      $utilities-bg-colors,
      (
        "transparent": transparent
      )
    )
  )
);

Saída:

.bg-primary {
  --bs-bg-opacity: 1;
  background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important;
}

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

Sensible

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

Imprimir

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.

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

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 .