--- title: "主题系统" description: "通过模块默认值、ThemePicker 组件和 useTheme composable 管理颜色、圆角、图标集与深色模式，字体则在构建期配置。" seo_title: "Theme System" seo_description: "Manage colors, radius, icon sets and dark mode in Movk Nuxt through module defaults, the ThemePicker component and the useTheme composable, with build-time font configuration and one-click CSS and config export." canonical_url: "https://nuxt.mhaibaraai.cn/docs/getting-started/theme" --- # 主题系统 > 通过模块默认值、ThemePicker 组件和 useTheme composable 管理颜色、圆角、图标集与深色模式，字体则在构建期配置。 ## 介绍 Movk Nuxt 在 [Nuxt UI](https://ui.nuxt.com){rel="[\"nofollow\"]"} 主题之上提供统一的运行时主题管理：颜色、圆角、字体、图标集与深色模式集中由一处控制，并可在运行时交互式调整、一键导出 CSS 变量或配置代码。 主题能力由三部分组成： - **[模块默认值](/docs/getting-started/configuration)** ： 在 `nuxt.config.ts` 的 `movk.theme` 中声明可选项。 - **`ThemePicker` 组件** ： 面向用户的可视化调参面板，支持导出。 - **`useTheme` composable** ： 在脚本中读写主题状态、导出 CSS/配置。 ## 启用与关闭 主题模块默认启用。关闭后不再注入 `appConfig` 默认值、theme 插件与 `ThemePicker` 组件： ```ts [nuxt.config.ts] export default defineNuxtConfig({ movk: { theme: { enabled: false } } }) ``` ## ThemePicker 组件 `ThemePicker` 提供颜色、圆角、图标集、深色模式的可视化切换，并能导出当前主题。 > \[\!TIP\] > See: /docs/components/theme-picker > > 查看 ThemePicker 的完整 props、事件与用法。 ## useTheme `useTheme` 暴露主题的响应式状态与导出方法，适合自定义主题面板或在业务逻辑中读取主题： ```ts const { color, neutral, radius, icon, mode, exportCSS, exportConfig, resetTheme } = useTheme() // 读取/切换主题 color.value = 'green' mode.value = 'dark' // 导出当前主题 const css = exportCSS() const config = exportConfig() ``` > \[\!TIP\] > See: /docs/composables/use-theme > > 查看 useTheme 返回的全部状态与方法。 ## 字体 字体是构建期配置，不随运行时切换。声明一行即可： ```ts [nuxt.config.ts] export default defineNuxtConfig({ movk: { theme: { font: 'Alibaba PuHuiTi' } } }) ``` 模块在构建期完成三件事，不依赖运行时 JS——Nuxt 模式随 SSR `` 直出，Vue/Vite 模式随构建产物 `index.html` 直出（`vite dev`/`vite build` 均生效）： - 向 `` 写入字体样式表的 `` - 为跨域字体补一条带 `crossorigin` 的 `preconnect` - 注入 `@theme { --font-sans }`，首选字体之后附上覆盖 macOS、Windows 与 Linux 的系统中文字体回退栈 内置字体托管在 [movk-fonts](https://github.com/mhaibaraai/movk-fonts){rel="[\"nofollow\"]"}，取值必须与其 `@font-face` 声明的 `font-family` 逐字一致： | 取值 | 样式表 | | ----------------- | ----------------------------------------------------- | | `Alibaba PuHuiTi` | `https://cdn.mhaibaraai.cn/fonts/alibaba-puhuiti.css` | | `OPPO Sans` | `https://cdn.mhaibaraai.cn/fonts/oppo-sans.css` | 自托管字体用 `{ name, href }` 形式补上入口 CSS 地址： ```ts [nuxt.config.ts] export default defineNuxtConfig({ movk: { theme: { font: { name: 'My Font', href: '/fonts/my-font.css' } } } }) ``` > \[\!WARNING\] > > name > > 写错不会报错，只会静默回退到系统字体——CSS 家族名匹配对大小写不敏感，但 > > alibaba-puhuiti > > 与 > > Alibaba PuHuiTi > > 是两个不同的名字。既非内置、又没提供 > > href > > 的字体不会产生任何请求，模块会在开发期发出警告。 模块注入的 `@theme` 随 `@import "@movk/nuxt"` 就位，写在其后的 `@theme` 覆盖 `--font-sans` 即可。完全由项目 CSS 控制字体时，不配置 `movk.theme.font` 即可： ```css [app/assets/css/main.css] @import "tailwindcss"; @import "@movk/nuxt"; @theme { --font-sans: "OPPO Sans", sans-serif; } ``` > \[\!NOTE\] > > 中文字体经 > > unicode-range > > 分包，浏览器只下载页面实际用到字符所在的分片。因此这些字体 > > 不能 > > 交给 > > @nuxt/fonts > > 处理——它会在构建期把全部分片下载进产物，既失去按需加载，也丢掉跨项目共享的 CDN 缓存。 > > @movk/nuxt > > 已默认设置 > > ui.fonts: false > > ，项目无需重复声明。 ## 图标集 `ThemePicker` 与 `useTheme` 可在 Lucide、Phosphor、Tabler 三套图标集间实时切换，切换只改写 `appConfig.ui.icons`，不需要重新构建。 模块默认把自己组件用到的图标与这三套图标集一并注入 `@nuxt/icon` 的构建期图标包，运行时无需再向 Iconify API 请求。每套图标集需要各自的 `@iconify-json` 包才能内联： ```bash npx nypm add -D @iconify-json/lucide @iconify-json/ph @iconify-json/tabler ``` > \[\!NOTE\] > > 未安装的图标集不会导致构建失败，只是相关图标退回运行时按需请求。默认图标集 > > lucide > > 缺失时模块会发出警告， > > ph > > 与 > > tabler > > 仅在切换图标集后才用到，缺失只记 debug 日志。 不需要这份注入时（例如项目自行管理图标包体积）可整体关闭，关闭后 movk 组件的图标改为运行时加载： ```ts [nuxt.config.ts] export default defineNuxtConfig({ movk: { icon: { clientBundle: false } } }) ``` ## 圆角 `--ui-radius` 保留三级优先级：`ThemePicker` 选择 > `movk.theme.radius` \> 项目 CSS。缺省时模块不注入该变量，沿用 `@nuxt/ui` 的默认值（`0.25rem`），项目可在自己的 CSS 中覆盖： ```css [app/assets/css/main.css] @theme { --ui-radius: 0.5rem; } ``` ## 可选项定制 颜色别名、圆角档位、neutral 颜色均可在 `movk.theme` 中覆盖，作为 `ThemePicker` 与 `useTheme` 的取值范围： ```ts [nuxt.config.ts] export default defineNuxtConfig({ movk: { theme: { colors: ['primary', 'secondary', 'success', 'info', 'warning', 'error'], radiuses: [0, 0.125, 0.25, 0.375, 0.5], neutralColors: ['slate', 'gray', 'zinc', 'neutral', 'stone'] } } }) ``` > \[\!TIP\] > See: /docs/getting-started/configuration > > 各字段含义见模块配置 · Theme ## 导出与复用 `ThemePicker` 与 `useTheme.exportCSS()` 导出的 CSS 变量可直接写入项目的 `main.css`，将运行时调试结果固化为默认主题： ```css [app/assets/css/main.css] @import "tailwindcss"; @import "@movk/nuxt"; :root { /* 粘贴 exportCSS() 导出的变量 */ } ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages.