useTheme

主题面板背后的状态与操作:主色、中性色、圆角、图标集、黑色主色与颜色模式,访客的选择保存在 localStorage,并能导出为 app.config 或 CSS 片段。自定义主题面板或在页面中切换主题时使用。

useTheme() 驱动页头的 ThemePicker。站点在 app.config 中配置的主题是基准值,访客在面板里的修改覆盖基准值并持久化到 localStorage,key 以站点名(site.name 的 kebab-case)为前缀。

用法

<script setup lang="ts">
const { primary, neutral, mode, resetTheme } = useTheme()
</script>

<template>
  <UButton label="Blue" @click="primary = 'blue'" />
  <UButton label="Dark" @click="mode = 'dark'" />
  <UButton label="Reset" @click="resetTheme()" />
</template>

签名

function useTheme(): {
  primary: WritableComputedRef<string>
  primaryColors: string[]
  neutral: WritableComputedRef<string>
  neutralColors: string[]
  radius: WritableComputedRef<number>
  radiuses: number[]
  icon: WritableComputedRef<string>
  icons: { label: string, icon: string, value: string }[]
  mode: WritableComputedRef<string>
  modes: ComputedRef<{ label: string, icon: string }[]>
  blackAsPrimary: ComputedRef<boolean>
  setBlackAsPrimary: (value: boolean) => void
  color: ComputedRef<string | undefined>
  style: { innerHTML: ComputedRef<string>, id: string, tagPriority: number }[]
  hasCSSChanges: ComputedRef<boolean>
  hasConfigChanges: ComputedRef<boolean>
  configLabel: string
  exportCSS: () => string
  exportConfig: () => string
  resetTheme: () => void
}

返回值

名称类型说明
primaryWritableComputedRef<string>主色,写入 appConfig.ui.colors.primary;设置时会关闭黑色主色
primaryColorsstring[]可选主色:vermilion 加 Tailwind 调色板中的彩色
neutralWritableComputedRef<string>中性色,写入 appConfig.ui.colors.neutral
neutralColorsstring[]可选中性色:paper、slate、gray、zinc、neutral、stone、taupe、mauve、mist、olive
radiusWritableComputedRef<number>圆角,单位 rem
radiusesnumber[]可选圆角:0、0.125、0.25、0.375、0.5
iconWritableComputedRef<string>图标集,写入时同步替换 appConfig.ui.icons
icons{ label, icon, value }[]可选图标集:lucide、phosphor、tabler
modeWritableComputedRef<string>颜色模式,写入 colorMode.preference
modesComputedRef<{ label, icon }[]>light、dark、system 三项
blackAsPrimaryComputedRef<boolean>是否以黑色(暗色模式下为白色)作为主色
setBlackAsPrimary(value: boolean) => void切换黑色主色
colorComputedRef<string | undefined>当前模式下中性色的 50 / 950 色值,用于 theme-color
styleobject[]圆角与黑色主色对应的 <style> 标签,由外壳注入 head
hasCSSChangesComputedRef<boolean>圆角或黑色主色是否偏离基准值
hasConfigChangesComputedRef<boolean>主色、中性色或图标集是否偏离基准值
configLabelstring导出配置的文件名,固定为 app.config.ts
exportCSS() => string导出与基准值不同的 CSS 变量
exportConfig() => string导出与基准值不同的 defineAppConfig(...) 代码
resetTheme() => void清除访客偏好,恢复 app.config 中的基准值

基准值

基准值在首次调用时从 app.config 读取:ui.colors.primary、ui.colors.neutral,以及 theme.radius(默认 0.25)、theme.icons(默认 lucide)、theme.blackAsPrimary(默认 false)。修改站点默认主题时改 app.config,不要在代码里写入这些 ref,详见 主题与字体。

更新日志

No recent changes
Copyright © 2024 - 2026