npm package: @hilime/theme-toggle
Description: A universal theme toggle library for vanilla JS, React, and Vue
Author: Shunrong Lai
Latest version: 1.0.0

# @hilime/theme-toggle

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

## 特性

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

## 安装

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

## 快速开始

### 原生 JavaScript

```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

```jsx
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

```vue
<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
/* 引入 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 中直接引用：

```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 属性

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

#### useTheme Hook

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

### Vue 3

#### useTheme 组合式函数

```typescript
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 演示

## 开发

```bash
# 安装依赖
pnpm install

# 构建
pnpm run build

# 开发模式
pnpm run dev

# 启动演示服务器
pnpm run serve
```

## 浏览器支持

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

## 许可证

MIT License