Granim.js v1.1.1 API 详解：打造流畅渐变动画

Granim.js v1.1.1 API 详解：打造流畅渐变动画

granim.js Create fluid and interactive gradient animations with this small javascript library. 项目地址: https://gitcode.com/gh_mirrors/gr/granim.js

Granim.js 是一个轻量级的 JavaScript 库，专门用于创建流畅且交互式的渐变动画效果。本文将深入解析 Granim.js v1.1.1 版本的 API，帮助开发者更好地理解和使用这个强大的动画工具。

核心概念

Granim.js 的核心功能是通过 Canvas 元素实现平滑的渐变动画过渡。它支持多种渐变方向、状态切换、图像混合等高级功能，非常适合用于网站背景、UI 元素等场景。

基础配置选项

必需参数

• element：指定用于渲染渐变的 Canvas 元素，可以是 CSS 选择器字符串或直接传入 HTMLCanvasElement 对象
• opacity：数组形式定义每个颜色点的透明度，如 [1, 0.5] 表示两个颜色点分别完全不透明和半透明
• states：定义动画状态的对象，包含渐变颜色组和过渡参数

可选参数

• name：为实例命名，用于设置基于亮度变化的 CSS 类名
• direction：渐变方向，可选值：
  • 'diagonal'（对角线，默认）
  • 'left-right'（左右）
  • 'top-bottom'（上下）
  • 'radial'（径向）
• isPausedWhenNotInView：当元素不在视口中时是否暂停动画
• stateTransitionSpeed：状态切换时的过渡速度（毫秒）

状态配置详解

每个状态(state)可以定义自己的渐变效果：

states: {
    "default-state": {
        gradients: [
            ['#FF9966', '#FF5E62'], // 第一组渐变
            ['#00F260', '#0575E6']  // 第二组渐变
        ],
        transitionSpeed: 5000, // 渐变间过渡时间
        loop: true // 是否循环
    },
    "dark-mode": {
        gradients: [
            ['#0F2027', '#203A43', '#2C5364'] // 三色渐变
        ],
        transitionSpeed: 8000
    }
}

状态配置要点

1. 渐变颜色组可以包含2个或更多颜色
2. 所有状态的渐变颜色数量应保持一致
3. 每个状态可以独立设置过渡速度和循环属性

图像混合功能 (v1.1.0新增)

Granim.js 支持将渐变与图像混合，创建更丰富的视觉效果：

image: {
    source: 'path/to/image.jpg', // 必需
    position: ['center', 'top'], // 图像位置
    stretchMode: ['stretch', 'stretch-if-smaller'], // 拉伸模式
    blendingMode: 'multiply' // 混合模式
}

图像配置详解

• position：控制图像在 Canvas 中的位置，x/y 轴可分别设置
• stretchMode：图像拉伸方式，可选：
  • 'stretch'：强制拉伸
  • 'stretch-if-smaller'：仅当图像小于 Canvas 时拉伸
  • 'stretch-if-bigger'：仅当图像大于 Canvas 时拉伸
• blendingMode：支持所有 Canvas 混合模式，如 'multiply'、'screen' 等

事件与回调

Granim.js 提供了完整的事件系统：

回调函数

• onStart：动画开始时触发
• onGradientChange：渐变切换时触发
• onEnd：动画结束时触发

自定义事件

可以通过标准 DOM 事件监听 Granim 的生命周期：

canvasElement.addEventListener('granim:start', function(event) {
    console.log('动画开始', event);
});

支持的事件类型包括：

• granim:start
• granim:end
• granim:loop
• granim:gradientChange

控制方法

Granim 实例提供了多种控制方法：

const granim = new Granim({...});

// 播放动画
granim.play();

// 暂停动画
granim.pause();

// 清除渐变
granim.clear();

// 切换状态
granim.changeState('dark-mode');

// 改变方向
granim.changeDirection('radial');

// 改变混合模式
granim.changeBlendingMode('overlay');

// 销毁实例
granim.destroy();

最佳实践

1. 响应式设计：结合 stretchMode 确保在不同屏幕尺寸下都能正常显示
2. 性能优化：对于复杂页面，设置 isPausedWhenNotInView 为 true
3. 用户体验：使用状态切换创建交互效果，如暗黑模式切换
4. 创意组合：尝试不同的混合模式创造独特视觉效果

总结

Granim.js v1.1.1 提供了强大的渐变动画功能，通过灵活的配置选项和丰富的控制方法，开发者可以轻松创建专业级的渐变效果。无论是简单的背景动画还是复杂的交互式UI，Granim.js 都能胜任。掌握本文介绍的 API 细节，你将能够充分发挥这个库的潜力，为你的项目添加令人印象深刻的视觉元素。

granim.js Create fluid and interactive gradient animations with this small javascript library. 项目地址: https://gitcode.com/gh_mirrors/gr/granim.js