UnoCSS Extraheren

UnoCSS werkt door te zoeken naar het gebruik van utilities in je codebase en de bijbehorende CSS on-demand te genereren. We noemen dit proces extracting.

Content Bronnen

UnoCSS ondersteunt het extraheren van utilities gebruik uit meerdere bronnen:

• Pipeline - Extraheer direct uit je build tools pipeline
• Bestandssysteem - Extraheer uit je bestandssysteem door bestanden te lezen en te bekijken
• Inline - Extraheer uit inline platte tekst

Gebruik van utilities die uit verschillende bronnen komen worden samengevoegd en de uiteindelijke CSS gegenereerd.

Extraheren uit Build Tools Pipeline

Dit wordt ondersteund in de Vite en Webpack integraties.

UnoCSS zal de content lezen die door je build tools pipeline gaat en de utilities gebruik eruit extraheren. Dit is de meest efficiënte en nauwkeurige manier om te extraheren, aangezien we alleen de gebruik extraheren die daadwerkelijk in je app worden gebruikt slim zonder dat er extra bestands-I/O wordt gemaakt tijdens de extractie.

Standaard zal UnoCSS de utilities gebruik extraheren uit bestanden in je build pipeline met extensie .jsx, .tsx, .vue, .md, .html, .svelte, .astro en dan de juiste CSS on-demand genereren. .js en .ts bestanden zijn standaard NIET inbegrepen.

Om ze te configureren, kun je je uno.config.ts bijwerken:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // de standaard
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // js/ts bestanden opnemen
        'src/**/*.{js,ts}',
      ],
      // bestanden uitsluiten
      // exclude: []
    },
  },
})

Je kunt ook @unocss-include magic comment toevoegen, per bestand, overal in het bestand dat je wilt dat UnoCSS scant. Als je *.js of *.ts bestanden moet scannen, voeg ze toe in de configuratie om alle js/ts bestanden als scan doelen op te nemen.

// ./some-utils.js

// aangezien `.js` bestanden niet standaard zijn inbegrepen,
// vertelt de volgende comment UnoCSS om dit bestand geforceerd te scannen.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

Evenzo kun je ook @unocss-ignore toevoegen om het scannen en transformeren voor het hele bestand over te slaan.

Als je wilt dat UnoCSS een blok code overslaat zonder te worden geëxtraheerd in een willekeurig extracting bestand, kun je @unocss-skip-start @unocss-skip-end in paren gebruiken. Merk op dat het in paren moet worden gebruikt om effectief te zijn.

<p class="text-green text-xl">Green Large</p>

<!-- @unocss-skip-start -->
<!-- `text-red` zal niet worden geëxtraheerd -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

Extraheren uit Bestandssysteem

In gevallen waarin je integraties gebruikt die geen toegang hebben tot de build tools pipeline (bijvoorbeeld de PostCSS plugin), of je integreert met backend frameworks zodat de code niet door de pipeline gaat, kun je handmatig de bestanden specificeren die moeten worden geëxtraheerd.

export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html',
    ],
  },
})

De matched bestanden worden direct van het bestandssysteem gelezen en bekeken voor wijzigingen in dev mode.

Extraheren uit Inline Tekst

Daarnaast kun je ook utilities gebruik uit inline tekst extraheren, die je misschien ergens anders vandaan haalt.

Je kunt ook een async functie doorgeven om de content te retourneren. Maar merk op dat de functie alleen wordt aangeroepen tijdens de build tijd.

export default defineConfig({
  content: {
    inline: [
      // platte tekst
      '<div class="p-4 text-red">Some text</div>',
      // async getter
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})

Beperkingen

Aangezien UnoCSS werkt op build tijd, betekent dit dat alleen statisch gepresenteerde utilities worden gegenereerd en naar je app worden verzonden. Utilities die dynamisch worden gebruikt of van externe bronnen worden opgehaald tijdens runtime KUNNEN worden gedetecteerd of toegepast.

Safelist

Soms wil je misschien dynamische concatenaties gebruiken zoals:

<div class="p-${size}"></div>
<!-- dit werkt niet! -->

Vanwege het feit dat UnoCSS werkt op build time met statische extractie, kan het tijdens het compileren niet mogelijk alle combinaties van de utilities kennen. Hiervoor kun je de safelist optie configureren.

safelist: 'p-1 p-2 p-3 p-4'.split(' ')

De bijbehorende CSS wordt altijd gegenereerd:

.p-1 { padding: 0.25rem; }
.p-2 { padding: 0.5rem; }
.p-3 { padding: 0.75rem; }
.p-4 { padding: 1rem; }

Of flexibeler:

safelist: [
  ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
]

Als je op zoek bent naar een echte dynamische generatie op runtime, wil je misschien het @unocss/runtime pakket bekijken.

Statische Lijst Combinaties

Een andere manier om de beperking van dynamisch geconstrueerde utilities te omzeilen is dat je een object kunt gebruiken dat alle combinaties statisch vermeldt. Bijvoorbeeld, als je dit wilt:

<div class="text-${color} border-${color}"></div>
<!-- dit werkt niet! -->

Je kunt een object maken dat alle combinaties vermeldt (aangenomen dat je alle mogelijke waarden van color kent die je wilt gebruiken)

// Omdat ze statisch zijn, zal UnoCSS ze kunnen extraheren op build tijd
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

En dan gebruiken in je template:

<div class="${classes[color]}"></div>

Blocklist

Net als safelist kun je ook blocklist configureren om sommige utilities uit te sluiten van generatie. Dit is nuttig om enkele extractie false positives uit te sluiten. Anders dan safelist accepteert blocklist zowel string voor exacte match als reguliere expressie voor patroonmatch.

blocklist: [
  'p-1',
  /^p-[2-4]$/,
]

Dit sluit p-1 en p-2, p-3, p-4 uit van generatie.