Extragere UnoCSS

UnoCSS funcționează prin căutarea utilizărilor utilităților din codul dvs. și generarea CSS-ului corespunzător la cerere. Numim acest proces extragere.

Surse de Conținut

UnoCSS acceptă extragerea utilizărilor utilităților din multiple surse:

• Pipeline - Extrage direct din pipeline-ul instrumentelor de build
• Sistem de fișiere - Extrage din sistemul de fișiere prin citirea și monitorizarea fișierelor
• Inline - Extrage din text inline simplu

Utilizările utilităților care provin din surse diferite vor fi combinate împreună și vor genera CSS-ul final.

Extragere din Pipeline-ul Instrumentelor de Build

Acesta este acceptat în integrările Vite și Webpack.

UnoCSS va citi conținutul care trece prin pipeline-ul instrumentelor de build și va extrage utilizările utilităților din acestea. Aceasta este cea mai eficientă și precisă modalitate de extragere, deoarece extragem doar utilizările care sunt efectiv utilizate în aplicația dvs. într-un mod inteligent, fără I/O suplimentar de fișiere în timpul extragerii.

În mod implicit, UnoCSS va extrage utilizarea utilităților din fișierele din pipeline-ul de build cu extensia .jsx, .tsx, .vue, .md, .html, .svelte, .astro și apoi va genera CSS-ul corespunzător la cerere. Fișierele .js și .ts NU sunt incluse în mod implicit.

Pentru a le configura, puteți actualiza uno.config.ts:

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

De asemenea, puteți adăuga comentariul magic @unocss-include, per-fișier, oriunde în fișierul pe care doriți să-l scaneze UnoCSS. Dacă trebuie să scanați fișiere *.js sau *.ts, adăugați-le în configurare pentru a include toate fișierele js/ts ca ținte de scanare.

// ./some-utils.js

// deoarece fișierele `.js` nu sunt incluse în mod implicit,
// comentariul următor îi spune lui UnoCSS să foreze scanarea acestui fișier.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

Similar, puteți adăuga și @unocss-ignore pentru a ocoli scanarea și transformarea pentru întregul fișier.

Dacă doriți ca UnoCSS să sară peste un bloc de cod fără a fi extras în niciun fișier de extragere, puteți utiliza @unocss-skip-start @unocss-skip-end în perechi. Rețineți că trebuie utilizat în perechi pentru a fi eficient.

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

<!-- @unocss-skip-start -->
<!-- `text-red` nu va fi extras -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

Extragere din Sistemul de Fișiere

În cazurile în care utilizați integrări care nu au acces la pipeline-ul instrumentelor de build (de exemplu, plugin-ul PostCSS), sau vă integrați cu framework-uri backend astfel încât codul nu trece prin pipeline, puteți specifica manual fișierele care trebuie extrase.

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

Fișierele potrivite vor fi citite direct din sistemul de fișiere și monitorizate pentru modificări în modul dev.

Extragere din Text Inline

În plus, puteți extrage și utilizările utilităților din text inline, pe care le puteți obține de aiurea.

De asemenea, puteți trece o funcție asincronă pentru a returna conținutul. Dar rețineți că funcția va fi apelată o singură dată în timpul build-ului.

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

Limitări

Deoarece UnoCSS funcționează la timpul de build, înseamnă că doar utilitățile prezentate static vor fi generate și livrate aplicației dvs. Utilitățile care sunt utilizate dinamic sau obținute din resurse externe în timpul rulării ar putea NU fi detectate sau aplicate.

Safelist

Uneori s-ar putea să doriți să utilizați concatenări dinamice precum:

<div class="p-${size}"></div>
<!-- asta nu va funcționa! -->

Datorită faptului că UnoCSS funcționează la timpul de build folosind extragere statică, în timpul compilării nu poate ști în mod posibil toate combinațiile utilităților. Pentru aceasta, puteți configura opțiunea safelist.

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

CSS-ul corespunzător va fi întotdeauna generat:

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

Sau mai flexibil:

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

Dacă căutați o generare cu adevărat dinamică în timpul rulării, poate doriți să verificați pachetul @unocss/runtime.

Combinații de Liste Statice

O altă modalitate de a ocoli limitarea utilităților construite dinamic este că puteți utiliza un obiect care listează toate combinațiile static. De exemplu, dacă doriți să aveți acest lucru:

<div class="text-${color} border-${color}"></div>
<!-- asta nu va funcționa! -->

Puteți crea un obiect care listează toate combinațiile (presupunând că știți orice valori posibile ale color pe care doriți să le utilizați)

// Deoarece sunt statice, UnoCSS le va putea extrage la timpul de build
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

Și apoi să-l utilizați în șablonul dvs.:

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

Blocklist

Similar cu safelist, puteți configura și blocklist pentru a exclude unele utilități din a fi generate. Acest lucru este util pentru a exclude unele false pozitive de extragere. Diferit de safelist, blocklist acceptă atât string pentru potrivire exactă, cât și expresie regulată pentru potrivire de tipar.

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

Aceasta va exclude p-1 și p-2, p-3, p-4 din a fi generate.