Extrahering

UnoCSS fungerar genom att söka efter verktygsanvändningar i din kodbas och generera motsvarande CSS on-demand. Vi kallar denna process extrahering.

Innehållskällor

UnoCSS stöder extrahering av verktygsanvändningar från flera källor:

• Pipeline - Extrahera direkt från din byggverktygs-pipeline
• Filsystem - Extrahera från ditt filsystem genom att läsa och övervaka filer
• Inline - Extrahera från inline vanlig text

Användningar av verktyg som kommer från olika källor kommer att slås samman och generera den slutliga CSS:en.

Extrahering från byggverktygs-pipeline

Detta stöds i Vite och Webpack integrationerna.

UnoCSS läser innehållet som går igenom din byggverktygs-pipeline och extraherar verktygsanvändningarna från dem. Detta är det mest effektiva och noggranna sättet att extrahera eftersom vi bara extraherar de användningar som faktiskt används i din app smart utan att ytterligare fil-I/O görs under extraheringen.

Som standard kommer UnoCSS att extrahera verktygsanvändningar från filer i din bygg-pipeline med extension .jsx, .tsx, .vue, .md, .html, .svelte, .astro och sedan generera lämplig CSS on-demand. .js och .ts filer är INTE inkluderade som standard.

För att konfigurera dem kan du uppdatera din uno.config.ts:

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

Du kan också lägga till @unocss-include magisk kommentar, per fil, var som helst i filen som du vill att UnoCSS ska skanna. Om du behöver skanna *.js eller *.ts filer, lägg till dem i konfigurationen för att inkludera alla js/ts filer som skanningsmål.

// ./some-utils.js

// eftersom `.js` filer inte är inkluderade som standard,
// kommer följande kommentar att tala om för UnoCSS att force skanna denna fil.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

På samma sätt kan du också lägga till @unocss-ignore för att kringgå skanning och transformering för hela filen.

Om du vill att UnoCSS ska hoppa över ett kodblock utan att extraheras i några extraheringsfiler kan du använda @unocss-skip-start @unocss-skip-end i par. Observera att det måste användas i par för att vara effektivt.

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

<!-- @unocss-skip-start -->
<!-- `text-red` kommer inte att extraheras -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

Extrahering från filsystemet

I fall där du använder integrationer som inte har tillgång till byggverktygs-pipelinen (till exempel PostCSS plugin), eller om du integrerar med backend-ramverk så att koden inte går igenom pipelinen, kan du manuellt ange vilka filer som ska extraheras.

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

De matchade filerna kommer att läsas direkt från filsystemet och övervakas för ändringar i dev-läge.

Extrahering från inline-text

Dessutom kan du också extrahera verktygsanvändningar från inline-text som du kan hämta från någon annanstans.

Du kan också skicka en async-funktion för att returnera innehållet. Men observera att funktionen bara kommer att anropas en gång vid byggtiden.

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

Begränsningar

Eftersom UnoCSS fungerar vid byggtid, betyder det att endast statiskt presenterade verktyg kommer att genereras och levereras till din app. Verktyg som används dynamiskt eller hämtas från externa resurser vid körtid kanske INTE upptäcks eller tillämpas.

Safelist

Ibland kan du vilja använda dynamiska konkateneringar som:

<div class="p-${size}"></div>
<!-- detta kommer inte att fungera! -->

På grund av att UnoCSS fungerar vid byggtid med statisk extrahering, kan det vid kompileringstiden inte veta alla kombinationer av verktygen då. För det kan du konfigurera alternativet safelist.

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

Motsvarande CSS kommer alltid att genereras:

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

Eller mer flexibelt:

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

Om du söker efter en äkta dynamisk generering vid körtid kan du kolla in @unocss/runtime paketet.

Statiska listkombinationer

Andra sätt att kringgå begränsningen för dynamiskt konstruerade verktyg är att du kan använda ett objekt som listar alla kombinationer statiskt. Till exempel, om du vill ha detta:

<div class="text-${color} border-${color}"></div>
<!-- detta kommer inte att fungera! -->

Du kan skapa ett objekt som listar alla kombinationer (förutsatt att du vet alla möjliga värden på color du vill använda)

// Eftersom de är statiska kommer UnoCSS att kunna extrahera dem vid byggtid
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

Och sedan använda det i din mall:

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

Blocklist

Liksom safelist kan du också konfigurera blocklist för att exkludera vissa verktyg från att genereras. Detta är användbart för att exkludera vissa extraherings-falska positiver. Till skillnad från safelist, accepterar blocklist både sträng för exakt matchning och reguljärt uttryck för mönstermatchning.

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

Detta kommer att exkludera p-1 och p-2, p-3, p-4 från att genereras.