主題定制

lh-ui-plus 提供了一套完整的 CSS 變數主題系統，支援國風主題色、暗色模式、花紋背景、執行時切換等豐富定製能力。

想要視覺化地調色並直接匯出一份 scss？見主題定製臺。

國風主色體系

元件庫以傳統水墨丹青為設計靈感，定義了 8 種國風色彩主題：

色彩	寓意	主色	hover	應用
靛藍	青花瓷之藍	`#2B4C7C`	`#3D649E`	主要按鈕、連結、聚焦態
松花綠	竹影青翠	`#5B8C5A`	`#6FA36E`	成功狀態
藤黃	秋葉金黃	`#C4A35A`	`#D4B76F`	警告狀態
朱砂（危險）	印泥朱紅	`#B23A3A`	`#C45050`	危險/錯誤狀態（`--lh-danger-*`）
黛色	水墨淡彩	`#7A7A7A`	`#8F8F8F`	訊息狀態
金色	華貴古韻	`#B8860B`	`#D4A843`	裝飾點綴（`--lh-gold-*`）
朱砂紅（強調）	朱砂偏紅的強調變體	`#C43A31`	`#E85D4A`	強調色（`--lh-vermilion-*`）
玉色	翠竹清雅	`#5B8C5A`	`#7AAE7A`	成功/裝飾（與松花綠同值）

每種色彩通常包含 4 個層級（主色/hover/active/light 背景色），主色與金色額外提供 lighter 描邊色（*-color-border），確保在不同情境下都有合適的對比度。

CSS 變數主題系統

所有主題色透過 CSS 自訂屬性（--lh-*）實現，共 88+ 個變數，覆蓋以下類別：

顏色變數

變數前綴	說明	範例
`--lh-primary-color`	主色基礎值	`#2B4C7C`
`--lh-primary-color-hover`	主色 hover 態	`#3D649E`
`--lh-primary-color-active`	主色 active 態	`#1F3A5F`
`--lh-primary-color-bg`	主色淺色背景	`#E8EDF3`
`--lh-success-color`	成功色	`#5B8C5A`
`--lh-warning-color`	警告色	`#C4A35A`
`--lh-danger-color`	危險色	`#B23A3A`
`--lh-info-color`	訊息色	`#7A7A7A`

文字變數

變數名	說明	預設值
`--lh-text-primary`	主要文字	`#2C2C2C`
`--lh-text-regular`	常規文字	`#5A5A5A`
`--lh-text-secondary`	輔助文字	`#8A8A8A`
`--lh-text-placeholder`	佔位符	`#B0B0B0`
`--lh-text-disabled`	停用文字	`#C8C8C8`

邊框變數

變數名	說明	預設值
`--lh-border-color-base`	預設邊框	`#D8D3CC`
`--lh-border-color-light`	輕量邊框	`#E5E0D8`
`--lh-border-radius-base`	基礎圓角	`2px`
`--lh-border-radius-round`	膠囊圓角	`20px`

背景變數

變數名	說明	預設值
`--lh-bg-color`	元件背景	`#FAF6F0`（宣紙色）
`--lh-bg-color-page`	頁面背景	`#F5F0EB`
`--lh-bg-color-overlay`	遮罩背景	`rgba(26, 26, 26, 0.4)`

陰影變數

變數名	說明
`--lh-box-shadow-base`	預設陰影
`--lh-box-shadow-light`	輕量陰影
`--lh-box-shadow-lighter`	極輕陰影

字型變數

變數名	說明	預設值
`--lh-font-family`	字型族	`Noto Serif SC, STSong, SimSun...`
`--lh-font-size-base`	基礎字級	`14px`
`--lh-font-size-small`	小號字級	`13px`
`--lh-font-weight-primary`	常規字重	`400`
`--lh-font-line-height-primary`	行高	`1.8`

間距變數

變數名	值	用途
`--lh-spacing-xs`	`4px`	極小間距
`--lh-spacing-sm`	`8px`	小間距
`--lh-spacing-md`	`12px`	中間距
`--lh-spacing-base`	`16px`	基礎間距
`--lh-spacing-lg`	`20px`	大間距
`--lh-spacing-xl`	`24px`	超大間距

