UnoCSS 中文网

Appearance

配置 UnoCSS ​

¥Configuring UnoCSS

配置 ​

¥Configuration

配置使 UnoCSS 变得强大。

¥Configurations are what make UnoCSS powerful.

  • 规则 - 定义原子 CSS 工具

    ¥Rules - Define atomic CSS utilities

  • 快捷方式 - 将多个规则组合成一个简写。

    ¥Shortcuts - Combine multiple rules into a single shorthand.

  • 主题 - 定义主题变量。

    ¥Theme - Define theme variables.

  • 变体 - 将自定义约定应用于规则。

    ¥Variants - Apply custom conventions to rules.

  • 提取器 - 定义提取工具的位置和方式。

    ¥Extractors - Define where and how the usage of utilities are extracted.

  • 预检 - 定义全局原始 CSS。

    ¥Preflights - Define global raw CSS.

  • 层 - 定义每个工具层的顺序。

    ¥Layers - Define the order of each utilities layer.

  • 预设 - 常见用例的预定义配置。

    ¥Presets - Predefined configurations for common use cases.

  • 转换器 - 将代码转换器转换为用户源代码以支持约定。

    ¥Transformers - Code transformers to user sources code to support conventions.

  • 自动补齐 - 定义自定义自动补齐建议。

    ¥Autocomplete - Define customized autocomplete suggestions.

选项 ​

¥Options

rules ​

  • 类型：Rule<Theme>[]

    ¥Type: Rule<Theme>[]

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

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

快捷方式 ​

¥shortcuts

  • 类型：UserShortcuts<Theme>

    ¥Type: 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

    ¥Type: Theme

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

¥Theme object for shared configuration between rules.

extendTheme ​

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

    ¥Type: Arrayable<ThemeExtender<Theme>> Custom functions mutate the theme object.

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

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

variants ​

  • 类型：Variant<Theme>[]

    ¥Type: Variant<Theme>[]

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

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

extractors ​

  • 类型：Extractor[]

    ¥Type: Extractor[]

用于处理源文件并输出可能的类/选择器的提取器。可以具有语言意识。

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

preflights ​

  • 类型：Preflight<Theme>[]

    ¥Type: Preflight<Theme>[]

原始 CSS 注入。

¥Raw CSS injections.

layers ​

  • 类型：Record<string, number>

    ¥Type: Record<string, number>

层层下单。默认为 0。

¥Layer orders. Default to 0.

outputToCssLayers ​

  • 类型：boolean | UseCssLayersOptions

    ¥Type: boolean | UseCssLayersOptions

  • 默认：false

    ¥Default: false

将图层输出到 CSS Cascade Layers。

¥Outputs the layers to CSS Cascade Layers.

cssLayerName ​

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

    ¥Type: (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.

sortLayers ​

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

    ¥Type: (layers: string[]) => string[]

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

¥Custom function to sort layers.

presets ​

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

    ¥Type: (PresetOrFactory<Theme> | PresetOrFactory<Theme>[])[]

常见用例的预定义配置。

¥Predefined configurations for common use cases.

transformers ​

  • 类型：SourceCodeTransformer[]

    ¥Type: SourceCodeTransformer[]

源代码的自定义转换器。

¥Custom transformers to the source code.

blocklist ​

  • 类型：BlocklistRule[]

    ¥Type: 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[]

    ¥Type: string[]

始终包含的工具。

¥Utilities that are always included.

preprocess ​

  • 类型：Arrayable<Preprocessor>

    ¥Type: Arrayable<Preprocessor>

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

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

postprocess ​

  • 类型：Arrayable<Postprocessor>

    ¥Type: Arrayable<Postprocessor>

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

¥Postprocess the generate utils object.

separators ​

  • 类型：Arrayable<string>

    ¥Type: Arrayable<string>

  • 默认：[':', '-']

    ¥Default: [':', '-']

变体分隔符。

¥Variant separator.

extractorDefault ​

  • 类型：Extractor | null | false

    ¥Type: Extractor | null | false

  • 默认：import('@unocss/core').defaultExtractor

    ¥Default: 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>

    ¥Type: Arrayable<AutoCompleteFunction | AutoCompleteTemplate>

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

¥Custom functions / templates to provide autocomplete suggestions.

extractors ​

  • 类型：Arrayable<AutoCompleteExtractor>

    ¥Type: Arrayable<AutoCompleteExtractor>

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

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

shorthands ​

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

    ¥Type: 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 - 从文件系统中提取

    ¥filesystem - extract from file system

  • plain - 从纯内联文本中提取

    ¥plain - extract from plain inline text

  • pipeline - 从构建工具的转换管道中提取，例如 Vite 和 Webpack

    ¥pipeline - extract from build tools' transformation pipeline, such as Vite and Webpack

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

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

filesystem ​

  • 类型：string[]

    ¥Type: string[]

  • 默认：[]

    ¥Default: []

除了其他内容源之外，还从文件系统中提取 Glob 模式。

¥Glob patterns to extract from the file system, in addition to other content sources.

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

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

inline ​

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

    ¥Type: 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

    ¥Type: FilterPattern

  • 默认：[/\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/]

    ¥Default: [/\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/]

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

¥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

    ¥Type: FilterPattern

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

    ¥Default: [/\.(css|postcss|sass|scss|less|stylus|styl)($|\?)/]

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

¥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

    ¥Type: (config: ResolvedConfig) => void

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

¥Hook to modify the resolved config.

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

¥First presets runs first and the user config.

configFile ​

  • 类型：string | false

    ¥Type: string | false

从配置文件加载。

¥Load from configs files.

将 false 设置为禁用。

¥Set false to disable.

configDeps ​

  • 类型：string[]

    ¥Type: string[]

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

¥List of files that will also trigger config reloads.

cli ​

UnoCSS CLI 选项。

¥UnoCSS CLI options.

entry ​

  • 类型：Arrayable<CliEntryItem>

    ¥Type: Arrayable<CliEntryItem>

UnoCSS cli 入口点。

¥UnoCSS cli entry points.

patterns ​

  • 类型：string[]

    ¥Type: string[]

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

¥Glob patterns to extract from the file system.

outFile ​

  • 类型：string

    ¥Type: string

输出文件路径。

¥Output file path.

shortcutsLayer ​

  • 类型：string

    ¥Type: string

  • 默认：'shortcuts'

    ¥Default: 'shortcuts'

快捷方式的布局名称。

¥Layout name of shortcuts.

envMode ​

  • 类型：'dev' | 'build'

    ¥Type: 'dev' | 'build'

  • 默认：'build'

    ¥Default: 'build'

环境模式。

¥Environment mode.

details ​

  • 类型：boolean

    ¥Type: boolean

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

¥Expose internal details for debugging / inspecting.

warn ​

  • 类型：boolean

    ¥Type: boolean

  • 默认：true

    ¥Default: true

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

¥Emit warning when matched selectors are presented in blocklist.