花紋背景系統

lh-ui-plus 提供了一套國風詩意花紋背景系統，支援 6 種預設花紋圖案，透過 CSS 變數（bg-pattern）或元件的 bgPattern prop 應用。明暗模式切換是另一套獨立能力，見文末「明暗模式」。

預設花紋

系統內建以下 6 種花紋：

花紋名	CSS 變數	說明
無	--lh-pattern-none	預設無花紋
柳葉	--lh-pattern-willow	細長柳葉，疏密有致
祥雲	--lh-pattern-cloud	祥雲舒展，蜿蜒流轉
水波	--lh-pattern-water	漣漪微動，層層疊疊
雪花	--lh-pattern-snow	六角雪花，細枝分岔
梅花	--lh-pattern-plum	五瓣舒展，蕊心分明
竹葉	--lh-pattern-bamboo	披針形竹葉，錯落有致

使用方式

透過 ConfigProvider 全域設定

<template>
  <LhConfigProvider :theme-vars="{ 'bg-pattern': 'var(--lh-pattern-willow)' }">
    <LhButton>默认</LhButton>
    <LhButton type="primary">主要</LhButton>
  </LhConfigProvider>
</template>

控制花紋應用範圍（patternComponents 白名單）

預設情況下，全域 bg-pattern 不會應用到任何元件，需要透過 patternComponents 白名單顯式開啟：

<script setup lang="ts">
import { ref } from 'vue'

const visible = ref(false)
</script>

<template>
  <LhConfigProvider
    :theme-vars="{ 'bg-pattern': 'var(--lh-pattern-cloud)' }"
    :pattern-components="['button', 'input']"
  >
    <!-- 按鈕和輸入框會應用花紋，Dialog 不會 -->
    <LhButton>带花纹的按钮</LhButton>
    <LhInput placeholder="带花纹的输入框" />
    <LhDialog v-model="visible">此对话框没有花纹</LhDialog>
  </LhConfigProvider>
</template>

元件級別花紋設定

元件自身透過 bgPattern prop 或 themeVars 設定的花紋不受白名單限制：

<template>
  <LhButton :bg-pattern="'var(--lh-pattern-bamboo)'">
    此按钮始终有花纹
  </LhButton>
</template>

自訂花紋透明度

<template>
  <LhConfigProvider
    :theme-vars="{
      'bg-pattern': 'var(--lh-pattern-snow)',
      'bg-pattern-opacity': '0.3',
      'bg-pattern-color': 'rgba(255, 0, 0, 0.2)',
    }"
  >
    <LhButton>自定义透明度</LhButton>
  </LhConfigProvider>
</template>

CSS 變數參考

變數名	說明	預設值
--lh-bg-pattern	花紋背景 URL	none
--lh-bg-pattern-repeat	花紋平鋪模式	repeat
--lh-bg-pattern-size	花紋大小	40px
--lh-bg-pattern-opacity	花紋透明度	0.15
--lh-bg-pattern-color	花紋顏色	var(--lh-decoration-color, rgba(184, 134, 11, 0.12))
--lh-bg-pattern-blend	花紋混合模式	soft-light

明暗模式

花紋系統本身透過 CSS 變數控制，與明暗模式互不影響。明暗模式使用 useLhTheme 組合式函式切換（寫入 data-theme 屬性）：

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

const { theme, toggleTheme, setTheme } = useLhTheme()

// 切換明暗主題
function onToggle() {
  toggleTheme()
}
</script>

<template>
  <div>
    <LhButton @click="onToggle">
      {{ theme === 'dark' ? '切换明色' : '切换暗色' }}
    </LhButton>
  </div>
</template>

主題變數優先級

元件最終的 CSS 變數會按以下優先級合併（後者覆寫前者）：

1. ConfigProvider 全域 themeVars（最低優先級）
2. ConfigProvider 按元件 componentTheme[元件名]
3. 元件自身 themeVars prop
4. 元件自身 bgPattern prop（最高優先級）

對於 bg-pattern 變數，還會額外受到 patternComponents 白名單控制：只有白名單中的元件才會應用全域設定的 bg-pattern。