useTheme()

useTheme() 提供一套完整的主题管理机制（主题由 swift.config.json 的 theme.mode 决定）：

将主题值持久化到 localStorage，刷新页面后自动恢复。
将当前主题写入 html[data-theme] 属性，全局 CSS 可通过 [data-theme='dark'] 选择器切换样式变量。
auto 模式下读取系统偏好（prefers-color-scheme），自动应用浅色或深色；resolvedTheme 给出当前实际明暗（auto 态也会解析成 light / dark）。
仅 theme.mode: 'toggle' 时允许用户切换（toggleTheme / setTheme 生效）；system / dark / light 模式下主题由 mode 锁定，二者为 no-op。

useTheme() 无条件注册，任何 theme.mode 下都能安全调用——非 toggle 模式下切换方法为 no-op（主题由 mode 锁定）。

基础用法

加载中...

<script setup lang="ts">
const { theme, setTheme, toggleTheme } = useTheme()
</script>

<template>
  <!-- 显示当前主题 -->
  <span>当前主题：{{ theme }}</span>

  <!-- 循环切换按钮 -->
  <button @click="toggleTheme">
    {{ theme === 'dark' ? '切换到浅色' : '切换到深色' }}
  </button>

  <!-- 精确设置 -->
  <button @click="setTheme('light')">浅色</button>
  <button @click="setTheme('dark')">深色</button>
  <button @click="setTheme('auto')">跟随系统</button>
</template>

监听主题变化

const { theme } = useTheme()

watch(theme, (newTheme) => {
  console.log('主题切换为', newTheme)
})

CSS 集成

加载中...

框架通过 html[data-theme] 属性控制全局主题变量。在 app/assets/css/ 中按如下方式定义各主题的 CSS 变量：

:root {
  --background: #ffffff;
  --foreground: #1f2937;
}

[data-theme='dark'] {
  --background: #0f172a;
  --foreground: #f1f5f9;
}

返回值

名称	类型	说明
`theme`	`Ref<'light' \| 'dark' \| 'auto'>`	用户选择的主题状态。初始值按 mode 推导（system→auto / dark→dark / light→light / toggle→default）
`resolvedTheme`	`ComputedRef<'light' \| 'dark'>`	当前实际明暗（`auto` 态解析成系统偏好）。切 logo / 插画按它判断
`mode`	`'system' \| 'toggle' \| 'dark' \| 'light'`	站点主题模式（只读，来自 `theme.mode` 配置）
`toggleStates`	`2 \| 3`	切换器形态（只读）。3=三态循环 / 2=两态
`setTheme`	`(t: 'light' \| 'dark' \| 'auto') => void`	设置指定主题，同步持久化 + 更新 `html[data-theme]`。仅 toggle 模式生效
`toggleTheme`	`() => void`	循环切换。仅 toggle 模式生效；3 态 `auto→light→dark→auto`（可回自适应）/ 2 态 `light↔dark`

注意事项

useTheme() 的状态是全局共享的，多处调用返回同一个响应式引用，无需担心状态不一致。
toggleTheme / setTheme 仅在 theme.mode: 'toggle' 时生效，其它模式为 no-op（主题由 mode 锁定，不给用户改）。
不想自己写切换按钮时，直接用框架内置的 SwThemeSwitch——它自 gate，仅 toggle 模式渲染。
初始化时会从 localStorage 读取保存的主题（仅 toggle 模式），未保存时按 mode 推导初始值。