Granim.js v2.0.0 API 详解：打造炫酷渐变动画的完整指南

Granim.js v2.0.0 API 详解：打造炫酷渐变动画的完整指南

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

什么是 Granim.js？

Granim.js 是一个轻量级的 JavaScript 库，专门用于创建流畅且交互式的渐变动画效果。它基于 HTML5 Canvas 实现，能够为网页带来生动的视觉体验。通过简单的 API 配置，开发者可以轻松实现复杂的渐变过渡效果，甚至结合图片实现混合模式动画。

核心配置参数

基础配置

{
    element: '#granim-canvas',  // 必需参数，指定canvas元素
    name: 'granim',            // 类名前缀，用于暗/亮模式切换
    direction: 'diagonal',     // 渐变方向
    isPausedWhenNotInView: false, // 不在视窗时暂停动画
    states: { /* 状态配置 */ }
}

渐变方向选项

Granim.js 提供了多种预设的渐变方向：

• 'diagonal' - 对角线渐变（默认）
• 'left-right' - 从左到右
• 'top-bottom' - 从上到下
• 'radial' - 径向渐变
• 'custom' - 自定义方向（需配合customDirection参数）

自定义方向示例：

customDirection: {
    x0: '10%',  // 起点x坐标
    y0: '25px', // 起点y坐标
    x1: '30%',  // 终点x坐标
    y1: '322px' // 终点y坐标
}

状态(states)配置详解

状态是 Granim.js 的核心概念，每个状态可以包含一组渐变配置：

states: {
    "default-state": {
        gradients: [
            ['#834d9b', '#d04ed6'],
            ['#1CD8D2', '#93EDC7']
        ],
        transitionSpeed: 5000, // 渐变过渡时间(ms)
        loop: true           // 是否循环
    }
}

渐变颜色配置的两种方式

1. 简单方式 - 均匀分布颜色：

gradients: [
    ['#FF9966', '#FF5E62'],
    ['#00FF78', '#2E8BFF']
]

2. 精确控制 - 指定颜色位置：

gradients: [
    [
        { color: 'rgba(255,153,102,.33)', pos: 0.5 },
        { color: '#ff5e62', pos: 1 }
    ]
]

图片混合功能

Granim.js 支持将渐变与图片结合，实现更丰富的视觉效果：

image: {
    source: 'img/bg.jpg',  // 图片路径
    position: ['center', 'bottom'], // 图片位置
    stretchMode: ['stretch', 'stretch-if-bigger'], // 拉伸模式
    blendingMode: 'multiply' // 混合模式
}

图片位置选项

• x轴：'left'、'center'、'right'
• y轴：'top'、'center'、'bottom'

拉伸模式选项

• 'none' - 不拉伸
• 'stretch' - 始终拉伸
• 'stretch-if-smaller' - 小于画布时拉伸
• 'stretch-if-bigger' - 大于画布时拉伸

事件与回调

Granim.js 提供了丰富的事件系统：

回调函数

{
    onStart: function() { /* 动画开始时触发 */ },
    onGradientChange: function(colorDetails) { /* 渐变变化时触发 */ },
    onEnd: function() { /* 动画结束时触发 */ }
}

自定义事件监听

// 原生JS
canvas.addEventListener('granim:start', function(event) {
    console.log('动画开始', event);
});

// jQuery
$('#granim-canvas').on('granim:gradientChange', 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-state');

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

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

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

最佳实践

1. 响应式设计：结合 stretchMode 确保在不同屏幕尺寸下表现一致
2. 性能优化：对于复杂动画，设置 isPausedWhenNotInView 为 true
3. 用户体验：使用状态切换创建交互式效果
4. 色彩搭配：确保渐变颜色过渡自然，避免突兀变化

完整示例

const granim = new Granim({
    element: '#animated-gradient',
    name: 'basic-gradient',
    direction: 'diagonal',
    states: {
        "default-state": {
            gradients: [
                ['#FF9966', '#FF5E62'],
                ['#00F260', '#0575E6'],
                ['#4776E6', '#8E54E9']
            ],
            transitionSpeed: 3000,
            loop: true
        },
        "dark-state": {
            gradients: [
                ['#0F2027', '#203A43'],
                ['#2C5364', '#0F2027']
            ],
            transitionSpeed: 5000
        }
    },
    onStart: () => console.log('动画开始'),
    onGradientChange: (details) => {
        console.log('当前颜色:', details.colors);
    }
});

// 点击切换状态
document.querySelector('#toggle-btn').addEventListener('click', () => {
    granim.changeState(granim.state === 'default-state' ? 'dark-state' : 'default-state');
});

通过掌握这些 API 和技巧，你可以轻松为网站添加专业级的渐变动画效果，提升用户体验和视觉吸引力。

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