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, `class`non se antepón ao nome da clase.
`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. Se non se proporciona e `property`é unha cadea, as `values`claves utilízanse para os `class`nomes.
`css-var`	Opcional	`false`	Booleano para xerar variables CSS en lugar de regras CSS.
`css-variable-name`	Opcional	nulo	Nome personalizado sen prefixo para a variable CSS dentro do conxunto de regras.
`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; }

Se class: null, xera clases para cada unha das valuesclaves:

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

Saída:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !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. Engade unha opción opcional css-variable-namepara establecer un nome de variable CSS diferente ao nome da clase.

Considere as nosas .text-opacity-*utilidades. Se engadimos a css-variable-nameopción, obteremos unha 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
    )
  ),
);

Saída:

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

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/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 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/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";

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/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";

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/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";

Eliminar utilidades

Elimina calquera das utilidades predeterminadas coa map-remove()función 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";

Tamén pode usar a map-merge()función Sass e configurar a tecla de grupo nullpara eliminar a utilidade.

@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";

Engadir, eliminar, modificar

Podes engadir, eliminar e modificar moitas utilidades á vez coa map-merge()función Sass . Aquí tes como podes combinar os exemplos anteriores nun mapa máis grande.

@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";

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 .