Estrazione

UnoCSS funziona cercando gli utilizzi delle utility dalla tua codebase e generando il CSS corrispondente on-demand. Chiamiamo questo processo estrazione.

Fonti di Contenuto

UnoCSS supporta l'estrazione degli utilizzi delle utility da più fonti:

• Pipeline - Estrai direttamente dalla pipeline dei tuoi strumenti di build
• File system - Estrai dal tuo file system leggendo e monitorando i file
• Inline - Estrai da testo inline semplice

Gli utilizzi delle utility che provengono da fonti diverse verranno uniti insieme e genereranno il CSS finale.

Estrazione dalla Pipeline degli Strumenti di Build

Questo è supportato nelle integrazioni Vite e Webpack.

UnoCSS leggerà il contenuto che passa attraverso la pipeline dei tuoi strumenti di build ed estrarrà gli utilizzi delle utility da essi. Questo è il modo più efficiente e accurato per estrarre poiché estraiamo solo gli utilizzi che sono effettivamente usati nella tua app in modo intelligente senza alcuna I/O di file aggiuntiva durante l'estrazione.

Per impostazione predefinita, UnoCSS estrarrà l'utilizzo delle utility dai file nella tua pipeline di build con estensione .jsx, .tsx, .vue, .md, .html, .svelte, .astro e poi genererà il CSS appropriato on-demand. I file .js e .ts NON sono inclusi per impostazione predefinita.

Per configurarli, puoi aggiornare il tuo uno.config.ts:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // i valori predefiniti
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // includi file js/ts
        'src/**/*.{js,ts}',
      ],
      // escludi file
      // exclude: []
    },
  },
})

Puoi anche aggiungere il commento magico @unocss-include, per file, ovunque nel file che vuoi che UnoCSS scansiona. Se devi scansionare file *.js o *.ts, aggiungili nella configurazione per includere tutti i file js/ts come target di scansione.

// ./some-utils.js

// poiché i file `.js` non sono inclusi per impostazione predefinita,
// il seguente commento dice a UnoCSS di forzare la scansione di questo file.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

Allo stesso modo, puoi anche aggiungere @unocss-ignore per bypassare la scansione e la trasformazione per l'intero file.

Se vuoi che UnoCSS salti un blocco di codice senza essere estratto in alcun file di estrazione, puoi usare @unocss-skip-start @unocss-skip-end in coppia. Nota che deve essere usato in coppia per essere efficace.

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

<!-- @unocss-skip-start -->
<!-- `text-red` non sarà estratto -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

Estrazione dal File System

Nei casi in cui stai usando integrazioni che non hanno accesso alla pipeline degli strumenti di build (ad esempio, il plugin PostCSS), o stai integrando con framework backend in modo che il codice non passi attraverso la pipeline, puoi specificare manualmente i file da estrarre.

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

I file corrispondenti verranno letti direttamente dal file system e monitorati per le modifiche in modalità dev.

Estrazione da Testo Inline

Inoltre, puoi anche estrarre utilizzi delle utility da testo inline, che potresti recuperare da altrove.

Puoi anche passare una funzione async per restituire il contenuto. Ma nota che la funzione verrà chiamata solo una volta al momento della build.

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

Limitazioni

Poiché UnoCSS funziona al momento della build, significa che solo le utility presentate staticamente saranno generate e inviate alla tua app. Le utility che sono usate dinamicamente o recuperate da risorse esterne a runtime potrebbero NON essere rilevate o applicate.

Safelist

A volte potresti voler usare concatenazioni dinamiche come:

<div class="p-${size}"></div>
<!-- questo non funzionerà! -->

A causa del fatto che UnoCSS funziona al momento della build usando l'estrazione statica, al momento della compilazione non può conoscere tutte le combinazioni delle utility. Per questo, puoi configurare l'opzione safelist.

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

Il CSS corrispondente sarà sempre generato:

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

O più flessibile:

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

Se stai cercando una vera generazione dinamica a runtime, potresti voler controllare il pacchetto @unocss/runtime.

Combinazioni di Liste Statiche

Un altro modo per aggirare la limitazione delle utility costruite dinamicamente è che puoi usare un oggetto che elenca tutte le combinazioni staticamente. Ad esempio, se vuoi avere questo:

<div class="text-${color} border-${color}"></div>
<!-- questo non funzionerà! -->

Puoi creare un oggetto che elenca tutte le combinazioni (supponendo che tu conosca tutti i possibili valori di color che vuoi usare)

// Poiché sono statici, UnoCSS sarà in grado di estrarli al momento della build
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

E poi usarlo nel tuo template:

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

Blocklist

Simile a safelist, puoi anche configurare blocklist per escludere alcune utility dalla generazione. Questo è utile per escludere alcuni falsi positivi di estrazione. Diversamente da safelist, blocklist accetta sia stringa per corrispondenza esatta che espressione regolare per corrispondenza di pattern.

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

Questo escluderà p-1 e p-2, p-3, p-4 dalla generazione.