UnoCSS Autocomplete 完全指南为原子化 CSS 打造智能补全【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocssUnoCSS 的 Autocomplete 是一套面向智能提示的可定制机制它内置于 Playground 与 VS Code 扩展让开发者输入诸如bg-、m-这类前缀时就能即时获得精准的补全建议。本文以 UnoCSS 仓库中 autocomplete 配置文档 与 autocomplete 工具文档 为主线结合 unocss/autocomplete 的源码实现与测试用例系统讲解其配置结构、DSL 语法、shorthands、extractors以及如何在自定义规则中声明补全模板帮助你为项目配置出贴合主题体系与业务习惯的智能提示。Autocomplete 是什么运行在哪里Autocomplete 是 UnoCSS 的智能建议能力当你在 Playground 或 VS Code 扩展 中输入候选类名时它负责解析你的输入并返回可用的补全列表。这套能力由独立包unocss/autocomplete提供源码见 packages-engine/autocomplete/src核心入口是createAutocomplete(uno, options)返回一个包含suggest、suggestInFile、templates、enumerate等能力的对象见 create.ts。从集成侧看语言服务器Language Server在收到补全请求时正是通过createAutocomplete(ctx.uno, { matchType, throwErrors: false })构建补全器然后调用suggest/suggestInFile返回结果见 completion.ts。这意味着你配置的 autocomplete 模板会直接作用于编辑器中的补全弹窗。配置总览三个核心字段在uno.config.ts的根配置中加入autocomplete字段即可开启定制autocomplete: { templates: [ // 主题推断theme inferring bg-$color/opacity, // 简写short hands text-font-size, // 逻辑 OR 组 (b|border)-(solid|dashed|dotted|double|hidden|none), // 常量 w-half, ], shorthands: { // 等价于 opacity: (0|10|20|30|40|50|60|70|90|100) opacity: Array.from({ length: 11 }, (_, i) i * 10), font-size: (xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl), // 覆盖内置简写 num: (0|1|2|3|4|5|6|7|8|9), }, extractors: [ // ...extractors ], }三个字段的分工如下templates使用一套简单 DSL 指定补全建议详见下一节。它可以接收字符串模板也可以接收返回建议列表的函数AutoCompleteFunction。shorthands简写名到模板的映射表。当值为数组时会被自动拼成一个逻辑 OR 组即用|连接并包上()。extractors负责从源码上下文中拾取可能正在输入的类并把类名风格的建议转换为当前场景下正确的格式例如将 attributify 属性值还原为可替换的形式。对应类型定义见 core 的 UserConfig其中明确了templates可为ArrayableAutoCompleteFunction | AutoCompleteTemplateshorthands的 value 可为string | string[]。在配置合并层面config.ts 会把所有 preset 与用户配置中的templates去重合并、按order排序extractors并通过mergeAutocompleteShorthands合并shorthands。因此各 preset 自带的内置补全与你的自定义模板是共存而非互斥的。templates DSL 详解模板 DSL 的核心语法由parseAutocomplete实现见 parse.ts。解析器会把模板拆解为三种节点类型见 types.tsstatic静态文本如m-、w-按字面匹配group逻辑 OR 组以|分隔、被()包裹的候选值theme主题推断以$开头指向 theme 对象的某个属性。(...|...)逻辑 OR 组用|分隔一组候选项当输入命中其中某些项时这些项会被作为建议返回。例如模板(border|b)-(solid|dashed|dotted|double|hidden|none)输入b-do→ 建议b-dotted、b-double这一行为与 autocomplete-parse.test.ts 的断言完全一致解析器会把(border|b)拆成values: [border, b]的 group 节点且支持可空组如(-suffix|)来生成带后缀与不带后缀的完整候选。...内置 shorthands尖括号内的名称是内置简写当前支持num(0|1|2|3|4|5|6|8|10|12|24|36)percent(0|10|20|30|40|50|60|70|80|90|100)percentage(10%|20%|30%|40%|50%|60%|70%|80%|90%|100%)directions(x|y|t|b|l|r|s|e)这些内置定义见 parse.ts。解析时/\w/g会先被替换为对应的正则片段若引用了未定义的简写名会抛出AutocompleteParseError提示Unknown template shorthand: key。例如模板m-num输入m-→ 建议m-1、m-2、m-3…而(m|p)directions-num则会组合出pt-0、pt-1、px-2、mb-4这类完整候选见 autocomplete-parse.test.ts。$...主题推断theme inferring以$开头引用主题对象例如$colors会枚举 theme 中colors对象的所有属性名。主题可以多级嵌套例如$animation.keyframes会深入 theme 的animation.keyframes结构。模板text-$colors输入text-r→ 建议text-red、text-rose…解析实现parse.ts会把$后的路径按.切分逐层深入 theme 对象并过滤掉DEFAULT键ignoredThemeKeys [DEFAULT]以及_开头的内部键。同时支持$路径用|并列如$colors|$spacing以合并多个主题分支的候选。多模板组合templates数组可同时传入多个模板补全时取并集。例如模板[(border|b)-num, (border|b)-directions-num]输入b-→ 建议b-x、b-y、b-1、b-2…输入b-x-→ 建议b-x-1、b-x-2…在内部所有模板会被预解析并缓存create.ts然后与静态规则、动态规则、shortcuts、variants 中声明的模板一起参与建议生成见下文在规则中声明 autocomplete。shorthands自定义与覆盖简写shorthands让你用语义化名字包装一组候选值并在模板中通过name引用shorthands: { // 数组会被自动转换为逻辑 OR 组 opacity: Array.from({ length: 11 }, (_, i) i * 10), font-size: (xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl), // 覆盖内置简写 num: (0|1|2|3|4|5|6|7|8|9), }要点value 为字符串时直接作为模板片段使用为数组时等价于(a|b|…)的 OR 组。例如上面的opacity数组等价于字符串(0|10|20|30|40|50|60|70|90|100)。自定义简写会覆盖同名内置简写例如把num重定义为(0|1|2|3|4|5|6|7|8|9)那么所有模板中出现的num都会使用新的候选集。源码层面parse.ts 在解析时通过{ ...shorthands, ...extraShorthands }合并后者的优先级更高。extractors从代码上下文拾取候选类extractors是补全能力的进阶开关它们读取光标所在位置的文件内容判断用户正在输入什么例如处于某个标签属性、某个 class 属性或某段自由文本内返回已提取的输入片段以及如何把补全建议转换/回填的规则。AutoCompleteExtractor的核心接口包含见 core 类型 附近extract({ content, cursor })返回{ extracted, transformSuggestions?, resolveReplacement? }或nullresolveReplacement(suggestion)将建议转换为{ start, end, replacement }用于精确替换光标附近文本transformSuggestions(suggestions)把类名风格的建议改写为当前输入场景下的正确格式。在suggestInFile中补全器会先尝试按 extractor 提取输入create.ts若没有 extractor 命中则退回到通用边界识别searchUsageBoundary它会扫描光标前后识别class、className、apply等上下文并排除引号、空白与;等分隔符utils.ts。实例attributify 自动补全提取器官方在 preset-attributify/src/autocomplete.ts 中实现了一个典型的 extractor它处理的是 attributify 风格如div bgblue-500的补全先用正则定位光标所在的 HTML 元素及属性区间跳过class/className/:class这类常规属性若光标在属性名上则把属性名当作待补全输入例如输入bg若光标在属性值上则将属性名-拼到值前作为补全输入并利用transformSuggestions把bg-blue-500这类类名风格建议还原为blue-500属性值风格同时resolveReplacement保证替换范围精确命中。这就是为什么在 Playground 的 attributify 模式下输入div b时可以补出bg、border等属性名输入div bgb时可以补出blue-500、black等值。这也是原文档建议参考 attributify extractor 实现自定义提取器的最佳范本。在规则与 shortcuts 中声明 autocompletemeta 方式除全局autocomplete.templates外静态规则天然可补全只要规则是静态字符串如[flex, { display: flex }]createAutocomplete会将其键名收集进staticUtils无需任何配置即可补出flexcreate.ts。动态规则则需要通过第三个元素meta声明autocompleterules: [ [ /^m-(\d)$/, ([, d]) ({ margin: ${d / 4}rem }), { autocomplete: m-num }, // -- 这里 ], ]在reset()中补全器会从以下来源收集全部模板create.tsuno.config.autocomplete.templates全局模板所有动态规则的meta.autocomplete所有 shortcuts 的meta.autocomplete所有 variants 的autocomplete。因此快捷方式也可以携带补全声明。core的类型定义types.ts确认了 rules、shortcuts、variants 均支持autocomplete?: ArrayableAutoCompleteTemplate。以 preset-wind3 的动画规则为例仓库源码中大量使用这一机制animation.ts{ autocomplete: [animate-keyframes-$animation.keyframes, keyframes-$animation.keyframes] } { autocomplete: animate-$animation.keyframes } { autocomplete: [animate-duration, animate-duration-$duration] } { autocomplete: [ animate-(fill|mode|fill-mode), animate-(fill|mode|fill-mode)-(none|forwards|backwards|both|inherit|initial|revert|revert-layer|unset), animate-(none|forwards|backwards|both|inherit|initial|revert|revert-layer|unset), ], }可以看到把meta.autocomplete与全局templates结合是给现有预设规则加餐补全的标准姿势。补全行为与内部机制建议来源与排序一次suggest(input)会并行收集四路建议create.tssuggestSelf直接尝试把输入作为合法 token 解析uno.parseToken命中则原样返回suggestStatic从静态规则 / 字符串 shortcuts 中按前缀过滤suggestUnoCache从生成器的已缓存 token 中匹配suggestFromTemplates所有已解析模板的suggest结果加上函数型模板。随后会做去重、过滤以-结尾的残缺建议、过滤blocklist中被屏蔽的类uno.isBlocked并按含数字的排后面 Intl.Collator数值感知排序输出create.ts。测试 autocomplete.test.ts 专门验证了被 blocklist 屏蔽的规则不会出现在建议中。matchTypeprefix 与 fuzzycreateAutocomplete支持两个选项types.tsmatchType: prefix | fuzzy默认prefix前缀匹配或基于 fzf 的模糊匹配throwErrors: boolean默认true模板解析出错时是否直接抛出。fuzzy 模式下会使用fzf库对结果做打分排序create.ts并有独立的 autocomplete-fuzzy.test.ts 覆盖。语言服务器在调用时传入了throwErrors: false因此某个模板写错不会让整个编辑器补全崩溃。suggestInFile 与 enumeratesuggestInFile(content, cursor)面向编辑器光标场景先尝试 extractor再退回到边界识别返回带resolveReplacement的结果create.tsenumerate()枚举从aa到zz等组合的完整建议集合通常用于生成完整的候选清单或文档统计create.ts。此外建议结果带有 LRU 缓存max: 5000与模板解析缓存保证编辑过程中的高频补全请求足够流畅。实践建议与注意事项优先复用内置简写num、percent、percentage、directions已覆盖大部分数值/方向类补全需求先组合再自定义。主题推断优先于硬编码$colors、$duration、$animation.keyframes这类引用会随 theme 扩展自动生效比写死候选列表更易维护。数组即 OR 组在shorthands中使用数组如Array.from({ length: 11 }, (_, i) i * 10)可避免手写一长串|。自定义 extractor 参考 attributify 实现如果你为某种模板语法如 Vue 指令、JSX 属性做补全直接参考 preset-attributify/src/autocomplete.ts 的extract/transformSuggestions/resolveReplacement三段式写法。模板写错会报错全局配置下默认throwErrors: true解析失败的模板会在启动时抛出带模板原文的AutocompleteParseError方便你定位编辑器侧则关闭了抛错以免影响体验。blocklist 优先级最高被 blocklist 的类即使命中模板也不会出现在建议里。延伸阅读配置总览docs/config/index.mdVS Code 扩展接入docs/integrations/vscode.md源码实现packages-engine/autocomplete/src、autocomplete 测试Attributify 提取器参考packages-presets/preset-attributify/src/autocomplete.ts内置规则 meta 示例packages-presets/preset-wind3/src/rules/animation.ts【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考