主题定制

BreezeUI 提供灵活的主题能力。你可以通过 BrConfigProvider 快速配置主题，也可以直接覆盖 CSS 变量进行更细粒度的控制。

使用 BrConfigProvider（推荐）

BrConfigProvider 可以在应用根节点（或任意节点）动态配置主题。它会把 Hex 颜色自动转换为 HSL，并注入到对应的 CSS 变量中。

<script setup lang="ts">
import { ref } from 'vue';
import { BrConfigProvider } from '@breezeui/vue';

const theme = ref({
  primary: '#3b82f6',
  radius: 0.5,
});
</script>

<template>
  <BrConfigProvider :theme="theme">
    <App />
  </BrConfigProvider>
</template>

详细的 theme 配置字段请参考下方的 API 参考。

API 参考

BrConfigProvider Props

属性名	类型	默认值	说明
theme	ThemeConfig	-	全局主题配置对象
size	ComponentSize	'default'	全局组件默认尺寸，可选：xs, sm, md, lg, xl, 2xl
toast	BrToastConfig	-	全局 Toast 行为配置
locale	'en-US' | 'zh-CN'	'en-US'	全局语言配置，组件会读取此配置显示默认文案。
tag	string	'div'	渲染的根标签或组件

国际化 (i18n)

你可以通过 BrConfigProvider 的 locale 属性来设置全局组件的语言。默认语言为 en-US。目前支持 en-US（英文）和 zh-CN（简体中文）。

<script setup lang="ts">
import { ref } from 'vue';
import { BrConfigProvider, BrSelectDialog } from '@breezeui/vue';

const currentLocale = ref('zh-CN');
</script>

<template>
  <BrConfigProvider :locale="currentLocale">
    <!-- 组件将默认使用中文文案 -->
    <BrSelectDialog />
  </BrConfigProvider>
</template>

注意：如果你为某个具体的组件传入了如 emptyText 或 placeholder 属性，它们将覆盖全局的语言配置。

<template>
  <BrConfigProvider locale="zh-CN">
    <!-- 将显示 "暂无数据" (来自全局配置) -->
    <BrTable :data="[]" />

    <!-- 将显示 "没有找到匹配的记录" (组件 Props 优先级更高) -->
    <BrTable :data="[]" emptyText="没有找到匹配的记录" />
  </BrConfigProvider>
</template>

ThemeConfig 类型定义

interface ThemeConfig {
  // 基础色
  background?: string;
  foreground?: string;

  // 功能色
  primary?: string;
  primaryForeground?: string;
  secondary?: string;
  secondaryForeground?: string;
  muted?: string;
  mutedForeground?: string;
  accent?: string;
  accentForeground?: string;
  destructive?: string;
  destructiveForeground?: string;
  error?: string;
  errorForeground?: string;
  success?: string;
  successForeground?: string;
  warning?: string;
  warningForeground?: string;
  info?: string;
  infoForeground?: string;
  carbon?: string;
  carbonForeground?: string;

  // 组件背景
  card?: string;
  cardForeground?: string;
  popover?: string;
  popoverForeground?: string;

  // 其它
  border?: string;
  input?: string;
  ring?: string;
  radius?: string | number;
  shadow?: string;
  transitionDuration?: string;

  // 层级 (z-index)
  zTooltip?: string | number;
  zToast?: string | number;
  zLoading?: string | number;
}

CSS 变量（进阶）

BreezeUI 的主题本质上由 CSS 变量驱动，因此你也可以直接在全局样式中覆盖这些变量。

变量示例

