带你深入了解 UnoCSS 核心引擎

dirs #

src/├── extractors/    # UnoCSS 提取器（提取给`UnoCSS`引擎进行解析）│   └── ...├── generator/     # 引擎核心功能│    └── index.ts├── utils/         # UnoCSS 工具函数│   └── index.ts└── config.ts/     # ResolveConfig

generator #

如果你想使用UnoCSS的核心功能，你可以直接使用createGenerator函数。

const uno = createGenerator({ // 你的配置 })

export function createGenerator(config?: UserConfig, defaults?: UserConfigDefaults) {  return new UnoGenerator(config, defaults)}

我们可以看到，createGenerator 函数返回了一个UnoGenerator类的实例，这个类包含了所有的核心功能。

export class UnoGenerator {  constructor(    public userConfig: UserConfig = {},    public defaults: UserConfigDefaults = {},  ) {    this.config = resolveConfig(userConfig, defaults)    this.events.emit('config', this.config)  }  // ...

UnoCSS 在构造实例的时候会先去合并用户的配置和默认的配置项resolveConfig。

resolveconfig #

于是我们进入到 config.ts，我们来看看是如何合并用户配置的。

const config = Object.assign({}, defaults, userConfig) as UserConfigDefaultsconst rawPresets = (config.presets || []).flatMap(toArray).map(resolvePreset)const sortedPresets = [    ...rawPresets.filter(p => p.enforce === 'pre'),    ...rawPresets.filter(p => !p.enforce),    ...rawPresets.filter(p => p.enforce === 'post'),  ]const layers = Object.assign(DEFAULT_LAYERS, ...rawPresets.map(i => i.layers), userConfig.layers)

UnoCSS 采用assign合并配置，并对配置中的预设进行enforce 排序，也对layer进行合并。

type mergeKey = 'rules' | 'variants' | 'extractors' | 'shortcuts' | 'preflights' | 'preprocess' | 'postprocess' | 'extendTheme' | 'safelist'function mergePresets<T extends mergeKey>(key: T): Required<UserConfig>[T] {  return uniq([    ...sortedPresets.flatMap(p => toArray(p[key] || []) as any[]),    ...toArray(config[key] || []) as any[],  ])}

mergePresets 函数会对预设中的部分key进行合并，并返回一个数组。

此举主要是为了合并多个预设中的相同字段的值进行汇总。

extractors #

const extractors = mergePresets('extractors')if (!extractors.length)  extractors.push(extractorSplit)extractors.sort((a, b) => (a.order || 0) - (b.order || 0))

用户可以在预设中，自定义提取器，于是我们对其进行合并，并对它的执行顺序进行排序

rules #

我们都知道，UnoCSS有动静态规则，用户可以完全控制规则，使UnoCSS 按照其逻辑进行返回内容。

const rules = mergePresets('rules')const rulesStaticMap: ResolvedConfig['rulesStaticMap'] = {}const rulesSize = rules.lengthconst rulesDynamic = rules  .map((rule, i) => {    if (isStaticRule(rule)) {      const prefix = rule[2]?.prefix || ''      rulesStaticMap[prefix + rule[0]] = [i, rule[1], rule[2], rule]      // delete static rules so we can't skip them in matching      // but keep the order      return undefined    }    return [i, ...rule]  })  .filter(Boolean)  .reverse() as ResolvedConfig['rulesDynamic']

我们通过循环所有的规则将动静态规则分离：

// types{  rulesStaticMap: Record<string, [number, CSSObject | CSSEntries, RuleMeta | undefined, Rule] | undefined>  rulesDynamic: [number, ...DynamicRule][] // [规则的索引， 具体的规则逻辑][]}

UnoCSS 的动态解析逻辑为倒序解析，所以在最后会有 reverse 动作。因为静态规则是一个对象，如果遇到重复的 key，会后者覆盖前者。

用户自定义动态规则时，优先会解析后面的规则 如果你的静态规则与presetUno 或者其他预设规则冲突，不必担心，在mergePresets时，优先以用户规则为主。

Check The Playground

shortcuts #

我们知道我们的shortcuts也有动静态区分，StaticShortcutMap DynamicShortcut<Theme>，而且shortcuts的类型不一，既可以是Array Or Object，所以我们需要对其进行处理：

export function resolveShortcuts(shortcuts: UserShortcuts): Shortcut[] {  return toArray(shortcuts).flatMap((s) => {    if (Array.isArray(s))      return [s]    return Object.entries(s)  })}

还记得我们的rawPreset吗？在preset Resolve 时，我们会将shortcuts和rules进行一并处理 主要是因为当我们的preset中指定了prefix layer时，为了使其工作在正确的预设环境中，我们需要将其进行一次Resolve。

if (preset.prefix || preset.layer) {  const apply = (i: Rule | Shortcut) => {    if (!i[2])      i[2] = {}    const meta = i[2]    if (meta.prefix == null && preset.prefix)      meta.prefix = preset.prefix    if (meta.layer == null && preset.layer)      meta.prefix = preset.layer  }  shortcuts?.forEach(apply)  preset.rules?.forEach(apply)}

themes #

const theme = clone([  ...sortedPresets.map(p => p.theme || {}),  config.theme || {},].reduce((a, p) => mergeDeep(a, p), {}));(mergePresets('extendTheme') as ThemeExtender<any>[]).forEach(extendTheme => extendTheme(theme))

我们将所有预设中的 theme 和用户自定义的 theme 进行深度合并，最后将 extendTheme 中的函数执行，将 theme 作为参数传入，这样用户就可以对 theme 进行扩展。

将来我会在presetMini中解析 theme，并介绍其中的用法，敬请期待。

autocomplete #

提取每个预设中的 autocomplete，并将其合并为一个数组，最后将其作为 autocomplete 的值。

const autocomplete = {  templates: uniq(sortedPresets.map(p => toArray(p.autocomplete?.templates)).flat()),  extractors: sortedPresets.map(p => toArray(p.autocomplete?.extractors)).flat()    .sort((a, b) => (a.order || 0) - (b.order || 0)),}

ResolveConfig 流程结束，最后返回我们的 config。

return {  mergeSelectors: true,  warn: true,  blocklist: [],  sortLayers: layers => layers,  ...config,  presets: sortedPresets,  envMode: config.envMode || 'build',  shortcutsLayer: config.shortcutsLayer || 'shortcuts',  layers,  theme,  rulesSize,  rulesDynamic,  rulesStaticMap,  preprocess: mergePresets('preprocess') as Preprocessor[],  postprocess: mergePresets('postprocess') as Postprocessor[],  preflights: mergePresets('preflights'),  autocomplete,  variants: mergePresets('variants').map(normalizeVariant),  shortcuts: resolveShortcuts(mergePresets('shortcuts')),  extractors,  safelist: mergePresets('safelist'),}

generate #

UnoCSS 的 Generate 核心，主要是将我们的 input 解析生成 css。

async generate(  input: string | Set<string> | string[],  options: GenerateOptions = {},): Promise<GenerateResult> {  const {    id, // 在提取token阶段用到文件id    scope, // 生成的css的作用域    preflights = true, // 是否生成preflights    safelist = true, // 是否应用safelist    minify = false, // 是否压缩css  } = options    // ...}  

首先我们先观察函数的参数与返回值，我们可以看到，input 可以是 string Set Array，options 有 id scope preflights safelist minify，返回值是一个Promise GenerateResult。

applyextractors #

UnoCSS 会将 input 交给 extractors 进行解析提取token，最终提取出的 token 会是Set string的形式，确保每个 token 是唯一的。

const tokens: Readonly<Set<string>> = isString(input)      ? await this.applyExtractors(input, id)      : Array.isArray(input)        ? new Set(input)        : input

因为我们的 config.extractors 是一个数组，所以我们需要遍历它，将 input 交给每个 extractor 进行解析，最后将所有解析出来的 token 合并为一个 Set。

const context: ExtractorContext = {  get original() { return code },  code,  id,}for (const extractor of this.config.extractors) {  const result = await extractor.extract(context)  if (result) {    for (const token of result)      set.add(token)  }}

如果我们应用了safelist，那么我们还需要将safelist中的token合并到set中。

if (safelist)  this.config.safelist.forEach(s => tokens.add(s))

最后我们得到了我们需要去解析的所有token，接下来将这些token解析成css。