Extração

O UnoCSS funciona procurando os usos de utilitários em sua base de código e gerando o CSS correspondente sob demanda. Chamamos esse processo de extração.

Fontes de Conteúdo

O UnoCSS suporta a extração de usos de utilitários de múltiplas fontes:

• Pipeline - Extrair diretamente do pipeline de suas ferramentas de construção
• Sistema de Arquivos - Extrair do seu sistema de arquivos lendo e observando arquivos
• Inline - Extrair de texto simples inline

Usos de utilitários provenientes de diferentes fontes serão mesclados e gerarão o CSS final.

Extraindo do Pipeline de Ferramentas de Construção

Isso é suportado nas integrações do Vite e do Webpack.

O UnoCSS lerá o conteúdo que passa pelo pipeline de suas ferramentas de construção e extrairá os usos de utilitários deles. Esta é a maneira mais eficiente e precisa de extrair, pois extraímos apenas os usos que são realmente utilizados em seu aplicativo de forma inteligente, sem realizar I/O de arquivo adicional durante a extração.

Por padrão, o UnoCSS extrairá o uso de utilitários de arquivos em seu pipeline com extensões .jsx, .tsx, .vue, .md, .html, .svelte, .astro e, em seguida, gerará o CSS apropriado sob demanda. Arquivos .js e .ts NÃO são incluídos por padrão.

Para configurá-los, você pode atualizar seu uno.config.ts:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // o padrão
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // incluir arquivos js/ts
        'src/**/*.{js,ts}',
      ],
      // excluir arquivos
      // exclude: []
    },
  },
})

Você também pode adicionar o comentário mágico @unocss-include em qualquer lugar do arquivo que deseja que o UnoCSS escaneie, em uma base por arquivo. Se precisar escanear arquivos *.js ou *.ts, adicione-os na configuração para incluir todos os arquivos js/ts como alvos de varredura.

// ./some-utils.js

// como os arquivos `.js` não são incluídos por padrão,
// o seguinte comentário diz ao UnoCSS para forçar o escaneamento deste arquivo.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

Da mesma forma, você também pode adicionar @unocss-ignore para ignorar a varredura e transformação para todo o arquivo.

Se você quiser que o UnoCSS pule um bloco de código sem ser extraído em qualquer arquivo de extração, pode usar @unocss-skip-start @unocss-skip-end em pares. Note que deve ser usado em pares para ser efetivo.

<p class="text-green text-xl">Verde Grande</p>

<!-- @unocss-skip-start -->
<!-- `text-red` não será extraído -->
<p class="text-red">Vermelho</p>
<!-- @unocss-skip-end -->

Extraindo do Sistema de Arquivos

Em casos em que você está usando integrações que não têm acesso ao pipeline de ferramentas de construção (por exemplo, o plugin PostCSS), ou está integrando com frameworks de backend de modo que o código não passa pelo pipeline, você pode especificar manualmente os arquivos a serem extraídos.

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

Os arquivos correspondentes serão lidos diretamente do sistema de arquivos e observados para mudanças no modo de desenvolvimento.

Extraindo de Texto Inline

Adicionalmente, você pode extrair usos de utilitários de texto inline que pode recuperar de outros lugares.

Você também pode passar uma função assíncrona para retornar o conteúdo. Mas note que a função será chamada apenas uma vez no momento da compilação.

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

Limitações

Como o UnoCSS funciona no momento da compilação, significa que apenas os utilitários apresentados estaticamente serão gerados e enviados para seu aplicativo. Utilitários usados dinamicamente ou buscados de recursos externos em tempo de execução podem NÃO ser detectados ou aplicados.

Lista de Segurança (Safelist)

Às vezes, você pode querer usar concatenações dinâmicas como:

<div class="p-${size}"></div>
<!-- isso não vai funcionar! -->

Devido ao fato de o UnoCSS funcionar no momento da compilação usando extração estática, no momento da compilação, não é possível saber todas as combinações de utilitários. Para isso, você pode configurar a opção safelist.

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

O CSS correspondente será sempre gerado:

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

Ou de forma mais flexível:

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

Se você está procurando uma geração verdadeiramente dinâmica em tempo de execução, pode querer conferir o pacote @unocss/runtime.

Combinações de Lista Estática

Outra forma de contornar a limitação de utilitários construídos dinamicamente é usar um objeto que liste todas as combinações estaticamente. Por exemplo, se você quiser fazer isso:

<div class="text-${color} border-${color}"></div>
<!-- isso não vai funcionar! -->

Você pode criar um objeto que liste todas as combinações (assumindo que você conheça todos os possíveis valores de color que deseja usar)

// Como são estáticos, o UnoCSS poderá extraí-los no momento da compilação
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

E então usá-lo em seu template:

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

Lista de Bloqueio (Blocklist)

Semelhante ao safelist, você também pode configurar blocklist para excluir alguns utilitários de serem gerados. Isso é útil para excluir alguns falsos positivos de extração. Diferente do safelist, blocklist aceita tanto strings para correspondência exata quanto expressões regulares para correspondência de padrão.

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

Isso excluirá p-1 e p-2, p-3, p-4 de serem gerados.