# uniapp-lantern-release

**Repository Path**: isixe/uniapp-lantern-release

## Basic Information

- **Project Name**: uniapp-lantern-release
- **Description**: uniapp放花灯效果组件
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-22
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# uniapp-lantern-release

一个基于 UniApp 的 放花灯 组件，适用于 H5，其他平台暂未测试。组件通过 requestAnimationFrame 实现花灯从底部向上飘动，并叠加左右摇摆动画，适合节日、活动氛围展示。

## 预览

<img src="https://gitee.com/isixe/uniapp-lantern-release/raw/master/docs/prevew.gif" width="200"/>

## 安装使用

1. 下载项目并引入组件
2. 在页面中引入 `lantern-release` 组件
3. 按需修改样式和配置参数
4. 通过 ref 调用动画控制方法

## 示例代码

```vue
<template>
  <button @click="handleAddLight">放花灯</button>

  <LanternRelease imageUrl="/static/lantern-release/lantern.png" :speed="3" :swing="20" :width="'200px'"
    :height="'220px'" :startPosition="-220" ref="lanternRef" />
</template>

<script setup>
import { ref } from "vue";
import LanternRelease from "../../components/lantern-release/lantern-release.vue";

const lanternRef = ref();

function handleAddLight() {
  lanternRef.value?.startAnimation();
}
</script>

<style scoped></style>
```

## API
### 参数

| 参数名             | 类型                     | 默认值         | 说明                                                     |
| ------------------ | ------------------------ | -------------- | -------------------------------------------------------- |
| imageUrl           | `string`                 | `""`           | 花灯图片地址                                             |
| speed              | `number`                 | `5`            | 上升速度（数值越大越快，基于 60fps 计算）                |
| swingAmplitude     | `number`                 | `10`           | 摆动角度幅度（单位：deg）                                |
| swingSpeed         | `number`                 | `500`          | 摆动周期速度（值越小，摆动越快）                         |
| startPosition      | `number`                 | `-100`         | 初始底部位置（px，负值表示屏幕外），需要大于花灯图片高度 |
| endPosition        | `number \| "screen-top"` | `"screen-top"` | 终止位置，`screen-top` 表示完全离开屏幕                  |
| width              | `string`                 | `"80px"`       | 花灯宽度                                                 |
| height             | `string`                 | `"100px"`      | 花灯高度                                                 |
| horizontalPosition | `string \| "center"`     | `"center"`     | 水平位置，如 `"20%"`、`"100px"`                          |
| autoStart          | `boolean`                | `false`        | 是否在组件挂载后自动开始动画                             |
| delay              | `number`                 | `0`            | 启动延迟时间（毫秒）                                     |

### 事件

| 事件名         | 说明                   |
| -------------- | ---------------------- |
| animationStart | 动画开始时触发         |
| animationEnd   | 花灯到达终点位置时触发 |
| animationReset | 调用重置方法时触发     |

### 实例方法

通过 ref 可调用以下方法控制花灯动画

| 方法名           | 参数 | 返回值 | 说明                             |
| ---------------- | ---- | ------ | -------------------------------- |
| startAnimation   | —    | `void` | 启动动画，重置位置并开始向上飘动 |
| stopAnimation    | —    | `void` | 立即停止动画，保持当前花灯位置   |
| resetAnimation   | —    | `void` | 重置花灯到初始位置，不播放动画   |
| restartAnimation | —    | `void` | 重置并重新启动动画               |


## 许可协议

MIT License，请查看项目根目录下的 LICENSE 文件。