配置 UnoCSS

🌐 Configuring UnoCSS

配置

🌐 Configuration

配置使 UnoCSS 变得强大。

🌐 Configurations are what make UnoCSS powerful.

• 规则 - 定义原子 CSS 工具
• 快捷方式 - 将多个规则合并为一个简写。
• 主题 - 定义主题变量。
• 变体 - 对规则应用自定义约定。
• 提取器 - 定义实用工具的使用位置和方式。
• 预检 - 定义全局原始 CSS。
• 图层 - 定义每个公用设施图层的顺序。
• 预设 - 常见用例的预定义配置。
• Transformers - 将用户源代码进行编码转换以支持约定。
• 自动补齐 - 定义自定义的自动补齐建议。

选项

🌐 Options

rules

• 类型: Rule<Theme>[]

生成 CSS 工具类的规则。后面的条目优先级更高。

🌐 Rules to generate CSS utilities. Later entries have higher priority.

shortcuts

• 类型: UserShortcuts<Theme>

类似于 Windi CSS 的快捷方式，允许你通过组合现有的工具类来创建新的工具类。后面的条目优先级更高。

🌐 Similar to Windi CSS's shortcuts, allows you to create new utilities by combining existing ones. Later entries have higher priority.

theme

• 类型: Theme

用于规则之间共享配置的主题对象。

🌐 Theme object for shared configuration between rules.

extendTheme

• 类型: Arrayable<ThemeExtender<Theme>> 自定义函数会修改主题对象。

还可以返回一个新的主题对象来完全替换原始主题对象。

🌐 It's also possible to return a new theme object to completely replace the original one.

variants

• 类型: Variant<Theme>[]

预处理选择器的变体，能够重写 CSS 对象。

🌐 Variants that preprocess the selectors, having the ability to rewrite the CSS object.

extractors

• 类型: Extractor[]

提取器用于处理源文件并输出可能的类/选择器。可以支持特定语言。

🌐 Extractors to handle the source file and output possible classes/selectors. Can be language-aware.

preflights

• 类型: Preflight<Theme>[]

原始 CSS 注入。

🌐 Raw CSS injections.

layers

• 类型: Record<string, number>

图层顺序。默认值为 0。

🌐 Layer orders. Default to 0.

outputToCssLayers

• 类型: boolean | UseCssLayersOptions
• 默认: false

将图层输出到 CSS Cascade Layers。

🌐 Outputs the layers to CSS Cascade Layers.

cssLayerName

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

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

🌐 Specifies the name of the CSS layer the internal layer should be output to (can be a sublayer e.g. "mylayer.mysublayer").

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

🌐 If undefined is return, the internal layer name wil be used as the CSS layer name. If null is return, the internal layer will not be output to a CSS layer.

allLayers

• 类型: boolean

强制输出所有 CSS 层，即使它们未被使用。

🌐 Force output all css layers, even if they are not used.

例如：

🌐 For example:

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

sortLayers

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

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

🌐 Custom function to sort layers.

presets

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

常见用例的预定义配置。

🌐 Predefined configurations for common use cases.

transformers

• 类型: SourceCodeTransformer[]

源代码的自定义转换器。

🌐 Custom transformers to the source code.

blocklist

• 类型: BlocklistRule[]

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

🌐 Rules to exclude the selectors for your design system (to narrow down the possibilities). Combining warnExcluded options can also help you identify wrong usages.

safelist

• 类型: string[]

始终包含的工具。

🌐 Utilities that are always included.

preprocess

• 类型: Arrayable<Preprocessor>

预处理传入的工具，返回要排除的虚假值。

🌐 Preprocess the incoming utilities, return falsy value to exclude.

postprocess

• 类型: Arrayable<Postprocessor>

对生成 utils 对象进行后处理。

🌐 Postprocess the generate utils object.

separators

• 类型: Arrayable<string>
• 默认: [':', '-']

变体分隔符。

🌐 Variant separator.

extractorDefault

• 类型: Extractor | null | false
• 默认: import('@unocss/core').defaultExtractor

默认提取器，会始终应用。默认情况下，它会根据空格和引号分割源代码。

