Skip to content

useTheme

主题状态单例:读取/切换配色家族与明暗档。

何时用

  • 自定义主题切换 UI(现成 UI 直接用 ThemeSwitcher
  • 业务逻辑需要感知当前主题(如图表配色)

用法

ts
import { useTheme } from '@luxeanor/ui'

const { family, mode, resolvedMode, setFamily, setMode } = useTheme()

setFamily('ink')          // 切家族,立即写入 <html data-theme> 并持久化
setMode('auto')           // 'light' | 'dark' | 'auto'
console.log(resolvedMode.value)  // auto 解析后的实际档位:'light' | 'dark'

API

返回类型说明
familyReadonly<Ref<'amethyst' | 'obsidian' | 'ink' | 'emerald'>>当前家族
modeReadonly<Ref<'light' | 'dark' | 'auto'>>当前设置档
resolvedModeComputedRef<'light' | 'dark'>auto 解析后的实际档位
setFamily(f: ThemeFamily) => void切家族(写属性 + 持久化)
setMode(m: ThemeModeSetting) => void切明暗档(写属性 + 持久化)

行为:

  • 模块级单例——所有调用方共享同一份状态,首个调用完成初始化
  • 持久化 localStorage['lx-theme'](JSON { family, mode }
  • auto 监听系统 prefers-color-scheme 实时跟随
  • SSR 返回默认值(amethyst / light),不触碰 DOM
  • 另有 themeBootScript 字符串导出用于首屏防闪烁,见主题定制