Z-Index 變數

變數名	值	用途
`--lh-z-index-dropdown`	`1000`	下拉選單
`--lh-z-index-modal`	`1050`	模態框
`--lh-z-index-tooltip`	`2000`	提示框

過渡變數

變數名	值	說明
`--lh-transition-duration-fast`	`0.25s`	快速過渡
`--lh-transition-duration-base`	`0.3s`	預設過渡
`--lh-transition-duration-slow`	`0.4s`	慢速過渡

暗色主題

元件庫內建暗色主題樣式，所有 CSS 變數在暗色模式下自動切換為適配值。

方案一：使用 `useLhTheme` 組合式函式

Composition API

vue

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

const { theme, toggleTheme, setTheme } = useLhTheme()
</script>

<template>
  <div>
    <LhButton @click="toggleTheme">
      {{ theme === 'dark' ? '切换明色' : '切换暗色' }}
    </LhButton>
    <LhButton @click="() => setTheme('light')">明色</LhButton>
    <LhButton @click="() => setTheme('dark')">暗色</LhButton>
  </div>
</template>

Options API

vue

<script>
import { useLhTheme } from '@lh-ui/vue3'

export default {
  setup() {
    const { theme, toggleTheme, setTheme } = useLhTheme()
    return { theme, toggleTheme, setTheme }
  },
}
</script>

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

useLhTheme 會自動將主題狀態持久化到 localStorage（key: lh-ui-theme），重新整理頁面後主題不會丟失。

方案二：HTML 屬性切換

在根元素設定 data-theme="dark" 即可全域啟用暗色模式：

html

<!DOCTYPE html>
<html lang="zh-CN" data-theme="dark">
  <!-- ... -->
</html>

自訂主題色（青花瓷 / 松花綠 / 朱砂紅）

除了內建的明暗主題，元件庫支援透過 themeVars 自訂任意顏色組合，實現個性化主題。

下面範例是手寫自訂變數的演示，取值為講解而調整，與預設主題中的同名內建預設（cerblue / songhua / zhusha）並不完全相同。要直接使用內建預設，請用 useLhPresetTheme 或 getThemeVars(name)。

青花瓷主題

以深靛藍為主色調，靈感來自傳統青花瓷。

Composition API

vue

<script setup lang="ts">
const cerblueTheme = {
  'primary-color': '#2B4C7C',
  'primary-color-hover': '#3D649E',
  'primary-color-active': '#1F3A5F',
  'primary-color-bg': '#E8EDF3',
  'bg-color': '#F0F4F8',
  'border-color-base': '#C8D6E5',
}
</script>

<template>
  <LhConfigProvider :theme-vars="cerblueTheme">
    <LhButton type="primary">青花瓷按钮</LhButton>
    <LhInput placeholder="青花瓷输入框" />
  </LhConfigProvider>
</template>

Options API

vue

<script>
import { LhConfigProvider, LhButton, LhInput } from '@lh-ui/vue3'

export default {
  components: { LhConfigProvider, LhButton, LhInput },
  data() {
    return {
      cerblueTheme: {
        'primary-color': '#2B4C7C',
        'primary-color-hover': '#3D649E',
        'primary-color-bg': '#E8EDF3',
        'bg-color': '#F0F4F8',
      },
    }
  },
}
</script>

<template>
  <LhConfigProvider :theme-vars="cerblueTheme">
    <LhButton type="primary">青花瓷按钮</LhButton>
  </LhConfigProvider>
</template>

松花綠主題

以竹綠為點綴，營造清新自然的風格。

vue

<script setup lang="ts">
const bambooTheme = {
  'primary-color': '#5B8C5A',
  'primary-color-hover': '#6FA36E',
  'primary-color-bg': '#EDF5EC',
  'success-color': '#5B8C5A',
  'bg-color': '#F6FAF5',
}
</script>

