UnoCSS Extracting

UnoCSS pracuje tak, že hľadá použitia utilít vo vašej kódovej báze a generuje zodpovedajúce CSS na požiadanie. Tento proces nazývame extrakcia.

Content Sources

UnoCSS podporuje extrakciu použití utilít z viacerých zdrojov:

• Pipeline - Extrakcia priamo z pipeline vášho build nástroja
• Filesystem - Extrakcia čítaním a sledovaním súborov z vášho súborového systému
• Inline - Extrakcia z inline plain textu

Použitia utilít, ktoré pochádzajú z rôznych zdrojov, budú zlúčené a vygeneruje sa finálne CSS.

Extracting from Build Tools Pipeline

Toto je podporované v integráciách Vite a Webpack.

UnoCSS bude čítať obsah, ktorý prechádza pipeline vášho build nástroja a extrahovať použitia utilít z nich. Toto je najefektívnejší a najpresnejší spôsob extrakcie, pretože extrahujeme iba použitia, ktoré sa skutočne používajú vo vašej aplikácii, inteligentne bez dodatočného I/O súborov počas extrakcie.

Predvolene bude UnoCSS extrahovať použitia utilít zo súborov vo vašom build pipelíne s príponou .jsx, .tsx, .vue, .md, .html, .svelte, .astro a následne generovať príslušné CSS na požiadanie. Súbory .js a .ts nie sú predvolene zahrnuté.

Na ich konfiguráciu môžete aktualizovať váš uno.config.ts:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // predvolené
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // zahrnúť js/ts súbory
        'src/**/*.{js,ts}',
      ],
      // vylúčiť súbory
      // exclude: []
    },
  },
})

Môžete tiež pridať kúzelný komentár @unocss-include, pre každý súbor, kdekoľvek v súbore, ktorý chcete, aby UnoCSS skenovalo. Ak potrebujete skenovať súbory *.js alebo *.ts, pridajte ich do konfigurácie, aby ste zahrnuli všetky js/ts súbory ako ciele skenovania.

// ./some-utils.js

// keďže súbory `.js` nie sú predvolene zahrnuté,
// nasledujúci komentár povie UnoCSS, aby tento súbor force scanovalo.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

Podobne môžete tiež pridať @unocss-ignore na obídenie skenovania a transformácie pre celý súbor.

Ak chcete, aby UnoCSS preskočilo blok kódu bez extrakcie v akýchkoľvek extrakčných súboroch, môžete použiť páry @unocss-skip-start @unocss-skip-end. Upozorňujeme, že musí byť použitý v pároch, aby bol účinný.

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

<!-- @unocss-skip-start -->
<!-- `text-red` nebude extrahované -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

Extracting from Filesystem

V prípadoch, keď používate integrácie, ktoré nemajú prístup k pipeline build nástroja (napríklad PostCSS plugin), alebo keď integrujete s backendovými frameworkmi tak, že kód neprechádza pipelinou, môžete manuálne určiť súbory, ktoré sa majú extrahovať.

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

Zodpovedajúce súbory budú priamo čítané zo súborového systému a sledované pre zmeny v režime vývoja.

Extracting from Inline Text

Dodatočne môžete tiež extrahovať použitia utilít z inline textu, ktorý môžete získať odkiaľkoľvek.

Môžete tiež odovzdať asynchrónnu funkciu na vrátenie obsahu. Upozorňujeme však, že funkcia bude zavolaná iba raz v čase zostavenia.

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

Limitations

Keďže UnoCSS pracuje v čase zostavenia, znamená to, že iba staticky prezentované utility budú vygenerované a doručené do vašej aplikácie. Utility, ktoré sa používajú dynamicky alebo sa získavajú z externých zdrojov v čase behu, nemusia byť detegované alebo aplikované.

Safelist

Niekedy môžete chcieť použiť dynamické konkatenácie, ako napríklad:

<div class="p-${size}"></div>
<!-- toto nebude fungovať! -->

Pretože UnoCSS pracuje v čase zostavenia pomocou statickej extrakcie, v čase kompilácie nemôže vedieť všetky kombinácie utilít. Pre toto môžete nakonfigurovať možnosť safelist.

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

Zodpovedajúce CSS bude vždy vygenerované:

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

Alebo flexibilnejšie:

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

Ak hľadáte skutočne dynamické generovanie v čase behu, môžete si pozrieť balík @unocss/runtime.

Static List Combinations

Ďalšie spôsoby, ako obísť obmedzenie dynamicky konštruovaných utilít, sú, že môžete použiť objekt, ktorý vypisuje všetky kombinácie staticky. Napríklad, ak chcete mať toto:

<div class="text-${color} border-${color}"></div>
<!-- toto nebude fungovať! -->

Môžete vytvoriť objekt, ktorý vypisuje všetky kombinácie (za predpokladu, že poznáte všetky možné hodnoty color, ktoré chcete použiť)

// Keďže sú statické, UnoCSS ich bude môcť extrahovať v čase zostavenia
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

A potom ho použiť vo vašej šablóne:

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

Blocklist

Podobne ako safelist, môžete tiež nakonfigurovať blocklist na vylúčenie niektorých utilít z generovania. Toto je užitočné na vylúčenie niektorých falošne pozitívnych extrakcií. Na rozdiel od safelist, blocklist akceptuje reťazec pre presnú zhodu a regulárny výraz pre zhodu vzoru.

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

Toto vylúči p-1 a p-2, p-3, p-4 z generovania.