Ekstrahowanie w UnoCSS

UnoCSS działa poprzez wyszukiwanie użycia narzędzi w kodzie i generowanie odpowiedniego CSS na żądanie. Ten proces nazywamy ekstrahowaniem.

Źródła zawartości

UnoCSS obsługuje ekstrahowanie użycia narzędzi z wielu źródeł:

• Pipeline - Ekstrahowanie bezpośrednio z pipeline narzędzi budowania
• System plików - Ekstrahowanie z systemu plików poprzez odczytywanie i obserwowanie plików
• Inline - Ekstrahowanie z wbudowanego plain text

Użycia narzędzi z różnych źródeł zostaną połączone i wygenerują końcowy CSS.

Ekstrahowanie z Pipeline Narzędzi Budowania

Jest to obsługiwane w integracjach Vite i Webpack.

UnoCSS odczyta zawartość, która przechodzi przez pipeline narzędzi budowania i wyekstrahuje użycia narzędzi z nich. Jest to najbardziej efektywny i dokładny sposób ekstrahowania, ponieważ ekstrahowane są tylko te użycia, które są faktycznie używane w Twojej aplikacji, bez dodatkowego I/O plików podczas ekstrahowania.

Domyślnie, UnoCSS wyekstrahuje użycia narzędzi z plików w pipeline budowania z rozszerzeniami .jsx, .tsx, .vue, .md, .html, .svelte, .astro, a następnie wygeneruje odpowiedni CSS na żądanie. Pliki .js i .ts NIE są domyślnie dołączone.

Aby je skonfigurować, możesz zaktualizować swój uno.config.ts:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // domyślne
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // dołącz pliki js/ts
        'src/**/*.{js,ts}',
      ],
      // wyklucz pliki
      // exclude: []
    },
  },
})

Możesz również dodać magiczny komentarz @unocss-include, dla pojedynczego pliku, w dowolnym miejscu w pliku, który chcesz, aby UnoCSS skanował. Jeśli musisz skanować pliki *.js lub *.ts, dodaj je w konfiguracji, aby uwzględnić wszystkie pliki js/ts jako cele skanowania.

// ./some-utils.js

// ponieważ pliki `.js` nie są domyślnie dołączone,
// poniższy komentarz mówi UnoCSS, aby wymusić skanowanie tego plika.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

Podobnie, możesz również dodać @unocss-ignore, aby pominąć skanowanie i transformowanie dla całego pliku.

Jeśli chcesz, aby UnoCSS pomijał blok kodu bez ekstrahowania w jakichkolwiek plikach ekstrahowania, możesz użyć @unocss-skip-start @unocss-skip-end parami. Zauważ, że musi być użyte w parach, aby było skuteczne.

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

<!-- @unocss-skip-start -->
<!-- `text-red` nie zostanie wyekstrahowany -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

Ekstrahowanie z Systemu Plików

W przypadkach, gdy używasz integracji, która nie ma dostępu do pipeline narzędzi budowania (na przykład wtyczka PostCSS), lub integrujesz się z frameworkami backendowymi, tak że kod nie przechodzi przez pipeline, możesz ręcznie określić pliki do ekstrahowania.

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

Dopasowane pliki będą odczytywane bezpośrednio z systemu plików i obserwowane pod kątem zmian w trybie dev.

Ekstrahowanie z Tekstu Inline

Dodatkowo, możesz również wyekstrahować użycia narzędzi z tekstu inline, który możesz pobrać skądinąd.

Możesz również przekazać funkcję asynchroniczną, aby zwrócić zawartość. Zauważ jednak, że funkcja zostanie wywołana tylko raz podczas budowania.

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()
      },
    ],
  },
})

Ograniczenia

Ponieważ UnoCSS działa w czasie budowania, oznacza to, że tylko statycznie przedstawione narzędzia zostaną wygenerowane i wysłane do Twojej aplikacji. Narzędzia, które są używane dynamicznie lub pobierane z zewnętrznych zasobów w czasie działania, mogą NIE zostać wykryte lub zastosowane.

Safelist

Czasami możesz chcieć użyć dynamicznych konkatenacji jak:

<div class="p-${size}"></div>
<!-- to nie zadziała! -->

Z faktu, że UnoCSS działa w czasie budowania używając statycznego ekstrahowania, w czasie kompilacji nie jest możliwe poznanie wszystkich kombinacji narzędzi. W tym celu, możesz skonfigurować opcję safelist.

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

Odpowiedni CSS zawsze zostanie wygenerowany:

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

Lub bardziej elastycznie:

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

Jeśli szukasz prawdziwej dynamicznej generacji w czasie działania, możesz sprawdzić pakiet @unocss/runtime.

Kombinacje List Statycznych

Innym sposobem na obejście ograniczenia dynamicznie konstruowanych narzędzi jest to, że możesz użyć obiektu, który wymienia wszystkie kombinacje statycznie. Na przykład, jeśli chcesz mieć to:

<div class="text-${color} border-${color}"></div>
<!-- to nie zadziała! -->

Możesz utworzyć obiekt, który wymienia wszystkie kombinacje (zakładając, że znasz wszystkie możliwe wartości color, których chcesz użyć)

// Ponieważ są statyczne, UnoCSS będzie w stanie wyekstrahować je w czasie budowania
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

A następnie użyć tego w szablonie:

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

Blocklist

Podobnie jak safelist, możesz również skonfigurować blocklist, aby wykluczyć niektóre narzędzia z generowania. Jest to przydatne do wykluczenia fałszywych pozytywów ekstrahowania. W przeciwieństwie do safelist, blocklist akceptuje zarówno string dla dokładnego dopasowania, jak i wyrażenie regularne dla dopasowania wzorca.

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

To wykluczy p-1 oraz p-2, p-3, p-4 z generowania.