red-packet-rain-sdk

v1.0.2

Published

2 months ago

一个用于在网页上创建红包雨效果的 JavaScript 库

0High
0Medium
0Low

mingle998

red-packet rain animation hongbao 红包雨前端组件

RedPacketRain SDK

✨ 特性

🎯 多种模块格式支持：支持 UMD、CommonJS、ES Module
🎨 高度可定制：丰富的配置选项，满足各种场景需求
🚀 轻量级：压缩后仅 5.4KB（包含 CSS）
💫 流畅动画：基于 CSS3 transform 和 transition
📱 响应式：自动适配不同屏幕尺寸
🎮 交互丰富：支持点击、销毁、倒计时等功能
🔧 零依赖：不依赖任何第三方库
📦 开箱即用：CSS 自动注入，无需单独引入样式文件

📦 安装

方式 1：通过 npm

npm install red-packet-rain-sdk

方式 2：通过 yarn

yarn add red-packet-rain-sdk

方式 3：通过 CDN

<!-- CSS 已自动注入到 JS 中，只需引入 JS 文件即可 -->
<script src="https://unpkg.com/red-packet-rain-sdk/dist/red-packet-rain.umd.min.js"></script>

🚀 快速开始

在浏览器中使用（UMD）

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>红包雨示例</title>
</head>
<body>
    <div id="rain-container"></div>
    <button id="start-btn">开始红包雨</button>

    <!-- CSS 已自动注入，只需引入 JS 文件 -->
    <script src="https://unpkg.com/red-packet-rain-sdk/dist/red-packet-rain.umd.min.js"></script>
    <script>
        const btn = document.getElementById('start-btn');
        const container = document.getElementById('rain-container');
        
        btn.addEventListener('click', () => {
            const redPacketRain = new RedPacketRain(container, {
                fallSpeed: 5000,
                packetDensity: 8,
                redPacketSupportEvent: true,
                packetImages: [
                    { src: 'https://pic1.imgdb.cn/item/6903728b3203f7be00b5844a.png', width: 50, height: 60 }
                ],
                onPacketClick: (packet) => {
                    console.log('红包被点击了！');
                }
            });
            
            redPacketRain.start();
        });
    </script>
</body>
</html>

在现代前端项目中使用（ES Module）

import RedPacketRain from 'red-packet-rain-sdk';
// CSS 已自动注入，无需单独引入

const redPacketRain = new RedPacketRain(
    document.querySelector('#rain-container'),
    {
        fallSpeed: 5000,
        animationActiveDuration: 20000,
        packetDensity: 8,
        redPacketSupportEvent: true,
        packetImages: [
            { src: 'https://pic1.imgdb.cn/item/6903728b3203f7be00b5844a.png', width: 50, height: 60 }
        ],
        onPacketClick: (packet) => {
            console.log('红包被点击了！');
        }
    }
);

redPacketRain.start();

⚙️ 配置参数

| 参数名称 | 数据类型 | 默认值 | 描述 | |----------|----------|--------|------| | packetCount | Number | 1000 | 红包总数量 | | fallSpeed | Number | 2000 | 红包下落速度（毫秒） | | animationActiveDuration | Number | 20000 | 红包雨活跃时长（毫秒） | | packetDensity | Number | 3 | 红包密集度（每秒生成数量），最大值 50 | | packetImages | Array | [{ src: 'https://pic1.imgdb.cn/item/6903728b3203f7be00b5844a.png', width: 40, height: 50 }] | 红包图片配置数组 | | onPacketClick | Function | null | 点击红包时的回调函数 | | getDestroyedCountHook | Function | null | 红包销毁时的钩子函数 | | onStopCallback | Function | null | 红包雨结束时的回调函数 | | destroyOnClick | Boolean | false | 点击后是否销毁红包 | | redPacketSupportEvent | Boolean | false | 是否支持红包点击事件 | | enableCountdown | Boolean | false | 是否启用倒计时 | | allowRotation | Boolean | false | 是否允许红包旋转 | | rotationRange | Number | 30 | 旋转角度范围（度） | | initialTopPosition | Number | -60 | 红包初始位置 | | boundingBottomPosition | Number | 0 | 红包与底部的边界 | | randomFallSpeed | Boolean | false | 是否随机下落速度 | | fallSpeedVariance | Number | 0.3 | 速度变化范围（0-1） | | horizontalOffset | Number | 0 | 横向偏移范围（像素） |

配置示例