🌐 Default extractor that are always applied. By default it split the source code by whitespace and quotes.

它可能被预设或用户配置替换，只能渲染一个默认提取器，后面的一个将覆盖前一个。

🌐 It maybe be replaced by preset or user config, only one default extractor can be presented, later one will override the previous one.

传入 null 或 false 以禁用默认提取器。

🌐 Pass null or false to disable the default extractor.

autocomplete

自动补齐的附加选项。

🌐 Additional options for auto complete.

templates

• 类型: Arrayable<AutoCompleteFunction | AutoCompleteTemplate>

自定义功能/模板以提供自动补齐建议。

🌐 Custom functions / templates to provide autocomplete suggestions.

extractors

• 类型: Arrayable<AutoCompleteExtractor>

自定义提取器来拾取可能的类并将类名样式建议转换为正确的格式。

🌐 Custom extractors to pickup possible classes and transform class-name style suggestions to the correct format.

shorthands

• 类型: Record<string, string | string[]>

自定义快捷方式以提供自动补齐建议。如果 values 是数组，它将使用 | 连接并用 () 封装。

🌐 Custom shorthands to provide autocomplete suggestions. if values is an array, it will be joined with | and wrapped with ().

content

作为工具用途提取的源的选项。

🌐 Options for sources to be extracted as utilities usages.

支持的来源：

🌐 Supported sources:

• filesystem - 从文件系统中提取
• inline - 从纯内联文本中提取
• pipeline - 从构建工具的转换管道中提取，例如 Vite 和 Webpack

从每个来源提取的用法将被合并在一起。

🌐 The usage extracted from each source will be merged together.

filesystem

• 类型: string[]
• 默认: []

从文件系统中提取的通配符模式，以及其他内容来源。node_modules 默认会被忽略，但当你指定路径包含 node_modules 时，unocss 会从中进行扫描。

🌐 Glob patterns to extract from the file system, in addition to other content sources. node_modules are ignored by default, but unocss will scan from it when you specify the path includes node_modules.

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

🌐 In dev mode, the files will be watched and trigger HMR.

inline

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

要提取的内嵌文本。

🌐 Inline text to be extracted.

pipeline

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

🌐 Filters to determine whether to extract certain modules from the build tools' transformation pipeline.

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

🌐 Currently only works for Vite and Webpack integration.

将 false 设置为禁用。

🌐 Set false to disable.

include

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

筛选正在提取的文件的模式。支持正则表达式和 picomatch 通配符模式。

🌐 Patterns that filter the files being extracted. Supports regular expressions and picomatch glob patterns.

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

🌐 By default, .ts and .js files are NOT extracted.

exclude

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

筛选未被提取文件的模式。支持正则表达式和 picomatch 通配符模式。

🌐 Patterns that filter the files NOT being extracted. Supports regular expressions and picomatch glob patterns.

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

🌐 By default, node_modules and dist are also extracted.

configResolved

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

钩子以修改已解析的配置。

🌐 Hook to modify the resolved config.

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

🌐 First presets runs first and the user config.

configFile

• 类型: string | false

从配置文件加载。

🌐 Load from configs files.

将 false 设置为禁用。

🌐 Set false to disable.

configDeps

• 类型: string[]

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

🌐 List of files that will also trigger config reloads.

cli

UnoCSS CLI 选项。

🌐 UnoCSS CLI options.

entry

• 类型: Arrayable<CliEntryItem>

UnoCSS cli 入口点。

🌐 UnoCSS cli entry points.

patterns

• 类型: string[]

从文件系统中提取的通配符模式。

🌐 Glob patterns to extract from the file system.

outFile

• 类型: string

输出文件路径。

🌐 Output file path.

shortcutsLayer

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

快捷方式的布局名称。

🌐 Layout name of shortcuts.

envMode

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

环境模式。

🌐 Environment mode.

details

• 类型: boolean

公开内部细节以进行调试/检查。

🌐 Expose internal details for debugging / inspecting.

warn

• 类型: boolean
• 默认: true

当匹配的选择器出现在阻止列表中时触发警告。

🌐 Emit warning when matched selectors are presented in blocklist.