Настройка UnoCSS

Конфигурация

Конфигурации — это то, что делает UnoCSS мощным.

• Правила — Определяют утилиты атомарного CSS.
• Шорткаты — Объединяют несколько правил в одно сокращение.
• Тема — Определяет переменные темы.
• Варианты — Применяют пользовательские соглашения к правилам.
• Экстракторы — Определяют, где и как извлекаются использования утилит.
• Префлайты — Определяют глобальный «сырой» CSS.
• Слои — Определяют порядок каждого слоя утилит.
• Пресеты — Предопределённые конфигурации для общих случаев использования.
• Трансформеры — Преобразователи кода, применяемые к исходному коду пользователя для поддержки соглашений.
• Автодополнение — Определяет пользовательские предложения автодополнения.

Опции

rules

• Тип: Rule<Theme>[]

Правила для генерации CSS-утилит. Более поздние записи имеют более высокий приоритет.

shortcuts

• Тип: UserShortcuts<Theme>

По аналогии с шорткатами Windi CSS, позволяет создавать новые утилиты, комбинируя существующие. Более поздние записи имеют более высокий приоритет.

theme

• Тип: Theme

Объект темы для общей конфигурации между правилами.

extendTheme

• Тип: Arrayable<ThemeExtender<Theme>> Пользовательские функции, мутирующие объект темы.

Также возможно вернуть новый объект темы, чтобы полностью заменить исходный.

variants

• Тип: Variant<Theme>[]

Варианты, которые предварительно обрабатывают селекторы, имея возможность перезаписывать объект CSS.

extractors

• Тип: Extractor[]

Экстракторы для обработки исходного файла и вывода возможных классов/селекторов. Могут учитывать синтаксис языка.

preflights

• Тип: Preflight<Theme>[]

Инъекции «сырого» CSS.

layers

• Тип: Record<string, number>

Порядок слоев. По умолчанию 0.

outputToCssLayers

• Тип: boolean | UseCssLayersOptions
• По умолчанию: false

Выводит слои в каскадные слои CSS (CSS Cascade Layers).

cssLayerName

• Тип: (internalLayer: string) => string | undefined | null

Указывает имя CSS-слоя, в который должен быть выведен внутренний слой (может быть подслоем, например, "mylayer.mysublayer").

Если возвращается undefined, имя внутреннего слоя будет использовано в качестве имени CSS-слоя. Если возвращается null, внутренний слой не будет выведен в CSS-слой.

allLayers

• Тип: boolean

Принудительно выводить все CSS-слои, даже если они не используются.

Например:

@layer theme, preflights, [unused-layer], default;

sortLayers

• Тип: (layers: string[]) => string[]

Пользовательская функция для сортировки слоев.

presets

• Тип: (PresetOrFactory<Theme> | PresetOrFactory<Theme>[])[]

Предопределенные конфигурации для общих случаев использования.

transformers

• Тип: SourceCodeTransformer[]

Пользовательские трансформеры для исходного кода.

blocklist

• Тип: BlocklistRule[]

Правила для исключения селекторов из вашей дизайн-системы (чтобы сузить возможности). Комбинирование с опцией warnExcluded также может помочь выявить неправильное использование.

safelist

• Тип: string[]

Утилиты, которые всегда включены.

preprocess

• Тип: Arrayable<Preprocessor>

Предварительная обработка входящих утилит; верните ложное (falsy) значение для исключения.

postprocess

• Тип: Arrayable<Postprocessor>

Постобработка сгенерированного объекта утилит.

separators

• Тип: Arrayable<string>
• По умолчанию: [':', '-']

Разделитель вариантов.

extractorDefault

• Тип: Extractor | null | false
• По умолчанию: import('@unocss/core').defaultExtractor

Дефолтный экстрактор, который применяется всегда. По умолчанию он разбивает исходный код по пробелам и кавычкам.

Может быть заменен пресетом или пользовательским конфигом; может присутствовать только один дефолтный экстрактор, более поздний переопределяет предыдущий.

Передайте null или false, чтобы отключить дефолтный экстрактор.

autocomplete

Дополнительные опции для автодополнения.

templates

• Тип: Arrayable<AutoCompleteFunction | AutoCompleteTemplate>

Пользовательские функции / шаблоны для предоставления предложений автодополнения.

extractors

• Тип: Arrayable<AutoCompleteExtractor>

Пользовательские экстракторы для подбора возможных классов и преобразования предложений в стиле имен классов в правильный формат.

shorthands

• Тип: Record<string, string | string[]>

Пользовательские сокращения для предоставления предложений автодополнения. Если значение является массивом, оно будет объединено с помощью | и обернуто в ().

content

Опции для источников, из которых будут извлекаться использования утилит.

Поддерживаемые источники:

• filesystem — извлечение из файловой системы
• inline — извлечение из обычного инлайн-текста
• pipeline — извлечение из конвейера трансформации инструментов сборки, таких как Vite и Webpack

Использования, извлеченные из каждого источника, будут объединены.

filesystem

• Тип: string[]
• По умолчанию: []

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

В режиме разработки (dev mode) файлы будут отслеживаться и вызывать HMR.

inline

• Тип: string | { code: string; id?: string } | (() => Awaitable<string | { code: string; id?: string }>)) []

Инлайн-текст для извлечения.

pipeline

Фильтры для определения того, следует ли извлекать определенные модули из конвейера трансформации инструментов сборки.

В настоящее время работает только для интеграций Vite и Webpack.

Установите false для отключения.

include

• Тип: FilterPattern
• По умолчанию: [/\.(vue|svelte|[jt]sx|vine.ts|mdx?|astro|elm|php|phtml|html)($|\?)/]

Шаблоны, фильтрующие файлы, подлежащие извлечению. Поддерживает регулярные выражения и glob-шаблоны picomatch.

По умолчанию файлы .ts и .js НЕ извлекаются.

exclude

• Тип: FilterPattern
• По умолчанию: [/\.(css|postcss|sass|scss|less|stylus|styl)($|\?)/]

Шаблоны, фильтрующие файлы, которые НЕ подлежат извлечению. Поддерживает регулярные выражения и glob-шаблоны picomatch.

По умолчанию node_modules и dist также исключаются.

configResolved

• Тип: (config: ResolvedConfig) => void

Хук для модификации разрешенной (resolved) конфигурации.

Сначала запускаются пресеты, затем пользовательская конфигурация.

configFile

• Тип: string | false

Загрузка из файлов конфигурации.

Установите false для отключения.

configDeps

• Тип: string[]

Список файлов, которые также будут вызывать перезагрузку конфигурации.

cli

Опции UnoCSS CLI.

entry

• Тип: Arrayable<CliEntryItem>

Точки входа UnoCSS CLI.

patterns

• Тип: string[]

Glob-шаблоны для извлечения из файловой системы.

outFile

• Тип: string

Путь к выходному файлу.

shortcutsLayer

• Тип: string
• По умолчанию: 'shortcuts'

Имя слоя шорткатов.

envMode

• Тип: 'dev' | 'build'
• По умолчанию: 'build'

Режим окружения.

details

• Тип: boolean

Раскрыть внутренние детали для отладки / инспектирования.

warn

• Тип: boolean
• По умолчанию: true

Выдавать предупреждение, когда совпадающие селекторы присутствуют в blocklist.