Theme Transition Animation

一个基于 View Transition API 的圆形扩散主题切换动画库。

特性

• 🎯 圆形扩散动画: 从点击位置开始的平滑圆形扩散效果
• 🚀 基于 View Transition API: 使用现代浏览器的原生动画API
• 📱 响应式: 自动适配不同屏幕尺寸
• ♿ 无障碍友好: 支持 prefers-reduced-motion 设置
• 🔧 高度可配置: 支持自定义动画时长、缓动函数等
• 📦 轻量级: 零依赖，体积小巧
• 🌐 浏览器兼容: 自动降级处理不支持的浏览器

安装

npm install theme-transition-animation

基本使用

快速开始

import { createThemeToggle } from 'theme-transition-animation';

// 创建主题切换函数
const toggleTheme = createThemeToggle(() => {
  // 你的主题切换逻辑
  document.documentElement.setAttribute('data-theme', 
    document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark'
  );
});

// 在按钮点击时调用
button.addEventListener('click', (event) => {
  toggleTheme(event);
});

使用类实例

import { CircularTransition } from 'theme-transition-animation';

const transition = new CircularTransition({
  duration: 0.8,
  easing: 'ease-out'
});

// 执行动画
transition.transition(() => {
  // 你的主题切换逻辑
  toggleThemeState();
}, event);

API 文档

createThemeToggle(callback, options?)

创建一个主题切换函数。

参数:

• callback: () => void - 主题切换回调函数
• options?: CircularTransitionOptions - 可选的配置选项

返回:

• (event?: ThemeToggleEvent) => Promise<void> - 主题切换函数

CircularTransition

主要的动画类。

构造函数

new CircularTransition(options?: CircularTransitionOptions)

方法

• transition(callback, event?) - 执行动画过渡
• updateOptions(options) - 更新配置
• getOptions() - 获取当前配置
• getBrowserSupport() - 获取浏览器支持信息
• isTransitionInProgress() - 检查是否正在动画中
• destroy() - 销毁实例，清理资源

配置选项 CircularTransitionOptions

interface CircularTransitionOptions {
  duration?: number;           // 动画持续时间（秒），默认 0.6
  easing?: string;            // 缓动函数，默认 'ease-in-out'
  fallback?: boolean;         // 不支持时是否降级，默认 true
  respectReducedMotion?: boolean; // 是否尊重减少动画偏好，默认 true
}

事件对象 ThemeToggleEvent

interface ThemeToggleEvent {
  clientX?: number; // 鼠标X坐标
  clientY?: number; // 鼠标Y坐标
}

高级用法

自定义动画参数

const transition = new CircularTransition({
  duration: 1.0,
  easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
  respectReducedMotion: true
});

检查浏览器支持

import { checkBrowserSupport } from 'theme-transition-animation';

const support = checkBrowserSupport();
console.log('支持 View Transition:', support.supportsViewTransition);

手动设置点击位置

// 从特定位置开始动画
toggleTheme({ clientX: 100, clientY: 200 });

CSS 要求

这个库会自动注入必要的CSS样式，但你需要确保你的主题样式正确设置了 view-transition-name：

:root {
  view-transition-name: root;
}

浏览器兼容性

• 支持 View Transition API: Chrome 111+, Edge 111+
• 降级支持: 所有现代浏览器（直接执行回调，无动画）

示例

查看 examples 目录获取完整的使用示例。

许可证

MIT License