sakura-fall | Canvas 飘落装饰库
简述
@night-tea/sakura-fall 是一个基于 Canvas 的轻量飘落装饰库。它适合用在博客、活动页、节日页面这类需要一点氛围感的地方，比如樱花、雪花、落叶、雨滴这些不会影响主要内容，但能让页面更有季节感的小装饰。
这个库本身不绑定具体框架，原生项目可以直接调用 TypeScript API，Vue 项目也可以使用封装好的组件。默认内置了 12 张透明水彩素材，并且支持通过 month 按月份自动切换。
- GitHub 地址：hahaxiaowai/sakura-fall
- 说明文档：sakura-fall 使用文档
为什么做
之前做博客主题和季节装饰时，经常会遇到类似需求：想在页面上加一点飘落效果，但又不希望为了一个装饰效果引入太重的插件，或者只能在某个特定框架里使用。
所以这次把飘落效果单独拆成一个小库，核心目标比较明确：
- 只负责飘落装饰，不和业务页面耦合。
- 基于 Canvas 绘制，避免创建大量 DOM 节点。
- 原生 API 可以在任意前端项目中使用。
- Vue 项目可以直接使用组件，减少重复封装。
- 内置常用季节素材，同时保留自定义图片能力。
功能介绍
月份素材
库里内置了 12 张透明水彩素材，可以按月份自动切换：
| 月份 | 素材名 | 元素 |
|---|---|---|
| 1 | 01-snow-crystal | 雪晶 |
| 2 | 02-plum-blossom | 梅花 |
| 3 | 03-sakura | 樱花 |
| 4 | 04-willow-leaf | 柳叶 |
| 5 | 05-dandelion | 蒲公英 |
| 6 | 06-raindrop | 雨滴 |
| 7 | 07-bubble | 气泡 |
| 8 | 08-lotus | 荷花 |
| 9 | 09-maple-leaf | 枫叶 |
| 10 | 10-ginkgo-leaf | 银杏 |
| 11 | 11-fallen-leaf | 落叶 |
| 12 | 12-snowflake | 雪花 |
如果 image 传入 month，库会根据当前月份自动选择对应素材。也可以直接指定某一张内置素材，比如 03-sakura，或者传入自定义图片 URL。
控制效果
目前常用配置主要有：
| 参数 | 说明 |
|---|---|
image | 飘落图片，支持 month、内置素材名或自定义 URL |
count | 粒子数量 |
size | 粒子基础尺寸 |
autoStart | 图片加载完成后是否自动开始 |
container | 自动创建 canvas 时的挂载容器 |
canvas | 复用已有 canvas |
实例上提供了 start、stop、setImage、setCount、destroy 等方法，可以在页面切换、主题切换、组件销毁时主动控制效果。
使用方式
安装
pnpm add @night-tea/sakura-fall如果在 Vue 项目中使用组件，需要项目中已经安装 vue。
原生用法
import { createSakuraFall } from "@night-tea/sakura-fall";
const fall = createSakuraFall({
image: "month",
count: 15,
size: 30,
});
fall.stop();
fall.start();
await fall.setImage("03-sakura");
fall.setCount(20);
fall.destroy();默认情况下，库会在 document.body 中创建一个全屏固定定位的 canvas，并且设置 pointer-events: none，避免影响页面原有交互。
如果想把效果限制在某个容器中，也可以传入 container：
createSakuraFall({
container: "#app",
image: "11-fallen-leaf",
});Vue 用法
Vue 项目可以直接使用组件：
<script setup lang="ts">
import { SakuraFall } from "@night-tea/sakura-fall/vue";
</script>
<template>
<SakuraFall image="month" :count="15" :size="30" />
</template>组件内部会在挂载时创建实例，在卸载前自动调用 destroy，所以一般页面中直接使用即可。
实现思路
整体实现并不复杂，核心是一个固定定位的 canvas 和一组粒子状态。
每个粒子会记录自己的位置、速度、旋转角度、旋转速度和缩放比例。绘制时通过 requestAnimationFrame 不断清空画布、绘制图片、更新粒子位置。当粒子飘出屏幕后，会重新回到顶部继续参与下一轮动画。
图片加载单独封装成 Promise，实例会暴露 ready，方便外部在图片加载完成后做后续处理。窗口尺寸变化时会重新设置 canvas 宽高，销毁时会取消动画帧、移除 resize 监听，并清理自动创建的 canvas。
这种方式的好处是使用简单，页面上也不会因为装饰效果出现大量额外 DOM。对于博客这种内容型页面来说，只要控制好粒子数量，就能兼顾氛围和性能。
后续计划
目前版本已经能覆盖基础使用，后面可以继续补一些更细的配置：
- 支持配置飘落速度和方向。
- 增加更多节日或季节素材。
- 提供更细的层级、透明度和区域控制。
- 补充 React 等其他框架的组件封装。
- 在文档中增加更多实际页面接入示例。
如果只是想给页面加一点不打扰阅读的季节装饰，sakura-fall 会是一个比较轻量的选择。