主题定制

Ghuo Design 提供强大的主题定制功能，允许您自定义组件外观以匹配您的品牌和设计需求。

设计令牌

我们的主题系统基于设计令牌构建 - 一组存储视觉设计属性的命名实体。这些令牌确保所有组件的一致性。

颜色令牌

:root {
  /* 主色调 */
  --g-color-primary: #1890ff;
  --g-color-primary-hover: #40a9ff;
  --g-color-primary-active: #096dd9;
  --g-color-primary-light: #e6f7ff;
  
  /* 成功色 */
  --g-color-success: #52c41a;
  --g-color-success-hover: #73d13d;
  --g-color-success-active: #389e0d;
  --g-color-success-light: #f6ffed;
  
  /* 警告色 */
  --g-color-warning: #faad14;
  --g-color-warning-hover: #ffc53d;
  --g-color-warning-active: #d48806;
  --g-color-warning-light: #fffbe6;
  
  /* 错误色 */
  --g-color-error: #ff4d4f;
  --g-color-error-hover: #ff7875;
  --g-color-error-active: #d9363e;
  --g-color-error-light: #fff2f0;
  
  /* 中性色 */
  --g-color-text-primary: #262626;
  --g-color-text-secondary: #595959;
  --g-color-text-tertiary: #8c8c8c;
  --g-color-text-disabled: #bfbfbf;
  
  --g-color-border: #d9d9d9;
  --g-color-border-light: #f0f0f0;
  
  --g-color-background: #ffffff;
  --g-color-background-light: #fafafa;
  --g-color-background-dark: #f5f5f5;
}

字体令牌

:root {
  /* 字体族 */
  --g-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif;
  
  /* 字体大小 */
  --g-font-size-xs: 12px;
  --g-font-size-sm: 14px;
  --g-font-size-base: 16px;
  --g-font-size-lg: 18px;
  --g-font-size-xl: 20px;
  --g-font-size-2xl: 24px;
  --g-font-size-3xl: 32px;
  
  /* 字体粗细 */
  --g-font-weight-normal: 400;
  --g-font-weight-medium: 500;
  --g-font-weight-semibold: 600;
  --g-font-weight-bold: 700;
  
  /* 行高 */
  --g-line-height-tight: 1.2;
  --g-line-height-normal: 1.5;
  --g-line-height-relaxed: 1.75;
}

间距令牌

:root {
  /* 间距比例 */
  --g-space-xs: 4px;
  --g-space-sm: 8px;
  --g-space-base: 16px;
  --g-space-lg: 24px;
  --g-space-xl: 32px;
  --g-space-2xl: 48px;
  --g-space-3xl: 64px;
  
  /* 组件内边距 */
  --g-padding-xs: 4px 8px;
  --g-padding-sm: 8px 12px;
  --g-padding-base: 12px 16px;
  --g-padding-lg: 16px 24px;
}

定制方法

1. CSS 变量覆盖

最简单的主题定制方法是覆盖 CSS 变量：

:root {
  --g-color-primary: #722ed1;
  --g-color-primary-hover: #9254de;
  --g-color-primary-active: #531dab;
}

2. SCSS 变量

如果您使用 SCSS，可以在引入 Ghuo Design 之前覆盖变量：

// 覆盖变量
$primary-color: #722ed1;
$success-color: #52c41a;
$warning-color: #faad14;
$error-color: #ff4d4f;

// 引入 Ghuo Design
@import 'ghuo-design/dist/ghuo-design.scss';

3. JavaScript 配置

通过编程方式配置主题：

import { ConfigProvider } from 'ghuo-design'

const theme = {
  token: {
    colorPrimary: '#722ed1',
    colorSuccess: '#52c41a',
    colorWarning: '#faad14',
    colorError: '#ff4d4f',
    fontFamily: 'Inter, sans-serif',
  },
}

// 在您的 Vue 应用中
app.use(ConfigProvider, { theme })

4. 组件级主题

为特定组件实例应用主题：

<template>
  <g-config-provider :theme="customTheme">
    <g-button type="primary">自定义主题按钮</g-button>
  </g-config-provider>
</template>

<script setup>
const customTheme = {
  token: {
    colorPrimary: '#722ed1',
  },
}
</script>

暗色模式

Ghuo Design 开箱即用地支持暗色模式：

自动暗色模式

