Белый список

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

Базовое использование

Массив строк

Самый простой способ использования — предоставить массив строк, содержащий имена классов, которые вы хотите сохранить:

// uno.config.ts
export default defineConfig({
  safelist: [
    'p-1',
    'p-2',
    'p-3',
    'text-center',
    'bg-red-500'
  ]
})

Функциональная форма

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

// uno.config.ts
export default defineConfig({
  safelist: [
    // Статические имена классов
    'p-1',
    'p-2',
    // Динамическая функция
    context => ['m-1', 'm-2', 'm-3'],
    (context) => {
      // Генерация имён классов на основе темы
      const colors = Object.keys(context.theme.colors || {})
      return colors.map(color => `bg-${color}-500`)
    }
  ]
})

Смешанное использование

Вы можете смешивать строки и функции в одной конфигурации белого списка:

// uno.config.ts
export default defineConfig({
  safelist: [
    // Статические имена классов
    'prose',
    'bg-orange-300',
    // Динамическая генерация
    () => ['flex', 'grid', 'block'],
    // Динамическая генерация по условию
    (context) => {
      if (process.env.NODE_ENV === 'development') {
        return ['debug-border', 'debug-grid']
      }
      return []
    }
  ]
})

Типы возвращаемых значений

Функции белого списка могут возвращать следующие типы значений:

• Arrayable<string> — Строка или массив строк

safelist: [
  // Возврат массива строк
  () => ['class1', 'class2', 'class3'],

  // Возврат одной строки
  () => 'single-class',

  // Возврат вложенного массива (будет выровнен)
  () => [['nested1', 'nested2'], 'normal3']
]

Практические сценарии использования

Динамически генерируемые имена классов

Когда у вас есть динамически генерируемые имена классов, которые могут быть не обнаружены статическим анализом:

safelist: [
  // Динамические классы цветов
  () => {
    const dynamicColors = ['primary', 'secondary', 'accent']
    return dynamicColors.flatMap(color => [
      `bg-${color}`,
      `text-${color}`,
      `border-${color}`
    ])
  },

  // Динамические классы размеров
  () => {
    return Array.from({ length: 12 }, (_, i) => `gap-${i + 1}`)
  }
]

Поддержка сторонних библиотек компонентов

Укажите необходимые имена классов для сторонних библиотек компонентов:

safelist: [
  // Зарезервированные имена классов для библиотеки компонентов
  'prose',
  'prose-sm',
  'prose-lg',

  // Динамическая генерация вариантов компонентов
  () => {
    const variants = ['primary', 'secondary', 'danger', 'success']
    const sizes = ['sm', 'md', 'lg']

    return variants.flatMap(variant =>
      sizes.map(size => `btn-${variant}-${size}`)
    )
  }
]

Связь с другими настройками

Отличие от чёрного списка

• safelist: гарантирует, что указанные имена классов всегда будут включены
• blocklist: гарантирует, что указанные имена классов всегда будут исключены

export default defineConfig({
  safelist: ['always-include'],
  blocklist: ['never-include']
})

Связь с параметрами генерации

При генерации CSS вы можете управлять включением белого списка с помощью GenerateOptions:

const { css } = await uno.generate('', {
  safelist: true // Включить имена классов из белого списка
})