預設主題

lh-ui-plus 內建 5 種國風預設主題，開箱即用。有兩種使用方式：

• 全域切換（推薦）：useLhPresetTheme 把預設變數寫到 :root，整站生效並持久化到 localStorage。
• 局部切換：LhConfigProvider :theme-vars 隻影響其子樹，適合同一頁面內並列展示多套主題。

預設變數可透過 getThemeVars(name)（來自 @lh-ui/vue3/theme）取得，name 取值見下方各小節。

站臺級主題切換

本站在頂部導覽列提供「主題預設」下拉，可一鍵切換 5 種國風主題。選擇會持久化到 localStorage['lh-docs-preset']，重新整理後仍保持。

主題預設與明暗模式是兩軸獨立的系統：VitePress 導覽列右側的 🌙/☀️ 切換明/暗色，「主題預設」下拉切換色板（青花瓷、朱砂、松花綠等）。暗色模式下預設同樣生效，表現為不同色調的暗色主題。

通用主題屬性 themeVars 與 bgPattern

所有 lh-ui-plus 元件都支援透過 LhConfigProvider 或元件自身 themeVars 屬性進行局部主題覆寫；紋樣背景透過 bgPattern 屬性統一控制（花紋來自 ConfigProvider 的 patternComponents 白名單）。這兩個屬性是跨元件的通用能力，因此不在各元件文件裡逐一九例，統一在主題定製和花紋背景系統中說明。

青花瓷 / Ceramic Blue（預設）

預設主題，青花瓷釉下彩，清雅素淨。預設名：cerblue。

青花瓷主題

標籤

<script setup lang="ts">
import { LhConfigProvider, LhButton, LhTag, LhSwitch } from '@lh-ui/vue3'
import { getThemeVars } from '@lh-ui/vue3/theme'

// getThemeVars 傳回的鍵已帶 --lh- 前綴，ConfigProvider 的前綴處理是冪等的，可直接傳入
const cerblueTheme = getThemeVars('cerblue')
</script>

<template>
  <LhConfigProvider :theme-vars="cerblueTheme">
    <div style="display: flex; gap: 8px; flex-wrap: wrap">
      <LhButton type="primary">主要按钮</LhButton>
      <LhButton type="success">成功</LhButton>
      <LhButton type="warning">警告</LhButton>
      <LhButton type="danger">危险</LhButton>
      <LhTag type="primary">标签</LhTag>
      <LhSwitch />
    </div>
  </LhConfigProvider>
</template>

松花綠 / Pine Green

竹林修竹，生機勃勃。預設名：songhua。

<script setup lang="ts">
import { LhConfigProvider, LhButton, LhTag, LhSwitch } from '@lh-ui/vue3'
import { getThemeVars } from '@lh-ui/vue3/theme'

const songhuaTheme = getThemeVars('songhua')
</script>

<template>
  <LhConfigProvider :theme-vars="songhuaTheme">
    <div style="display: flex; gap: 8px; flex-wrap: wrap">
      <LhButton type="primary">主要按钮</LhButton>
      <LhTag type="primary">标签</LhTag>
      <LhSwitch />
    </div>
  </LhConfigProvider>
</template>

朱砂 / Vermilion

傳統印章朱砂紅，喜慶莊重。預設名：zhusha。

<script setup lang="ts">
import { LhConfigProvider, LhButton, LhTag, LhSwitch } from '@lh-ui/vue3'
import { getThemeVars } from '@lh-ui/vue3/theme'

const zhushaTheme = getThemeVars('zhusha')
</script>

<template>
  <LhConfigProvider :theme-vars="zhushaTheme">
    <div style="display: flex; gap: 8px; flex-wrap: wrap">
      <LhButton type="primary">主要按钮</LhButton>
      <LhTag type="primary">标签</LhTag>
      <LhSwitch />
    </div>
  </LhConfigProvider>
</template>

水墨 / Ink Wash

水墨丹青，素雅極簡。預設名：shuimo。

<script setup lang="ts">
import { LhConfigProvider, LhButton, LhTag, LhSwitch } from '@lh-ui/vue3'
import { getThemeVars } from '@lh-ui/vue3/theme'

const shuimoTheme = getThemeVars('shuimo')
</script>

