Una UI配置完全指南：nuxt.config与app.config的12个关键配置项

Una UI配置完全指南：nuxt.config与app.config的12个关键配置项

【免费下载链接】una-uiThe Atomic UI framework for Nuxt, powered by Unocss engine 💛项目地址: https://gitcode.com/gh_mirrors/un/una-ui

想要快速上手Una UI配置，让这套基于 Unocss 引擎的原子化 UI 框架真正"长"成你项目的模样？本文为你梳理 nuxt.config 与 app.config 中的 12 个关键配置项，从组件前缀、全局注册到主色、圆角、侧边栏宽度，全部一次讲透，照着抄就能用。

Una UI 是一款专为 Nuxt 打造的原子化 UI 框架，核心引擎是 Unocss。它默认帮你集成了 Unocss、Color Mode（深色模式）、VueUse、Reka UI 等必备能力，你几乎不用做额外安装，只需在配置文件里"点菜"即可。配置分两大入口：nuxt.config.ts管模块行为，app.config.ts管主题与组件细节，下面逐一拆解。

一、nuxt.config 配置：控制模块行为的 3 个关键项

在nuxt.config.ts中，通过una字段传入模块选项，共 3 个核心配置项。对应源码见 module.ts。

1. prefix：自定义组件前缀

所有 Una UI 组件默认以N开头，比如<NButton>、<NCard>。想避免与现有组件库冲突，改成自己的前缀即可，例如改成U后组件就变成<UButton>。

2. themeable：一键开关主题能力

设为true时会自动加载主题相关插件（theme.client.ts 与 theme.server.ts），支持运行时换色。不需要主题功能时可关掉，减少一点运行时开销。

3. global：全局注册还是按需导入

默认全局注册所有组件，开箱即用。若项目组件较多想精简，可设false，然后手动导入：import { NButton } from '@una-ui/nuxt'。

// nuxt.config.ts export default defineNuxtConfig({ modules: ['@una-ui/nuxt'], una: { prefix: 'N', // 组件前缀 themeable: true, // 启用主题化 global: true, // 全局注册组件 }, })

二、app.config 配置：掌控主题与细节的 9 个关键项

主题类的配置统一放在app.config.ts的una字段下，运行时可被useUnaSettings()读取并动态修改（见 useUnaSettings.ts）。

4. primary：设置主色调

所有组件的主色默认是yellow（黄），改一个词就能让全站换肤，支持 Tailwind 风格的全部色板。例如改成blue、violet，或自定义色值。

5. gray：设置中性色

默认stone，用于边框、背景、文字等中性元素。喜欢偏冷或偏暖的灰，可以换成slate、neutral、zinc等。

6. radius：统一圆角大小

默认0.5，控制所有组件的圆角风格。想要更圆润的卡片与按钮，调到0.75甚至1即可，整个 UI 气质立刻不同。

7. fontSize：根字号基准

默认16（px），作为全局字号基准，影响所有text-*工具类的计算。

8. fontSizes：字号切换预设列表

这是一个预设数组，供主题切换器（ThemeSwitcher）在下拉菜单中切换字号使用。替换它即可自定义可选字号档位：

// app.config.ts export default defineAppConfig({ una: { primary: 'yellow', gray: 'stone', radius: 0.5, fontSize: 16, fontSizes: [ { label: '小', value: 14 }, { label: '默认', value: 16 }, { label: '大', value: 18 }, ], }, })

9. sidebar.cookieName：侧边栏状态存储名

侧边栏的开合状态会持久化到 cookie，默认名为sidebar:state。多侧边栏场景建议各自命名，避免互相覆盖。

10. sidebar.cookieMaxAge：状态有效期

默认604800秒（7 天）。想"一次设置、长期记住"，把它调大即可。默认值与侧边栏逻辑对应源码见 useSidebar.ts。

11. sidebar 宽度三件套：width / widthMobile / widthIcon

• width：展开宽度，默认16rem
• widthMobile：移动端宽度，默认18rem
• widthIcon：折叠为图标栏时的宽度，默认3rem

12. sidebar.keyboardShortcut：折叠快捷键

默认b，即按下⌘/Ctrl + B快速折叠/展开侧边栏。觉得顺手也可以换成.等其他按键。

完整的 app.config 参考写法：

export default defineAppConfig({ una: { primary: 'violet', gray: 'slate', radius: 0.75, sidebar: { keyboardShortcut: '.', width: '20rem', }, }, })

三、延伸：uno.config.ts 里还能玩出什么花？

除了上述 12 项，Una UI 还提供了defaultConfig()帮助函数，让你在uno.config.ts中扩展 Unocss 配置并覆盖组件样式（官方文档见 una-config.md）。

import { defaultConfig } from '@una-ui/nuxt/una.config' export default defaultConfig({ shortcuts: [ // 静态组合：'btn-custom': 'py-2 px-4 bg-blue-500 text-white rounded', // 动态正则：[/^gradient-(\w+)$/, ([, c]) => `bg-gradient-to-r from-${c}-500 to-${c}-700`], ], })

静态 shortcuts 适合定义"常用组合类"，动态 shortcuts 则能用正则批量生成工具类，是二次定制组件外观的利器。底层预设还自带primary、gray、error、success等语义色板（见 colors.ts），扩展配色非常方便。

四、配置速查：一张表记住全部默认值

五、新手常见疑问

改了 primary 不生效？检查是否同时有useUnaSettings()在运行时写入 localStorage，它会覆盖默认值；调用其reset()即可恢复默认。

想精简打包体积？关闭global按需导入组件，并只在fontSizes中保留需要的字号档位。

主题与侧边栏配置不够用？别忘了uno.config.ts的 shortcuts 扩展入口，几乎所有组件样式都能在这里二次覆盖。

掌握了这 12 个关键配置项，Una UI 就能从"开箱默认"进化为"为你定制"。现在就打开你的nuxt.config.ts和app.config.ts，动手配置起来吧！

【免费下载链接】una-uiThe Atomic UI framework for Nuxt, powered by Unocss engine 💛项目地址: https://gitcode.com/gh_mirrors/un/una-ui