<template>
  <LhConfigProvider :theme-vars="bambooTheme">
    <LhButton type="primary">竹林幽径</LhButton>
    <LhTag type="success">新叶</LhTag>
  </LhConfigProvider>
</template>

朱砂紅主題

以印泥朱紅為主調，突出典雅華貴的氛圍。

vue

<script setup lang="ts">
const vermilionTheme = {
  'primary-color': '#C43A31',
  'primary-color-hover': '#E85D4A',
  'primary-color-bg': '#FDF0EE',
  'bg-color': '#FFFBF9',
  'border-color-base': '#F0D5CF',
}
</script>

<template>
  <LhConfigProvider :theme-vars="vermilionTheme">
    <LhButton type="primary">丹书铁券</LhButton>
  </LhConfigProvider>
</template>

花紋背景系統

元件庫提供了一套國風詩意花紋背景系統，支援 6 種預設花紋，可配合 patternComponents 白名單精確控制應用範圍。

預設花紋

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

全域花紋設定

Composition API

vue

<script setup lang="ts">
const config = {
  themeVars: {
    'bg-pattern': 'var(--lh-pattern-cloud)',
    'bg-pattern-opacity': '0.15',
  },
  patternComponents: ['button', 'input'] as const,
}
</script>

<template>
  <LhConfigProvider
    :theme-vars="config.themeVars"
    :pattern-components="config.patternComponents"
  >
    <!-- 按鈕和輸入框會應用紋理，Dialog 不會 -->
    <LhButton>带花纹的按钮</LhButton>
    <LhInput placeholder="带花纹的输入框" />
  </LhConfigProvider>
</template>

Options API

vue

<script>
export default {
  data() {
    return {
      config: {
        themeVars: {
          'bg-pattern': 'var(--lh-pattern-cloud)',
          'bg-pattern-opacity': '0.15',
        },
        patternComponents: ['button', 'input'],
      },
    }
  },
}
</script>

<template>
  <LhConfigProvider
    :theme-vars="config.themeVars"
    :pattern-components="config.patternComponents"
  >
    <LhButton>带花纹的按钮</LhButton>
  </LhConfigProvider>
</template>

花紋變數參考

變數名	說明	預設值
`--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`

完整設定範例

以下展示 ConfigProvider 的完整設定用法，整合主題、語言、尺寸、花紋等所有能力。

Composition API

vue

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

const configProvider = {
  size: 'medium' as const,
  locale: zhCN,
  themeVars: {
    'primary-color': '#2B4C7C',
    'bg-pattern': 'var(--lh-pattern-cloud)',
    'bg-pattern-opacity': '0.15',
  },
  patternComponents: ['button', 'input', 'dialog'],
}
</script>

<template>
  <LhConfigProvider
    :size="configProvider.size"
    :locale="configProvider.locale"
    :theme-vars="configProvider.themeVars"
    :pattern-components="configProvider.patternComponents"
  >
    <slot />
  </LhConfigProvider>
</template>

Options API

vue

<script>
import { zhCN } from '@lh-ui/vue3'

export default {
  data() {
    return {
      configProvider: {
        size: 'medium',
        locale: zhCN,
        themeVars: {
          'primary-color': '#2B4C7C',
          'bg-pattern': 'var(--lh-pattern-cloud)',
        },
        patternComponents: ['button', 'input', 'dialog'],
      },
    }
  },
}
</script>

<template>
  <LhConfigProvider
    :size="configProvider.size"
    :locale="configProvider.locale"
    :theme-vars="configProvider.themeVars"
    :pattern-components="configProvider.patternComponents"
  >
    <slot />
  </LhConfigProvider>
</template>

主題變數優先級

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

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

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

sx 快速版面配置

sx 屬性提供了一種宣告式的內聯版面配置方式，無需編寫 CSS 即可設定元件的間距和尺寸。目前已在以下元件中支援：Button、Input、Dialog、Tooltip、Alert、Card、Empty、Breadcrumb、Pagination、Steps、Tabs、Skeleton。

原理

sx 基於 8px 基準網格，數字乘 8 得到實際像素值。例如 mt: 2 等價於 marginTop: 16px。