把以下变量放到你的全局 CSS（例如 src/style.css 或 App.vue 的全局样式）：

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;
  --popover: 0 0% 100%;
  --popover-foreground: 222.2 84% 4.9%;
  --primary: 239 84% 67%;
  --primary-foreground: 0 0% 100%;
  --secondary: 240 5% 96%;
  --secondary-foreground: 240 6% 10%;
  --muted: 240 5% 96%;
  --muted-foreground: 240 4% 46%;
  --accent: 240 5% 96%;
  --accent-foreground: 240 6% 10%;
  --destructive: 0 84% 60%;
  --destructive-foreground: 0 0% 100%;
  --error: 0 84% 60%;
  --error-foreground: 0 0% 100%;
  --success: 142 71% 45%;
  --success-foreground: 0 0% 100%;
  --warning: 38 92% 50%;
  --warning-foreground: 0 0% 100%;
  --info: 217 91% 60%;
  --info-foreground: 0 0% 100%;
  --carbon: 215 28% 17%;
  --carbon-foreground: 0 0% 100%;
  --border: 214.3 31.8% 85%;
  --input: 214.3 31.8% 85%;
  --ring: 222.2 84% 4.9%;
  --radius: 0.5rem;
  --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
  --z-tooltip: 60;
  --z-toast: 100;
  --z-loading: 50;
  --transition-duration: 300ms;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --card: 222.2 84% 4.9%;
  --card-foreground: 210 40% 98%;
  --popover: 222.2 84% 4.9%;
  --popover-foreground: 210 40% 98%;
  --primary: 239 84% 67%;
  --primary-foreground: 0 0% 100%;
  --secondary: 240 3.7% 15.9%;
  --secondary-foreground: 210 40% 98%;
  --muted: 240 3.7% 15.9%;
  --muted-foreground: 215 20.2% 65.1%;
  --accent: 240 3.7% 15.9%;
  --accent-foreground: 210 40% 98%;
  --destructive: 0 62.8% 30.6%;
  --destructive-foreground: 0 0% 98%;
  --error: 0 62.8% 30.6%;
  --error-foreground: 0 0% 98%;
  --success: 142 70% 50%;
  --success-foreground: 0 0% 100%;
  --warning: 38 92% 50%;
  --warning-foreground: 0 0% 100%;
  --info: 217 91% 60%;
  --info-foreground: 0 0% 100%;
  --carbon: 215 28% 17%;
  --carbon-foreground: 0 0% 100%;
  --border: 240 3.7% 15.9%;
  --input: 240 3.7% 15.9%;
}

尺寸系统定制

你可以通过 BrConfigProvider 设置全局默认组件尺寸，也可以通过 CSS 变量自定义具体尺寸的数值（高度、横向内边距、字号与宽度）。

全局组件尺寸

你可以通过 BrConfigProvider 的 size 属性来设置内部所有 BreezeUI 组件的默认尺寸。当你希望整个应用（或某个特定区域）统一使用偏小或偏大的尺寸时，这非常有用，无需在每个组件上单独设置 size 属性。

<script setup lang="ts">
import { ref } from 'vue';
import { BrConfigProvider, BrButton, BrInput } from '@breezeui/vue';

const globalSize = ref('sm');
</script>

<template>
  <BrConfigProvider :size="globalSize">
    <!-- 下面的组件如果没有显式声明 size，都将自动应用 sm 尺寸 -->
    <BrButton>提交</BrButton>
    <BrInput placeholder="请输入..." />
  </BrConfigProvider>
</template>

通过 CSS 变量

:root {
  --br-h-md: 2.5rem;
  --br-px-md: 1rem;
  --br-text-md: 0.875rem;
  --br-h-icon: 2.5rem;
  --br-w-icon: 2.5rem;
}

深色模式

BreezeUI 的深色模式基于 .dark 类。把 dark 类加到 html 或 body 上即可切换。

<html class="dark">
  <body></body>
</html>

切换示例

<script setup lang="ts">
import { useDark, useToggle } from '@vueuse/core';
import { BrButton } from '@breezeui/vue';
import { Moon, Sun } from 'lucide-vue-next';

const isDark = useDark();
const toggleDark = useToggle(isDark);
</script>

<template>
  <BrButton variant="outline" size="icon" @click="toggleDark()">
    <Sun v-if="isDark" class="h-[1.2rem] w-[1.2rem]" />
    <Moon v-else class="h-[1.2rem] w-[1.2rem]" />
  </BrButton>
</template>

基于 ConfigProvider 的动态主题

<script setup lang="ts">
import { computed } from 'vue';
import { useDark } from '@vueuse/core';
import { BrConfigProvider } from '@breezeui/vue';

const isDark = useDark();

const theme = computed(() => {
  return isDark.value ? { primary: '#60a5fa', radius: 0.5 } : { primary: '#2563eb', radius: 0.5 };
});
</script>

<template>
  <BrConfigProvider :theme="theme">
    <slot />
  </BrConfigProvider>
</template>