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() 無條件註冊，任何模式下都能安全呼叫——只是非 toggle 模式的切換方法不改變主題。

基本用法

加载中...

<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 推導初始值。