支援屬性

間距

屬性	說明	範例	等效 CSS
`m`	四邊外距	`m: 2`	`margin: 16px`
`mx`	水平外距	`mx: 1`	`marginLeft: 8px; marginRight: 8px`
`my`	垂直外距	`my: 1`	`marginTop: 8px; marginBottom: 8px`
`mt`, `mr`, `mb`, `ml`	單邊外距	`mt: 2`	`marginTop: 16px`
`p`	四邊內距	`p: 3`	`padding: 24px`
`px`	水平內距	`px: 2`	`paddingLeft: 16px; paddingRight: 16px`
`py`	垂直內距	`py: 1`	`paddingTop: 8px; paddingBottom: 8px`
`pt`, `pr`, `pb`, `pl`	單邊內距	`pt: 2`	`paddingTop: 16px`

尺寸

屬性	說明	範例
`w`	寬度（數字為 px，字串為值本身）	`w: 200` 或 `w: '100%'`
`h`	高度	`h: 100` 或 `h: 'auto'`

Flex 版面配置

屬性	說明	範例
`display`	顯示類型	`display: 'flex'`
`flex`	flex 簡寫	`flex: '1 1 0%'`
`flexDirection`	主軸方向	`flexDirection: 'column'`
`alignItems`	交叉軸對齊	`alignItems: 'center'`
`justifyContent`	主軸對齊	`justifyContent: 'flex-end'`

使用範例

vue

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

const visible = ref(false)
</script>

<template>
  <!-- 按鈕間距 -->
  <LhButton type="primary" :sx="{ mt: 2, mx: 1 }">带间距的按钮</LhButton>

  <!-- 輸入框外距 -->
  <LhInput placeholder="输入框上下间距" :sx="{ my: 1 }" />

  <!-- Dialog 寬度：sx 僅支援 w/h 與間距類屬性 -->
  <LhDialog v-model="visible" title="示例" :sx="{ w: 480 }">
    <p>固定宽度的对话框</p>
  </LhDialog>
</template>

vue

<script>
export default {
  data() {
    return { visible: false }
  },
}
</script>

<template>
  <LhButton type="primary" :sx="{ mt: 2, mx: 1 }">带间距的按钮</LhButton>
</template>

主題定制 ​

國風主色體系 ​

CSS 變數主題系統 ​

顏色變數 ​

文字變數 ​

邊框變數 ​

背景變數 ​

陰影變數 ​

字型變數 ​

間距變數 ​

Z-Index 變數 ​

過渡變數 ​

暗色主題 ​

方案一：使用 useLhTheme 組合式函式 ​

Composition API ​

Options API ​

方案二：HTML 屬性切換 ​

自訂主題色（青花瓷 / 松花綠 / 朱砂紅） ​

青花瓷主題 ​

Composition API ​

Options API ​

松花綠主題 ​

朱砂紅主題 ​

花紋背景系統 ​

預設花紋 ​

全域花紋設定 ​

Composition API ​

Options API ​

花紋變數參考 ​

完整設定範例 ​

Composition API ​

Options API ​

主題變數優先級 ​

sx 快速版面配置 ​

原理 ​

支援屬性 ​

間距 ​

尺寸 ​

Flex 版面配置 ​

使用範例 ​

主題定制

國風主色體系

CSS 變數主題系統

顏色變數

文字變數

邊框變數

背景變數

陰影變數

字型變數

間距變數

Z-Index 變數

過渡變數

暗色主題

方案一：使用 `useLhTheme` 組合式函式

Composition API

Options API

方案二：HTML 屬性切換

自訂主題色（青花瓷 / 松花綠 / 朱砂紅）

青花瓷主題

Composition API

Options API

松花綠主題

朱砂紅主題

花紋背景系統

預設花紋

全域花紋設定

Composition API

Options API

花紋變數參考

完整設定範例

Composition API

Options API

主題變數優先級

sx 快速版面配置

原理

支援屬性

間距

尺寸

Flex 版面配置

使用範例