const options = {
    // 基础配置
    fallSpeed: 5000,                      // 下落时间5秒
    animationActiveDuration: 20000,       // 红包雨持续20秒
    packetDensity: 8,                     // 每秒生成8个红包
    
    // 视觉效果
    allowRotation: true,                  // 启用旋转
    rotationRange: 80,                    // 旋转角度±40度
    randomFallSpeed: true,                // 随机速度
    fallSpeedVariance: 0.3,               // 速度变化±30%
    horizontalOffset: 200,                // 水平偏移±100px
    
    // 交互配置
    redPacketSupportEvent: true,          // 支持点击事件
    destroyOnClick: false,                // 点击不销毁
    
    // 倒计时
    enableCountdown: false,               // 不显示倒计时
    
    // 红包图片
    packetImages: [
        { src: './hongbao1.png', width: 50, height: 60 },
        { src: './hongbao2.png', width: 45, height: 55 }
    ],
    
    // 回调函数
    onPacketClick: (packet) => {
        console.log('红包被点击了！', packet.src);
    },
    getDestroyedCountHook: (count) => {
        console.log('已销毁红包数量：', count);
    },
    onStopCallback: (totalDestroyed) => {
        console.log('红包雨结束！总共销毁：', totalDestroyed);
    }
};

📚 API

构造函数

new RedPacketRain(container, options)

container: HTMLElement - 红包雨的容器元素
options: Object - 配置参数对象

方法

`start()`

启动红包雨效果

redPacketRain.start();

`stop()`

停止红包雨并清除所有红包

redPacketRain.stop();

`removeCountdownElement()`

移除倒计时元素（需要开启 enableCountdown）

redPacketRain.removeCountdownElement();

React 示例

import React, { useRef, useCallback } from 'react';
import RedPacketRain from 'red-packet-rain-sdk';
// CSS 已自动注入，无需单独引入

function RedPacketRainComponent() {
    const containerRef = useRef(null);
    const rainRef = useRef(null);
    
    const startRain = useCallback(() => {
        if (rainRef.current) {
            rainRef.current.stop();
        }
        
        rainRef.current = new RedPacketRain(containerRef.current, {
            fallSpeed: 5000,
            packetDensity: 8,
            redPacketSupportEvent: true,
            packetImages: [
                { src: '/hongbao.png', width: 50, height: 60 }
            ],
            onPacketClick: (packet) => {
                console.log('红包被点击了！');
            }
        });
        
        rainRef.current.start();
    }, []);
    
    return (
        <div>
            <div ref={containerRef} className="rain-container" />
            <button onClick={startRain}>开始红包雨</button>
        </div>
    );
}

export default RedPacketRainComponent;

Vue 3 示例

Options API

<template>
  <div>
    <div ref="rainContainer" class="rain-container"></div>
    <button @click="startRain">开始红包雨</button>
  </div>
</template>

<script>
import RedPacketRain from 'red-packet-rain-sdk';
// CSS 已自动注入，无需单独引入

export default {
  data() {
    return {
      redPacketRain: null
    };
  },
  methods: {
    startRain() {
      if (this.redPacketRain) {
        this.redPacketRain.stop();
      }
      
      this.redPacketRain = new RedPacketRain(this.$refs.rainContainer, {
        fallSpeed: 5000,
        packetDensity: 8,
        redPacketSupportEvent: true,
        packetImages: [
          { src: '/hongbao.png', width: 50, height: 60 }
        ],
        onPacketClick: (packet) => {
          console.log('红包被点击了！');
        }
      });
      
      this.redPacketRain.start();
    }
  },
  beforeUnmount() {
    if (this.redPacketRain) {
      this.redPacketRain.stop();
    }
  }
};
</script>

Composition API (推荐)

<template>
  <div>
    <div ref="rainContainer" class="rain-container"></div>
    <button @click="startRain">开始红包雨</button>
  </div>
</template>

<script setup>
import { ref, onUnmounted } from 'vue'
import RedPacketRain from 'red-packet-rain-sdk'

const rainContainer = ref(null)
const redPacketRain = ref(null)

const startRain = () => {
  if (redPacketRain.value) {
    redPacketRain.value.stop()
  }
  
  redPacketRain.value = new RedPacketRain(rainContainer.value, {
    fallSpeed: 5000,
    packetDensity: 8,
    redPacketSupportEvent: true,
    packetImages: [
      { src: '/hongbao.png', width: 50, height: 60 }
    ],
    onPacketClick: (packet) => {
      console.log('红包被点击了！')
    }
  })
  
  redPacketRain.value.start()
}

onUnmounted(() => {
  if (redPacketRain.value) {
    redPacketRain.value.stop()
  }
})
</script>

🌟 浏览器支持

Chrome (最新版)
Firefox (最新版)
Safari (最新版)
Edge (最新版)
支持 ES6+ 的现代浏览器

📄 许可证

MIT License