1.0.2 • Published 11 months ago
theme-toggle-animation v1.0.2
一个简单好用的主题切换动画
ThemeSwitcher 是一个轻量级的主题切换器，支持在浅色和深色主题之间平滑切换，并提供了丰富的自定义选项。它基于 View Transitions API，没有使用第三方库，所以你可以在 React 、 Vue 或者其他项目中使用。
实现思路
- 创建一个类来封装主题切换功能
- 使用 View Transitions API 来实现动画效果
- 提供配置选项,允许用户自定义动画效果
- 实现主题状态的保存和读取
- 添加回退机制,以确保在不支持 View Transitions API 的浏览器上仍能正常工作
- 提供简单的 API 供用户调用
使用方法
安装
npm install theme-switcher使用
- 导入 ThemeSwitcher 类：
import { ThemeSwitcher } from "theme-switcher";- 创建 ThemeSwitcher 实例：
const themeSwitcher = new ThemeSwitcher();- 切换主题：
// 无参数切换
themeSwitcher.toggleTheme();
// 或者传入鼠标事件以实现从点击位置开始的动画效果
document.getElementById("themeToggle").addEventListener("click", (e) => {
themeSwitcher.toggleTheme(e);
});- 检查当前主题：
if (themeSwitcher.isDark()) {
console.log("当前是深色主题");
} else {
console.log("当前是浅色主题");
}- 手动设置主题：
themeSwitcher.setTheme(true); // 设置为深色主题
themeSwitcher.setTheme(false); // 设置为浅色主题配置选项
ThemeSwitcher 构造函数接受一个可选的配置对象。以下是可用的配置选项：
| 可用选项 | 选项类型 | 默认值 | 描述 |
|---|---|---|---|
| duration | number | 300 | 主题切换动画的持续时间（毫秒） |
| easing | "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | "ease-in-out" | 动画的缓动函数 |
| darkClass | string | "dark" | 深色主题的 CSS 类名 |
| lightClass | string | "light" | 浅色主题的 CSS 类名 |
| storageKey | string | "theme-preference" | 用于本地存储主题偏好的键名 |
| darkBgColor | string | "#1a1a1a" | 深色主题的背景颜色 |
| lightBgColor | string | "#ffffff" | 浅色主题的背景颜色 |
| darkTextColor | string | "#ffffff" | 深色主题的文本颜色 |
| lightTextColor | string | "#1a1a1a" | 浅色主题的文本颜色 |
| customHtmlStyles | boolean | false | 是否使用自定义的 HTML 样式 |
| transition | "circle" | "fade" | "colorFade" | "curtain" | "circle" | 动画效果 |
示例：
const themeSwitcher = new ThemeSwitcher({
duration: 500,
easing: "ease",
darkClass: "theme-dark",
lightClass: "theme-light",
storageKey: "my-app-theme",
darkBgColor: "#222",
lightBgColor: "#f0f0f0",
darkTextColor: "#eee",
lightTextColor: "#333",
customHtmlStyles: true,
});高级用法
自定义 HTML 样式
如果你想完全控制主题的样式，可以将 customHtmlStyles 选项设置为 true，然后在你的 CSS 中定义主题样式：
html.theme-dark {
--bg-color: #222;
--text-color: #eee;
}
html.theme-light {
--bg-color: #f0f0f0;
--text-color: #333;
}
body {
background-color: var(--bg-color);
color: var(--text-color);
}使用 View Transitions API
ThemeSwitcher 会自动检测并使用 View Transitions API（如果浏览器支持）来实现更平滑的主题切换效果。如果浏览器不支持该 API，它会回退到简单的类切换。
响应系统主题变化
ThemeSwitcher 在初始化时会检查系统主题偏好。如果你想在运行时响应系统主题的变化，可以这样做：
const themeSwitcher = new ThemeSwitcher();
window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) => {
themeSwitcher.setTheme(e.matches);
});注意事项
- ThemeSwitcher 会自动将必要的样式添加到文档的
<head>中。 - ThemeSwitcher 会自动检测用户的系统主题偏好和之前保存的主题设置。
- 确保在你的 HTML 文件中有一个用于触发主题切换的元素，并为其添加点击事件监听器。
浏览器兼容性
ThemeSwitcher 可以在所有现代浏览器中工作。然而，平滑的过渡动画效果依赖于 View Transitions API，该 API 目前并非所有浏览器都支持。在不支持的浏览器中，主题切换会立即生效，没有过渡动画。
通过以上步骤，你可以轻松地在你的项目中集成 ThemeSwitcher，实现平滑的主题切换功能。