Extrahieren

UnoCSS funktioniert, indem es nach der Verwendung von Utilities in Ihrer Codebasis sucht und das entsprechende CSS On-Demand generiert. Wir nennen diesen Prozess Extrahieren.

Inhaltsquellen

UnoCSS unterstützt das Extrahieren von Utilities-Verwendungen aus mehreren Quellen:

• Pipeline - Extrahieren direkt aus der Pipeline Ihrer Build-Tools
• Dateisystem - Extrahieren aus Ihrem Dateisystem durch Lesen und Überwachen von Dateien
• Inline - Extrahieren aus Inline-Text

Verwendungen von Utilities aus verschiedenen Quellen werden zusammengeführt und generieren das finale CSS.

Extrahieren aus Build-Tools-Pipeline

Dies wird in den Vite und Webpack Integrationen unterstützt.

UnoCSS liest den Inhalt, der durch Ihre Build-Tools-Pipeline geht, und extrahiert die Utilities-Verwendungen daraus. Dies ist der effizienteste und genaueste Weg zum Extrahieren, da wir nur die Verwendungen extrahieren, die tatsächlich in Ihrer App verwendet werden, intelligent ohne zusätzliche Datei-I/O während der Extraktion.

Standardmäßig extrahiert UnoCSS die Utilities-Verwendung aus Dateien in Ihrer Build-Pipeline mit der Erweiterung .jsx, .tsx, .vue, .md, .html, .svelte, .astro und generiert dann das entsprechende CSS On-Demand. .js und .ts Dateien sind standardmäßig NICHT enthalten.

Um sie zu konfigurieren, können Sie Ihre uno.config.ts aktualisieren:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // die Standardwerte
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // js/ts Dateien einschließen
        'src/**/*.{js,ts}',
      ],
      // Dateien ausschließen
      // exclude: []
    },
  },
})

Sie können auch den @unocss-include Magic-Kommentar pro Datei hinzufügen, überall in der Datei, die UnoCSS scannen soll. Wenn Sie *.js oder *.ts Dateien scannen müssen, fügen Sie sie in der Konfiguration hinzu, um alle js/ts Dateien als Scan-Ziele einzuschließen.

// ./some-utils.js

// da `.js` Dateien standardmäßig nicht enthalten sind,
// teilt der folgende Kommentar UnoCSS mit, diese Datei zu scannen.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

Ähnlich können Sie auch @unocss-ignore hinzufügen, um das Scannen und Transformieren für die gesamte Datei zu umgehen.

Wenn Sie möchten, dass UnoCSS einen Codeblock überspringt, ohne in irgendwelchen Extraktionsdateien extrahiert zu werden, können Sie @unocss-skip-start @unocss-skip-end paarweise verwenden. Beachten Sie, dass es paarweise verwendet werden muss, um wirksam zu sein.

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

<!-- @unocss-skip-start -->
<!-- `text-red` wird nicht extrahiert -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

Extrahieren aus Dateisystem

In Fällen, in denen Sie Integrationen verwenden, die keinen Zugriff auf die Build-Tools-Pipeline haben (z. B. das PostCSS Plugin), oder Sie mit Backend-Frameworks integrieren, sodass der Code nicht durch die Pipeline geht, können Sie die zu extrahierenden Dateien manuell angeben.

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

Die übereinstimmenden Dateien werden direkt aus dem Dateisystem gelesen und auf Änderungen im Dev-Modus überwacht.

Extrahieren aus Inline-Text

Zusätzlich können Sie auch Utilities-Verwendungen aus Inline-Text extrahieren, den Sie möglicherweise von anderswo abrufen.

Sie können auch eine async-Funktion übergeben, um den Inhalt zurückzugeben. Beachten Sie jedoch, dass die Funktion nur einmal zur Build-Zeit aufgerufen wird.

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

Einschränkungen

Da UnoCSS zur Build-Zeit arbeitet, bedeutet dies, dass nur statisch präsentierte Utilities generiert und an Ihre App geliefert werden. Utilities, die dynamisch verwendet oder zur Laufzeit aus externen Ressourcen abgerufen werden, werden möglicherweise NICHT erkannt oder angewendet.

Safelist

Manchmal möchten Sie möglicherweise dynamische Verkettungen wie diese verwenden:

<div class="p-${size}"></div>
<!-- das funktioniert nicht! -->

Aufgrund der Tatsache, dass UnoCSS zur Build-Zeit mit statischer Extraktion arbeitet, kann es zur Kompilierzeit nicht alle Kombinationen der Utilities kennen. Dafür können Sie die Option safelist konfigurieren.

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

Das entsprechende CSS wird immer generiert:

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

Oder flexibler:

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

Wenn Sie eine echte dynamische Generierung zur Laufzeit suchen, möchten Sie möglicherweise das @unocss/runtime Paket überprüfen.

Statische Listenkombinationen

Eine andere Möglichkeit, die Einschränkung von dynamisch konstruierten Utilities zu umgehen, ist die Verwendung eines Objekts, das alle Kombinationen statisch auflistet. Wenn Sie beispielsweise dies haben möchten:

<div class="text-${color} border-${color}"></div>
<!-- das funktioniert nicht! -->

Sie können ein Objekt erstellen, das alle Kombinationen auflistet (vorausgesetzt, Sie kennen alle möglichen Werte von color, die Sie verwenden möchten)

// Da sie statisch sind, kann UnoCSS sie zur Build-Zeit extrahieren
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

Und dann in Ihrer Vorlage verwenden:

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

Blocklist

Ähnlich wie safelist können Sie auch blocklist konfigurieren, um einige Utilities von der Generierung auszuschließen. Dies ist nützlich, um einige Extraktions-False-Positives auszuschließen. Im Gegensatz zu safelist akzeptiert blocklist sowohl String für exakte Übereinstimmung als auch regulären Ausdruck für Musterübereinstimmung.

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

Dies schließt p-1 und p-2, p-3, p-4 von der Generierung aus.