安全列表

🌐 Safelist

Safelist 是 UnoCSS 配置中的一个重要选项，它允许你指定一组实用类，这些类无论是否在你的源代码中被检测到，都应始终包含在生成的 CSS 中。

🌐 Safelist is an important option in UnoCSS configuration that allows you to specify a set of utility classes that should always be included in the generated CSS, regardless of whether these classes are detected in your source code.

基本用法

🌐 Basic Usage

字符串数组

🌐 String Array

最简单的用法是提供一个包含你想要保留的类名的字符串数组：

🌐 The simplest usage is to provide a string array containing the class names you want to preserve:

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

函数形式

🌐 Function Form

允许列表还可以包含在构建时调用并动态返回类名的函数：

🌐 Safelist can also contain functions that are called during build time and can dynamically return class names:

// uno.config.ts
export default defineConfig({
  safelist: [
    // Static class names
    'p-1',
    'p-2',
    // Dynamic function
    context => ['m-1', 'm-2', 'm-3'],
    (context) => {
      // Generate class names based on theme
      const colors = Object.keys(context.theme.colors || {})
      return colors.map(color => `bg-${color}-500`)
    }
  ]
})

混合使用

🌐 Mixed Usage

你可以在同一安全列表配置中混合使用字符串和函数：

🌐 You can mix strings and functions in the same safelist configuration:

// uno.config.ts
export default defineConfig({
  safelist: [
    // Static class names
    'prose',
    'bg-orange-300',
    // Dynamic generation
    () => ['flex', 'grid', 'block'],
    // Conditional dynamic generation
    (context) => {
      if (process.env.NODE_ENV === 'development') {
        return ['debug-border', 'debug-grid']
      }
      return []
    }
  ]
})

返回值类型

🌐 Return Value Types

安全列表函数可以返回以下类型的值：

🌐 Safelist functions can return the following types of values:

• Arrayable<string> - 字符串或字符串数组

safelist: [
  // Return string array
  () => ['class1', 'class2', 'class3'],

  // Return single string
  () => 'single-class',

  // Return nested array (will be flattened)
  () => [['nested1', 'nested2'], 'normal3']
]

实际使用案例

🌐 Practical Use Cases

动态生成的类名

🌐 Dynamically Generated Class Names

当你有可能未被静态分析检测到的动态生成的类名时：

🌐 When you have dynamically generated class names that might not be detected by static analysis:

safelist: [
  // Dynamic color classes
  () => {
    const dynamicColors = ['primary', 'secondary', 'accent']
    return dynamicColors.flatMap(color => [
      `bg-${color}`,
      `text-${color}`,
      `border-${color}`
    ])
  },

  // Dynamic size classes
  () => {
    return Array.from({ length: 12 }, (_, i) => `gap-${i + 1}`)
  }
]

第三方组件库支持

🌐 Third-party Component Library Support

为第三方组件库提供必要的类名：

🌐 Provide necessary class names for third-party component libraries:

safelist: [
  // Reserved class names for component library
  'prose',
  'prose-sm',
  'prose-lg',

  // Dynamically generate component variants
  () => {
    const variants = ['primary', 'secondary', 'danger', 'success']
    const sizes = ['sm', 'md', 'lg']

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

与其他配置的关系

🌐 Relationship with Other Configurations

与黑名单的区别

🌐 Difference from blocklist

• 安全列表：确保指定的类名始终被包含
• 阻止列表：确保指定的类名始终被排除

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

与世代选项的关系

🌐 Relationship with Generation Options

在生成 CSS 时，你可以通过 GenerateOptions 控制是否包含安全列表：

🌐 When generating CSS, you can control whether to include safelist through GenerateOptions:

const { css } = await uno.generate('', {
  safelist: true // Include class names from safelist
})