import { ConfigProvider } from 'ghuo-design'

const app = createApp(App)
app.use(ConfigProvider, {
  theme: {
    algorithm: 'dark', // 或 'light'
  },
})

系统偏好检测

const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
const theme = {
  algorithm: prefersDark ? 'dark' : 'light',
}

手动切换

<template>
  <div>
    <g-switch v-model:checked="isDark" @change="toggleTheme" />
    <g-config-provider :theme="currentTheme">
      <!-- 您的应用内容 -->
    </g-config-provider>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'

const isDark = ref(false)

const currentTheme = computed(() => ({
  algorithm: isDark.value ? 'dark' : 'light',
}))

const toggleTheme = () => {
  document.documentElement.setAttribute('data-theme', isDark.value ? 'dark' : 'light')
}
</script>

品牌定制

创建品牌主题

const brandTheme = {
  token: {
    // 品牌色彩
    colorPrimary: '#1890ff',
    colorSuccess: '#52c41a',
    colorWarning: '#faad14',
    colorError: '#ff4d4f',
    
    // 字体排版
    fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
    fontSize: 14,
    
    // 间距
    sizeUnit: 4,
    sizeStep: 4,
    
    // 圆角
    borderRadius: 6,
    
    // 阴影
    boxShadow: '0 2px 8px rgba(0, 0, 0, 0.15)',
  },
  components: {
    Button: {
      borderRadius: 8,
      fontWeight: 500,
    },
    Input: {
      borderRadius: 4,
    },
  },
}

组件特定定制

const componentTheme = {
  components: {
    Button: {
      colorPrimary: '#722ed1',
      borderRadius: 8,
      fontWeight: 600,
    },
    Input: {
      colorBorder: '#d9d9d9',
      borderRadius: 4,
    },
    Card: {
      borderRadius: 12,
      boxShadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
    },
  },
}

高级主题定制

自定义算法

创建自定义主题算法：

const customAlgorithm = (seedToken, mapToken) => {
  return {
    ...mapToken,
    colorPrimary: seedToken.colorPrimary,
    colorPrimaryHover: lighten(seedToken.colorPrimary, 0.1),
    colorPrimaryActive: darken(seedToken.colorPrimary, 0.1),
  }
}

const theme = {
  algorithm: customAlgorithm,
}

动态主题

<template>
  <div>
    <g-color-picker v-model:value="primaryColor" @change="updateTheme" />
    <g-config-provider :theme="dynamicTheme">
      <!-- 您的组件 -->
    </g-config-provider>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'

const primaryColor = ref('#1890ff')

const dynamicTheme = computed(() => ({
  token: {
    colorPrimary: primaryColor.value,
  },
}))

const updateTheme = (color) => {
  primaryColor.value = color
}
</script>

最佳实践

1. 使用设计令牌

始终使用设计令牌而不是硬编码值：

/* 推荐 */
.custom-component {
  color: var(--g-color-text-primary);
  padding: var(--g-space-base);
}

/* 避免 */
.custom-component {
  color: #262626;
  padding: 16px;
}

2. 测试无障碍性

确保您的自定义主题符合无障碍标准：

// 检查颜色对比度
const contrastRatio = getContrastRatio(backgroundColor, textColor)
if (contrastRatio < 4.5) {
  console.warn('颜色对比度过低')
}

3. 提供主题预设

为常见用例创建预定义主题：

export const themes = {
  default: { /* 默认主题 */ },
  dark: { /* 暗色主题 */ },
  corporate: { /* 企业主题 */ },
  creative: { /* 创意主题 */ },
}

4. 记录自定义令牌

记录您创建的任何自定义令牌：

:root {
  /* 自定义品牌色 */
  --g-color-brand-primary: #1890ff;
  --g-color-brand-secondary: #722ed1;
  
  /* 特定布局的自定义间距 */
  --g-space-section: 80px;
  --g-space-container: 120px;
}

迁移指南

从 v1.x 到 v2.x

// v1.x
const theme = {
  primaryColor: '#1890ff',
  successColor: '#52c41a',
}

// v2.x
const theme = {
  token: {
    colorPrimary: '#1890ff',
    colorSuccess: '#52c41a',
  },
}

资源

• 设计令牌参考
• 色彩系统指南
• 字体排版指南
• 主题示例

需要主题定制帮助？查看我们的社区讨论或联系我们的团队！