Extraction

UnoCSS fonctionne en recherchant l'utilisation des utilitaires dans votre base de code et en générant le CSS correspondant à la demande. Nous appelons ce processus extraction.

Sources de contenu

UnoCSS prend en charge l'extraction de l'utilisation des utilitaires à partir de plusieurs sources :

• Pipeline - Extraction directement depuis le pipeline de vos outils de build
• Système de fichiers - Extraction depuis votre système de fichiers en lisant et surveillant les fichiers
• Inline - Extraction depuis du texte brut en ligne

Les utilisations d'utilitaires provenant de différentes sources seront fusionnées pour générer le CSS final.

Extraction depuis le pipeline des outils de build

Ceci est pris en charge dans les intégrations Vite et Webpack.

UnoCSS lira le contenu qui passe par le pipeline de vos outils de build et extraira les utilisations d'utilitaires à partir de là. C'est la manière la plus efficace et précise d'extraire car nous ne récupérons que les utilisations réellement présentes dans votre application, sans accès supplémentaire au système de fichiers pendant l'extraction.

Par défaut, UnoCSS extrait l'utilisation des utilitaires à partir des fichiers de votre pipeline de build avec les extensions .jsx, .tsx, .vue, .md, .html, .svelte, .astro et génère ensuite le CSS approprié à la demande. Les fichiers .js et .ts ne sont PAS inclus par défaut.

Pour les configurer, vous pouvez mettre à jour votre uno.config.ts :

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // par défaut
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // inclure les fichiers js/ts
        'src/**/*.{js,ts}',
      ],
      // exclure des fichiers
      // exclude: []
    },
  },
})

Vous pouvez également ajouter le commentaire magique @unocss-include, par fichier, n'importe où dans le fichier que vous souhaitez que UnoCSS analyse. Si vous avez besoin d'analyser des fichiers *.js ou *.ts, ajoutez-les dans la configuration pour inclure tous les fichiers js/ts comme cibles d'analyse.

// ./some-utils.js

// comme les fichiers `.js` ne sont pas inclus par défaut,
// le commentaire suivant indique à UnoCSS de forcer l'analyse de ce fichier.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

De même, vous pouvez aussi ajouter @unocss-ignore pour ignorer l'analyse et la transformation pour tout le fichier.

Si vous souhaitez que UnoCSS ignore un bloc de code sans l'extraire dans aucun fichier d'extraction, vous pouvez utiliser @unocss-skip-start et @unocss-skip-end par paires. Notez qu'il faut toujours les utiliser par paires pour que cela soit effectif.

<p class="text-green text-xl">Vert Grand</p>

<!-- @unocss-skip-start -->
<!-- `text-red` ne sera pas extrait -->
<p class="text-red">Rouge</p>
<!-- @unocss-skip-end -->

Extraction depuis le système de fichiers

Dans le cas où vous utilisez des intégrations qui n'ont pas accès au pipeline des outils de build (par exemple, le plugin PostCSS), ou si vous intégrez avec des frameworks backend de sorte que le code ne passe pas par le pipeline, vous pouvez spécifier manuellement les fichiers à extraire.

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

Les fichiers correspondants seront lus directement depuis le système de fichiers et surveillés pour les changements en mode développement.

Extraction depuis du texte en ligne

Vous pouvez également extraire l'utilisation des utilitaires à partir de texte brut en ligne, que vous pouvez récupérer d'ailleurs.

Vous pouvez aussi passer une fonction asynchrone pour retourner le contenu. Notez cependant que la fonction ne sera appelée qu'une seule fois lors du build.

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

Limitations

Comme UnoCSS fonctionne au moment du build, cela signifie que seules les utilités présentes statiquement seront générées et livrées à votre application. Les utilités utilisées dynamiquement ou récupérées à partir de ressources externes à l'exécution pourraient NE PAS être détectées ou appliquées.

Safelist (liste blanche)

Parfois, vous voudrez peut-être utiliser des concaténations dynamiques comme :

<div class="p-${size}"></div>
<!-- ceci ne fonctionnera pas ! -->

Du fait qu'UnoCSS fonctionne au moment du build en utilisant une extraction statique, il ne peut pas connaître toutes les combinaisons possibles des utilitaires à la compilation. Pour cela, vous pouvez configurer l'option safelist.

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

Le CSS correspondant sera toujours généré :

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

Ou de façon plus flexible :

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

Si vous cherchez une vraie génération dynamique à l'exécution, vous pouvez consulter le package @unocss/runtime.

Combinaisons de listes statiques

Une autre façon de contourner la limitation des utilitaires construits dynamiquement est d'utiliser un objet qui liste toutes les combinaisons statiquement. Par exemple, si vous voulez avoir ceci :

<div class="text-${color} border-${color}"></div>
<!-- ceci ne fonctionnera pas ! -->

Vous pouvez créer un objet qui liste toutes les combinaisons (en supposant que vous connaissez toutes les valeurs possibles de color que vous souhaitez utiliser)

// Comme elles sont statiques, UnoCSS pourra les extraire au moment du build
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

Et ensuite l'utiliser dans votre template :

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

Blocklist (liste noire)

Similaire à safelist, vous pouvez aussi configurer blocklist pour exclure certains utilitaires de la génération. Ceci est utile pour exclure certains faux positifs d'extraction. Contrairement à safelist, blocklist accepte à la fois une chaîne pour une correspondance exacte et une expression régulière pour une correspondance par motif.

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

Cela exclura p-1 ainsi que p-2, p-3, p-4 de la génération.