Regole

Le regole definiscono le classi utility e il CSS risultante. UnoCSS ha molte regole integrate ma permette anche di aggiungere facilmente regole personalizzate.

Regole statiche

Con questo esempio:

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

Il seguente CSS verrà generato ogni volta che m-1 viene rilevato nella codebase degli utenti:

.m-1 { margin: 0.25rem; }

Nota: La sintassi del body segue la sintassi delle proprietà CSS, ad es. font-weight invece di fontWeight. Se c'è un trattino - nel nome della proprietà, dovrebbe essere tra virgolette.

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

Regole dinamiche

Per renderlo più intelligente, cambia il matcher in un RegExp e il body in una funzione:

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

Il primo argomento della funzione body è il risultato della corrispondenza RegExp che può essere destrutturato per ottenere i gruppi corrispondenti.

Ad esempio, con il seguente utilizzo:

<div class="m-100">
  <button class="m-3">
    <icon class="p-5" />
    My Button
  </button>
</div>

verrà generato il CSS corrispondente:

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

Congratulazioni! Ora hai le tue potenti utility CSS atomiche. Divertiti!

Fallback delle regole CSS

Nei casi in cui potresti voler sfruttare il fallback delle regole CSS per usare nuove funzionalità CSS mentre sei anche in grado di fare fallback per supportare browser vecchi, puoi opzionalmente restituire un array 2D come rappresentazione CSS per regole con le stesse chiavi. Ad esempio:

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

Che farà generare a h-100dvh:

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

Ordinamento

UnoCSS rispetta l'ordine delle regole che hai definito nel CSS generato. Quelle successive hanno priorità più alta.

Quando si usano regole dinamiche, può corrispondere a più token. Per impostazione predefinita, l'output di quelli corrispondenti sotto una singola regola dinamica verrà ordinato alfabeticamente all'interno del gruppo.

Unione delle regole

Per impostazione predefinita, UnoCSS unirà le regole CSS con lo stesso body per minimizzare la dimensione del CSS.

Ad esempio, <div class="m-2 hover:m2"> genererà:

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

Invece di due regole separate:

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

Simboli speciali

Dalla v0.61, UnoCSS supporta simboli speciali per definire informazioni meta aggiuntive per il tuo CSS generato. Puoi accedere ai simboli dal secondo argomento della funzione matcher della regola dinamica.

Ad esempio:

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

Genererà:

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

Simboli disponibili

• symbols.parent: Il wrapper parent della regola CSS generata (ad es. @supports, @media, ecc.)
• symbols.selector: Una funzione per modificare il selettore della regola CSS generata (vedi l'esempio sotto)
• symbols.layer: Una stringa/funzione/regex match che imposta il livello UnoCSS della regola CSS generata
• symbols.variants: Un array di gestori di varianti che vengono applicati all'oggetto CSS corrente
• symbols.shortcutsNoMerge: Un booleano per disabilitare l'unione della regola corrente negli shortcuts
• symbols.noMerge: Un booleano per disabilitare l'unione della regola corrente negli shortcuts
• symbols.sort: Un numero per sovrascrivere l'ordine di ordinamento dell'oggetto CSS corrente

Regole multi-selettore

Dalla v0.61, UnoCSS supporta multi-selettore tramite funzioni Generator JavaScript.

Ad esempio:

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)`
    }
  }],
]

Genererà più regole CSS:

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

Regole completamente controllate

TIP

Questa è una funzionalità avanzata, nella maggior parte delle situazioni non sarà necessaria.

Quando hai davvero bisogno di alcune regole avanzate che non sono coperte dalla combinazione di Regole Dinamiche e Varianti, UnoCSS fornisce anche un modo per darti il pieno controllo per generare il CSS.

Ti permette di restituire una stringa dalla funzione body della regola dinamica che verrà direttamente passata al CSS generato (questo significa anche che devi occuparti di cose come l'escape CSS, l'applicazione delle varianti, la costruzione CSS, e così via).

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

export default defineConfig({
  rules: [
    [/^custom-(.+)$/, ([, name], { rawSelector, currentSelector, variantHandlers, theme }) => {
      // scarta regole non corrispondenti
      if (name.includes('something'))
        return

      // se vuoi, puoi disabilitare le varianti per questa regola
      if (variantHandlers.length)
        return
      const selector = e(rawSelector)
      // restituisci una stringa invece di un oggetto
      return `
${selector} {
  font-size: ${theme.fontSize.sm};
}
/* puoi avere più regole */
${selector}::after {
  content: 'after';
}
.foo > ${selector} {
  color: red;
}
/* o media queries */
@media (min-width: ${theme.breakpoints.sm}) {
  ${selector} {
    font-size: ${theme.fontSize.sm};
  }
}
`
    }],
  ],
})