Извлечение

UnoCSS работает, выполняя поиск использования утилит в вашей кодовой базе и генерируя соответствующий CSS по требованию. Мы называем этот процесс извлечением.

Источники контента

UnoCSS поддерживает извлечение использования утилит из нескольких источников:

• Конвейер - Извлечение прямо из конвейера инструментов сборки
• Файловая система - Извлечение из файловой системы путем чтения и отслеживания файлов
• Встроенный - Извлечение из встроенного простого текста

Использование утилит из разных источников будет объединено и сгенерирует итоговый CSS.

Извлечение из конвейера инструментов сборки

Это поддерживается в интеграциях Vite и Webpack.

UnoCSS будет читать контент, проходящий через конвейер инструментов сборки, и извлекать использование утилит. Это самый эффективный и точный способ извлечения, так как мы извлекаем только фактически используемые утилиты в вашем приложении, без дополнительного ввода-вывода файлов во время извлечения.

По умолчанию UnoCSS будет извлекать использование утилит из файлов в конвейере сборки с расширениями .jsx, .tsx, .vue, .md, .html, .svelte, .astro, а затем генерировать соответствующий CSS по требованию. Файлы .js и .ts не включаются по умолчанию.

Чтобы настроить их, вы можете обновить uno.config.ts:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // по умолчанию
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // включить файлы js/ts
        'src/**/*.{js,ts}',
      ],
      // исключить файлы
      // exclude: []
    },
  },
})

Вы также можете добавить магический комментарий @unocss-include в любом месте файла, чтобы UnoCSS его просканировал. Если вам нужно сканировать файлы *.js или *.ts, добавьте их в конфигурацию, чтобы включить все js/ts файлы в цели сканирования.

// ./some-utils.js

// поскольку `.js` файлы не включены по умолчанию,
// следующий комментарий указывает UnoCSS принудительно просканировать этот файл.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

Аналогично, вы можете добавить @unocss-ignore, чтобы пропустить сканирование и преобразование для всего файла.

Если вы хотите, чтобы UnoCSS пропустил блок кода без извлечения в любых извлекаемых файлах, вы можете использовать пары @unocss-skip-start @unocss-skip-end. Обратите внимание, что они должны использоваться парами, чтобы быть эффективными.

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

<!-- @unocss-skip-start -->
<!-- `text-red` не будет извлечен -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

Извлечение из файловой системы

В случаях, когда вы используете интеграции без доступа к конвейеру инструментов сборки (например, плагин PostCSS), или интегрируетесь с бэкенд-фреймворками, где код не проходит через конвейер, вы можете вручную указать файлы для извлечения.

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

Сопоставленные файлы будут прочитаны напрямую из файловой системы и отслеживаться на изменения в режиме разработки.

Извлечение из встроенного текста

Дополнительно вы можете извлекать использование утилит из встроенного текста, который вы можете получить откуда-либо.

Вы также можете передать асинхронную функцию для возврата содержимого. Но имейте в виду, что функция будет вызвана только один раз во время сборки.

export default defineConfig({
  content: {
    inline: [
      // простой текст
      '<div class="p-4 text-red">Some text</div>',
      // асинхронный получатель
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})

Ограничения

Поскольку UnoCSS работает во время сборки, это означает, что будут сгенерированы и отправлены в ваше приложение только статически представленные утилиты. Утилиты, используемые динамически или загруженные из внешних ресурсов во время выполнения, МОГУТ НЕ быть обнаружены или применены.

Список безопасности

Иногда вы можете захотеть использовать динамические конкатенации, например:

<div class="p-${size}"></div>
<!-- это не сработает! -->

Из-за того, что UnoCSS работает во время сборки с использованием статического извлечения, во время компиляции невозможно знать все комбинации утилит. Для этого вы можете настроить опцию safelist.

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

Соответствующий CSS всегда будет сгенерирован:

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

Или более гибко:

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

Если вы ищете истинную динамическую генерацию во время выполнения, вам может пригодиться пакет @unocss/runtime.

Статические комбинации списков

Другой способ обойти ограничение динамически сконструированных утилит - использовать объект, который статически перечисляет все комбинации. Например, если вы хотите сделать так:

<div class="text-${color} border-${color}"></div>
<!-- это не сработает! -->

Вы можете создать объект, перечисляющий все комбинации (предполагая, что вы знаете все возможные значения color, которые хотите использовать)

// Поскольку они статические, UnoCSS сможет извлечь их во время сборки
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

И затем использовать его в шаблоне:

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

Список блокировки

Аналогично safelist, вы также можете настроить blocklist, чтобы исключить некоторые утилиты из генерации. Это полезно для исключения ложных срабатываний извлечения. В отличие от safelist, blocklist принимает как строки для точного совпадения, так и регулярные выражения для сопоставления по шаблону.

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

Это исключит генерацию p-1, p-2, p-3, p-4.