UnoCSS 中文网

Appearance

配置 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 级联层。

cssLayerName ​

  • 类型: (internalLayer: string) => string | undefined | null

指定内部层应输出到的 CSS 层的名称（可以是子层，例如 "mylayer.mysublayer"）。

如果返回 undefined，则内部层名称将用作 CSS 层名称。 如果返回 null，则内部层将不会输出到 CSS 层。

sortLayers ​

  • 类型: (layers: string[]) => string[]

用于对层进行排序的自定义函数。

presets ​

  • 类型: (PresetOrFactory<Theme> | PresetOrFactory<Theme>[])[]

针对常见用例的预定义配置。

transformers ​

  • 类型: SourceCodeTransformer[]

对源代码进行自定义转换的转换器。

blocklist ​

  • 类型: BlocklistRule[]

用于排除设计系统中选择器的规则（以缩小可能性范围）。结合 warnExcluded 选项还可以帮助您识别错误的用法。

safelist ​

  • 类型: string[]

始终包含的工具类。

preprocess ​

  • 类型: Arrayable<Preprocessor>

对传入的工具类进行预处理，返回假值以排除。

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，但当您指定的路径包含 node_modules 时，unocss 会对其进行扫描。

在开发模式下，文件将被监视并触发热更新。

inline ​

  • 类型: string | { code: string; id?: string } | (() => Awaitable<string | { code: string; id?: string }>)) []

要提取的内联文本。

pipeline ​

用于确定是否从构建工具的转换管道中提取某些模块的过滤器。

目前仅适用于 Vite 和 Webpack 集成。

设置为 false 以禁用。

include ​
  • 类型: FilterPattern
  • 默认值: [/\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/]

过滤要提取的文件的模式。支持正则表达式和 picomatch glob 模式。

默认情况下，不会提取 .ts 和 .js 文件。

exclude ​
  • 类型: FilterPattern
  • 默认值: [/\.(css|postcss|sass|scss|less|stylus|styl)($|\?)/]

过滤不提取的文件的模式。支持正则表达式和 picomatch glob 模式。

默认情况下，也会提取 node_modules 和 dist。

configResolved ​

  • 类型: (config: ResolvedConfig) => void

用于修改已解析配置的钩子。

预设首先运行，然后是用户配置。

configFile ​

  • 类型: string | false

从配置文件加载。

设置为 false 以禁用。

configDeps ​

  • 类型: string[]

也会触发配置重新加载的文件列表。

cli ​

UnoCSS 命令行界面选项。

entry ​

  • 类型: Arrayable<CliEntryItem>

UnoCSS 命令行界面入口点。

patterns ​
  • 类型: string[]

从文件系统提取的 glob 模式。

outFile ​
  • 类型: string

输出文件路径。

shortcutsLayer ​

  • 类型: string
  • 默认值: 'shortcuts'

快捷方式的层名称。

envMode ​

  • 类型: 'dev' | 'build'
  • 默认值: 'build'

环境模式。

details ​

  • 类型: boolean

暴露内部详细信息以进行调试/检查。

warn ​

  • 类型: boolean
  • 默认值: true

当匹配的选择器出现在黑名单中时发出警告。