LogoMkSaaS文档

主题

学习如何自定义MkSaaS 模板中的主题

本文档涵盖了MkSaaS 模板中的主题系统，如何在内置主题之间切换，以及如何创建和自定义您自己的主题。

核心功能

MkSaaS 模板配备了强大的主题系统，允许用户自定义网站的外观。主题系统包括：

  • 明暗模式支持
  • 多种颜色主题（默认、中性、蓝色、绿色、琥珀色）
  • 用户主题在线切换功能
  • 主题设置持久化

内置主题

模板包含几个预配置的主题，您可以开箱即用。

  • 默认：具有平衡色彩调色板的主要主题
  • 中性：具有中性色彩的灰度主题
  • 蓝色：以蓝色为主色调的主题
  • 绿色：以绿色为主色调的主题
  • 琥珀色：以琥珀色为主色调的主题

每个主题都会更改主色调和相关颜色，同时保持整体设计系统。

主题配置

主题系统在 website.tsx 配置文件中配置。

src/config/website.tsx
export const websiteConfig: WebsiteConfig = {
  metadata: {
    theme: {
      defaultTheme: 'default', // 选择：default、blue、green、amber、neutral
      enableSwitch: true,      // 启用/禁用主题切换
    },
    // ...其他配置
  },
  // ...其余配置
};

配置选项：

属性类型描述
defaultTheme'default' | 'blue' | 'green' | 'amber' | 'neutral'设置网站的默认颜色主题
enableSwitchboolean为真时，允许用户更改颜色主题

创建自定义主题

您可以通过向全局 CSS 文件添加新主题定义来创建自定义主题，这样主题切换的时候就可以选择新主题。

1. 添加新主题类

向 src/styles/globals.css 添加新主题类：

src/styles/globals.css
.theme-custom {
  --primary: var(--color-purple-600);
  --primary-foreground: var(--color-purple-50);

  @variant dark {
    --primary: var(--color-purple-500);
    --primary-foreground: var(--color-purple-50);
  }
}

2. 将主题添加到选择器

修改 src/components/layout/theme-selector.tsx 中的 ThemeSelector 组件以包含您的新主题：

src/components/layout/theme-selector.tsx
const DEFAULT_THEMES = [
  {
    name: t('default'),
    value: 'default',
  },
  // ...现有主题
  {
    name: t('custom'),
    value: 'custom',
  },
];

3. 添加翻译键

在您的翻译文件中为您的主题添加新的翻译键。

{
  "Common": {
    "theme": {
      "custom": "Custom Theme"
    }
  }
}
{
  "Common": {
    "theme": {
      "custom": "自定义主题"
    }
  }
}

高级自定义主题

对于更高级的主题自定义，您可以直接修改基础主题变量，或者使用主题生成器创建自定义主题。

自定义基础主题

基础主题变量在 src/styles/globals.css 的 :root 选择器中定义，您可以修改它来更改所有主题的默认外观：

src/styles/globals.css
:root {
  --radius: 0.5rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.141 0.005 285.823);
  /* 根据需要修改其他变量 */
}

.dark {
  --background: oklch(0.141 0.005 285.823);
  --foreground: oklch(0.985 0 0);
  /* 根据需要修改暗黑模式变量 */
}

创建自定义调色板

您可以通过在主题类中覆盖所有颜色变量来创建完全自定义的调色板：

src/styles/globals.css
.theme-custom {
  --background: oklch(0.98 0.01 280);
  --foreground: oklch(0.2 0.01 280);
  --card: oklch(0.97 0.01 280);
  --card-foreground: oklch(0.2 0.01 280);
  /* 覆盖所有其他颜色变量 */
}

主题生成器

您可以使用以下主题生成器创建自己的自定义主题，然后将 CSS 变量复制到您的 globals.css 文件中，或使用 shadcn cli 来添加并更改您的 globals.css 文件：

pnpm dlx shadcn@latest add https://tweakcn.com/r/themes/twitter.json

视频教程：

下图显示默认的主题现在变成自定义主题。

自定义主题

常见问题

主题没有正确应用

如果您的主题没有正确应用：

  1. 检查主题类是否在 globals.css 中正确定义
  2. 验证主题选择器是否在网站配置中启用
  3. 检查浏览器控制台是否有任何 JavaScript 错误
  4. 清除浏览器 cookie 并重新加载页面

页面加载时自定义主题闪烁

如果您在自定义主题加载前看到默认主题的闪烁：

  1. 在 website.tsx 中将您的自定义主题设置为默认主题
  2. 在主题加载时使用加载状态或骨架 UI

最佳实践

  • 颜色对比：确保文本颜色与背景颜色有足够的对比度以便于访问
  • 测试两种模式：如果开启明暗模式，确保在两种模式下测试新主题
  • 限制主题选项：提供少量精心设计的主题，而不是许多相似的选项
  • 主题一致性：在不同主题之间保持一致的样式，以避免 UI 异常

视频教程

下一步

现在您了解了如何在 MkSaaS 中使用主题，探索这些相关主题：

图片

配置网站各种图片

字体

配置自定义字体

环境配置

配置环境变量

网站配置

配置网站核心设置

字体

学习如何自定义MkSaaS 模板中的字体

图片

学习如何自定义MkSaaS 模板中的图片