Regras

Regras definem classes de utilitários e o CSS resultante. O UnoCSS possui muitas regras embutidas e também permite adicionar facilmente regras personalizadas.

Regras estáticas

Com este exemplo:

rules: [
  ['m-1', { margin: '0.25rem' }],
]

O seguinte CSS será gerado sempre que m-1 for detectado no código do usuário:

.m-1 { margin: 0.25rem; }

Nota: A sintaxe do corpo segue a sintaxe de propriedades CSS, por exemplo, font-weight em vez de fontWeight. Se houver um hífen - no nome da propriedade, ele deve ser colocado entre aspas.

rules: [
  ['font-bold', { 'font-weight': 700 }],
]

Regras dinâmicas

Para torná-lo mais inteligente, altere o matcher para um RegExp e o corpo para uma função:

rules: [
  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
  [/^p-(\d+)$/, match => ({ padding: `${match[1] / 4}rem` })],
]

O primeiro argumento da função do corpo é o resultado da correspondência RegExp que pode ser desestruturado para obter os grupos correspondidos.

Por exemplo, com o seguinte uso:

<div class="m-100">
  <button class="m-3">
    <icon class="p-5" />
    Meu Botão
  </button>
</div>

o CSS correspondente será gerado:

.m-100 { margin: 25rem; }
.m-3 { margin: 0.75rem; }
.p-5 { padding: 1.25rem; }

Parabéns! Agora você tem seus próprios utilitários de CSS atômico poderosos. Aproveite!

Fallback de Regras CSS

Em casos em que você pode querer aproveitar o fallback de regras CSS para usar novos recursos de CSS, mantendo o suporte a navegadores antigos, você pode, opcionalmente, retornar uma matriz 2D como representação CSS para regras com as mesmas chaves. Por exemplo:

rules: [
  [/^h-(\d+)dvh$/, ([_, d]) => {
    return [
      ['height', `${d}vh`],
      ['height', `${d}dvh`],
    ]
  }],
]

Que fará h-100dvh gerar:

.h-100dvh { height: 100vh; height: 100dvh; }

Ordenação

O UnoCSS respeita a ordem das regras definidas no CSS gerado. As últimas têm maior prioridade.

Ao usar regras dinâmicas, pode corresponder a múltiplos tokens. Por padrão, a saída daqueles correspondidos sob uma única regra dinâmica será classificada alfabeticamente dentro do grupo.

Mesclagem de Regras

Por padrão, o UnoCSS irá mesclar regras CSS com o mesmo corpo para minimizar o tamanho do CSS.

Por exemplo, <div class="m-2 hover:m2"> irá gerar:

.hover\:m2:hover,
.m-2 {
  margin: 0.5rem;
}

Em vez de duas regras separadas:

.hover\:m2:hover {
  margin: 0.5rem;
}
.m-2 {
  margin: 0.5rem;
}

Símbolos Especiais

Desde a v0.61, o UnoCSS suporta símbolos especiais para definir informações meta adicionais para seu CSS gerado. Você pode acessar símbolos a partir do segundo argumento da função de correspondência de regra dinâmica.

Por exemplo:

rules: [
  [/^grid$/, ([, d], { symbols }) => {
    return {
      [symbols.parent]: '@supports (display: grid)',
      display: 'grid',
    }
  }],
]

Irá gerar:

@supports (display: grid) {
  .grid {
    display: grid;
  }
}

Símbolos Disponíveis

• symbols.parent: O wrapper pai da regra CSS gerada (por exemplo, @supports, @media, etc.)
• symbols.selector: Uma função para modificar o seletor da regra CSS gerada (veja o exemplo abaixo)
• symbols.layer: Uma string/função/correspondência regex que define a camada UnoCSS da regra CSS gerada
• symbols.variants: Uma matriz de manipulador de variantes que são aplicados ao objeto CSS atual
• symbols.shortcutsNoMerge: Um booleano para desabilitar a mesclagem da regra atual em atalhos
• symbols.noMerge: Um booleano para desabilitar a mesclagem da regra atual em atalhos
• symbols.sort: Um número para sobrescrever a ordem de classificação do objeto CSS atual

Regras Multi-seletor

Desde a v0.61, o UnoCSS suporta multi-seletor via Funções Geradoras JavaScript.

Por exemplo:

rules: [
  [/^button-(.*)$/, function* ([, color], { symbols }) {
    yield {
      background: color
    }
    yield {
      [symbols.selector]: selector => `${selector}:hover`,
      // https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix
      background: `color-mix(in srgb, ${color} 90%, black)`
    }
  }],
]

Irá gerar múltiplas regras CSS:

.button-red {
  background: red;
}
.button-red:hover {
  background: color-mix(in srgb, red 90%, black);
}

Regras Totalmente Controladas

TIP

Este é um recurso avançado, na maioria das situações não será necessário.

Quando você realmente precisar de algumas regras avançadas que não são cobertas pela combinação de Regras Dinâmicas e Variantes, o UnoCSS também fornece uma maneira de dar a você controle total para gerar o CSS.

Ele permite que você retorne uma string do corpo da função de regra dinâmica que será diretamente passada para o CSS gerado (isso também significa que você precisa cuidar de coisas como escape de CSS, aplicação de variantes, construção de CSS, etc.).

import { defineConfig, toEscapedSelector as e } from 'unocss'

export default defineConfig({
  rules: [
    [/^custom-(.+)$/, ([, name], { rawSelector, currentSelector, variantHandlers, theme }) => {
      // descartar regras que não correspondem
      if (name.includes('something'))
        return

      // se quiser, pode desabilitar as variantes para esta regra
      if (variantHandlers.length)
        return
      const selector = e(rawSelector)
      // retornar uma string em vez de um objeto
      return `
${selector} {
  font-size: ${theme.fontSize.sm};
}
/* você pode ter múltiplas regras */
${selector}::after {
  content: 'after';
}
.foo > ${selector} {
  color: red;
}
/* ou consultas de mídia */
@media (min-width: ${theme.breakpoints.sm}) {
  ${selector} {
    font-size: ${theme.fontSize.sm};
  }
}
`
    }],
  ],
})