@hilime/theme-toggle

一个通用的主题切换工具库，支持原生 JavaScript、React 和 Vue 应用。

特性

• 🎨 多主题支持 - 浅色、深色、跟随系统
• ⚡ 轻量高效 - 零依赖，体积小，性能优秀
• 🔧 框架无关 - 支持原生 JS、React、Vue
• 💾 持久化存储 - 自动保存用户偏好
• 🎭 平滑过渡 - 内置过渡动画
• 📱 响应式 - 自动响应系统主题变化
• 🛡️ TypeScript - 完整的类型支持

安装

npm install @hilime/theme-toggle
# 或
yarn add @hilime/theme-toggle
# 或
pnpm add @hilime/theme-toggle

快速开始

原生 JavaScript

import { themeManager } from '@hilime/theme-toggle/vanilla';
// 或者在浏览器中直接使用
// <script src="path/to/vanilla.umd.js"></script>

// 注册主题
themeManager.registerTheme('light');
themeManager.registerTheme('dark');
themeManager.registerTheme('system');

// 设置主题
themeManager.setTheme('dark');

// 获取当前主题
const currentTheme = themeManager.getCurrentTheme();

// 监听主题变化
themeManager.subscribe((theme) => {
  console.log('当前主题:', theme);
});

React

import { ThemeProvider, useTheme } from '@hilime/theme-toggle/react';

function App() {
  return (
    <ThemeProvider themes={['light', 'dark', 'system']} defaultTheme="light">
      <MyComponent />
    </ThemeProvider>
  );
}

function MyComponent() {
  const { currentTheme, setTheme, themes } = useTheme();
  
  return (
    <div>
      <p>当前主题: {currentTheme}</p>
      <button onClick={() => setTheme('dark')}>深色模式</button>
      <select value={currentTheme} onChange={(e) => setTheme(e.target.value)}>
        {themes.map(theme => (
          <option key={theme} value={theme}>{theme}</option>
        ))}
      </select>
    </div>
  );
}

Vue 3

<template>
  <div>
    <p>当前主题: {{ theme }}</p>
    <button @click="setTheme('dark')">深色模式</button>
    <select :value="theme" @change="setTheme($event.target.value)">
      <option v-for="t in themes" :key="t" :value="t">{{ t }}</option>
    </select>
  </div>
</template>

<script setup>
import { useTheme } from '@hilime/theme-toggle/vue';

const { theme, setTheme, themes } = useTheme({
  defaultTheme: 'light',
  storageKey: 'my-theme'
});
</script>

CSS 样式

库提供了一个内置的 CSS 文件，包含基本的主题变量：

/* 引入 CSS 文件 */
@import '@hilime/theme-toggle/theme.css';

/* 使用 CSS 变量 */
body {
  background-color: var(--bg-color);
  color: var(--text-color);
}

.card {
  background-color: var(--card-bg);
  border-color: var(--border-color);
}

或者在 HTML 中直接引用：

<link rel="stylesheet" href="path/to/theme.css">

API 文档

ThemeManager 类

主要方法

• registerTheme(theme: string) - 注册主题
• setTheme(theme: string) - 设置主题
• getCurrentTheme(): string - 获取当前主题
• getAllThemes(): string[] - 获取所有已注册的主题
• subscribe(callback: (theme: string) => void) - 订阅主题变化

配置选项

• themes - 主题集合
• defaultTheme - 默认主题
• storageKey - 本地存储键名

React

ThemeProvider 属性

interface ThemeProviderProps {
  children: React.ReactNode;
  themes: string[];           // 可用主题列表
  defaultTheme?: string;      // 默认主题
  storageKey?: string;        // 存储键名
}

useTheme Hook

const {
  currentTheme,              // 当前主题
  setTheme,                  // 设置主题函数
  themes                     // 可用主题列表
} = useTheme();

Vue 3

useTheme 组合式函数

const {
  theme,                     // 响应式主题状态
  setTheme,                  // 设置主题函数
  themes                     // 可用主题列表
} = useTheme({
  defaultTheme?: string,     // 默认主题
  storageKey?: string        // 存储键名
});

在线演示

查看 example 目录中的演示文件：

• example/index.html - 演示导航页面
• example/vanilla.html - 原生 JavaScript 演示
• example/react.html - React 演示
• example/vue.html - Vue 演示

开发

# 安装依赖
pnpm install

# 构建
pnpm run build

# 开发模式
pnpm run dev

# 启动演示服务器
pnpm run serve

浏览器支持

• Chrome >= 60
• Firefox >= 55
• Safari >= 12
• Edge >= 79

许可证

MIT License