<template>
  <LhConfigProvider :theme-vars="shuimoTheme">
    <div style="display: flex; gap: 8px; flex-wrap: wrap">
      <LhButton type="primary">主要按钮</LhButton>
      <LhTag type="primary">标签</LhTag>
      <LhSwitch />
    </div>
  </LhConfigProvider>
</template>

藤黃 / Golden Autumn

深秋楓黃，溫暖金黃。預設名：golden。

<script setup lang="ts">
import { LhConfigProvider, LhButton, LhTag, LhSwitch } from '@lh-ui/vue3'
import { getThemeVars } from '@lh-ui/vue3/theme'

const goldenTheme = getThemeVars('golden')
</script>

<template>
  <LhConfigProvider :theme-vars="goldenTheme">
    <div style="display: flex; gap: 8px; flex-wrap: wrap">
      <LhButton type="primary">主要按钮</LhButton>
      <LhTag type="primary">标签</LhTag>
      <LhSwitch />
    </div>
  </LhConfigProvider>
</template>

主題對比

主題	預設名	主色 --lh-primary-color	主色背景 --lh-primary-color-bg	描述
青花瓷	cerblue	#2B4C7C	#E8EDF3	青花瓷釉下彩，清雅素淨
松花綠	songhua	#5B8C5A	#E8F5E8	竹林修竹，生機勃勃
朱砂	zhusha	#B23A3A	#FDF0F0	傳統印章朱砂紅，喜慶莊重
水墨	shuimo	#2C2C2C	#F5F5F5	水墨丹青，素雅極簡
藤黃	golden	#B8860B	#FBF6EA	深秋楓黃，溫暖金黃

預設只覆蓋主色（primary）色板，--lh-primary-color-bg 是主色的淡化背景色，並非整頁背景色。

程式化切換

兩種機制，按作用域選擇：

• 全域切換（推薦）：useLhPresetTheme 把預設變數寫到 :root，整站生效並持久化到 localStorage，重新整理後保持選擇。無需 LhConfigProvider 包裹。
• 局部切換：LhConfigProvider :theme-vars 隻影響其子樹，適合同一頁面內並列展示多套主題。

全域預設切換

下面這組切換按鈕會寫入 :root，因此整個文件站都會受影響——這也是本頁不再單獨演示全域切換的原因。

<script setup lang="ts">
import { LhButton, useLhPresetTheme } from '@lh-ui/vue3'

const { preset, setPreset, presets } = useLhPresetTheme()
</script>

<template>
  <LhButton
    v-for="theme in presets"
    :key="theme.name"
    :type="preset === theme.name ? 'primary' : 'default'"
    @click="setPreset(theme.name)"
  >
    {{ theme.label }}
  </LhButton>
</template>

局部作用域切換

傳入 applyToRoot: false 可關閉全域寫入，只取傳回的 themeVars（已按 ConfigProvider 約定去掉 --lh- 前綴），由 Provider 接管作用範圍。

切換按鈕要放在 LhConfigProvider 外部，否則按鈕自身也會被主題改色：

局部切換預設主題

標籤

<script setup lang="ts">
import { LhConfigProvider, LhButton, LhTag, LhSwitch, useLhPresetTheme } from '@lh-ui/vue3'

const { preset, setPreset, presets, themeVars } = useLhPresetTheme({ applyToRoot: false })
</script>

<template>
  <div style="display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 12px">
    <LhButton
      v-for="theme in presets"
      :key="theme.name"
      :type="preset === theme.name ? 'primary' : 'default'"
      @click="setPreset(theme.name)"
    >
      {{ theme.label }}
    </LhButton>
  </div>
  <LhConfigProvider :theme-vars="themeVars">
    <div style="display: flex; gap: 8px; flex-wrap: wrap">
      <LhButton type="primary">主要按钮</LhButton>
      <LhButton type="success">成功</LhButton>
      <LhButton type="warning">警告</LhButton>
      <LhButton type="danger">危险</LhButton>
      <LhTag type="primary">标签</LhTag>
      <LhSwitch />
    </div>
  </LhConfigProvider>
</template>

前綴寫法：ConfigProvider 的前綴處理是冪等的，getThemeVars()（來自 @lh-ui/vue3/theme）傳回的鍵已帶 --lh- 前綴，可直接傳入 :theme-vars；而 useLhPresetTheme() 傳回的 themeVars 已去掉前綴。兩者都能直接用於 :theme-vars，無需二次處理。