更新记录

v1.0.1（2026-09-08）

更新部分机型动画渲染引擎问题

v1.0.0（2026-09-07）

1.0.0（2026-09-07）

首次发布

前端组件（5 个，easycom 自动注入）​

• sw-bullet-screen：LED 点阵弹幕，支持纯色/LED 点阵背景、滚动/闪烁/霓虹等多种特效
• sw-wish-canvas：祝福摆台，WebGL(Three.js) + Canvas 2D 双路径渲染，12 套模板（生日/节日/纪念日/心情 4 分类），16 种文字特效
• sw-template-list / sw-demo-basic / sw-demo-wish：模板列表示例与演示页

uniCloud 云函数（3 个示例）​

• sw-content-guard：微信内容安全检测（加密云函数，msgSecCheck 接入）
• sw-favorite-sync：收藏云端同步（含分页）
• sw-template-list：云端模板配置下发

数据库

• sw_favorites / sw_user 两张表 Schema + db_init.json

跨端：微信小程序为主，H5/App 基础兼容（3D 自动回退 2D）

平台兼容性

云端兼容性

云函数类插件通用教程

使用云函数类插件的前提是：使用HBuilderX 2.9+

星愿弹幕 · 祝福摆台模板（matthew-bullet-uniapp）

一套开箱即用的「LED 弹幕 + 3D 祝福摆台」uniapp 商业模板，基于 uniapp + Vue3 + uniCloud 构建。内置 12 套精调祝福摆台模板（生日 / 节日 / 纪念日 / 心情）、16 种霓虹发光文字特效、3 个示例云函数与 2 个数据库 Schema，覆盖祝福类、节庆类、纪念类小程序的主流场景，导入工程即可运行，适合快速搭建「弹幕祝福」「照片摆台」「节日贺卡」类产品。

一、功能描述

1. 祝福摆台组件 sw-wish-canvas（核心）

WebGL（Three.js 裁剪版）+ Canvas 2D 双路径渲染：小程序端启用 WebGL 3D 主体（立方体照片台 / 情侣照片心形环 / 水晶相框摆台等），WebGL 不可用时自动回退纯 2D 绘制，全端可用。

内置 12 套摆台模板，通过 template-id 一键切换：

能力清单：

• 照片驱动：传入照片路径数组即可替换模板内置示例图，支持本地路径 / 代码包路径 / 网络图片 / 临时文件；
• 文字特效 16 种：metallic-gold 鎏金立体字、gradient-rainbow 彩虹渐变、glitter 鎏光、neon-blue/pink/gold/green/purple 霓虹发光系列、ice-blue 冰蓝、lava-red 熔岩、soft-pink 柔粉、outline-white 白描边、shadow-black 黑投影等；
• 专属氛围背景：星空 / 烟花 / 灯笼 / 龙舟江面 / 中秋夜色 / 国庆红 / 深奢婚庆暗金等 20+ 种 canvas 绘制背景，零图片资源、不增加包体积；
• 导出与分享：支持 generateImage() 合成当前帧竖版 1080×1440 高清图，配合 uni.saveImageToPhotosAlbum 或微信 showShareImageMenu 完成保存 / 分享；
• 动效参数可调：旋转速度、文字速度、环半径、字号、颜色、文字布局（底部 / 环绕 / 堆叠 / 跑马灯）均为 props。

2. 滚动弹幕组件 sw-bullet-screen

LED 点阵风格滚动弹幕：黑色底 + 淡色网格 + 格心微光，模拟真实 LED 屏。支持 led / solid 两种背景、7 种播放特效（滚动 / 双向 / 闪烁 / 镜像 / 弹跳 / 霓虹 / 渐变），字号、速度、颜色可配，支持全屏模式。

3. uniCloud 云端配套（3 云函数 + 2 Schema）

数据库 Schema：sw_favorites（收藏表）、sw_user（用户扩展信息表）。

4. 演示页（安装即用）

• uni_modules/matthew-bullet-uniapp/pages/sw-demo-basic/sw-demo-basic：弹幕演示（背景切换 / 特效切换 / 全屏播放）；
• uni_modules/matthew-bullet-uniapp/pages/sw-demo-wish/sw-demo-wish：摆台演示（12 套模板轮播 / 本地照片临时替换 / 一键导出图片）。

安装时通过 pages_init.json 自动注册，无需手改 pages.json。

二、环境要求

• HBuilderX 4.71 及以上（需支持 uni_modules 与 Vue3）；
• uniapp Vue 3 工程（Vue 2 工程请勿购买）；
• 云端部分需开通 uniCloud 服务空间（阿里云 / 支付宝云 / 腾讯云均提供部署目录）；不开通云端也可正常使用全部前端组件（模板列表自动走内置默认数据）。

三、安装步骤

方式 A：插件市场一键导入（推荐）

1. 打开 HBuilderX，新建或打开你的 Vue3 uniapp 工程；
2. 点击本插件页面右上角「使用 HBuilderX 导入插件」，浏览器会拉起 HBuilderX；
3. 在弹出的导入窗口中选择你的目标工程，点击「确定」；
4. 若提示「pages.json 存在差异，是否合并」，选择「合并」——演示页路由会自动注册；
5. 等待依赖编译完成，运行到微信开发者工具或内置浏览器；
6. 将启动页临时设为 uni_modules/matthew-bullet-uniapp/pages/sw-demo-wish/sw-demo-wish（或在任意页面 uni.navigateTo 跳转），看到 12 套模板轮播即安装成功。

方式 B：手动拷贝

1. 下载插件 zip 包并解压；
2. 将 uni_modules/matthew-bullet-uniapp/ 整个目录拷贝到你工程的 uni_modules/ 下；
3. （可选）如需体验演示页，把 uni_modules/matthew-bullet-uniapp/pages_init.json 中的两条 page 手动合并进你工程的 pages.json；
4. 重新编译运行。组件基于 easycom 自动注册，页面模板中直接写 <sw-bullet-screen />、<sw-wish-canvas /> 即可，无需 import。

安装验证

编译后控制台应输出：

[sw-wish-canvas] draw/api.js version: 2026-09-07-11

且无 module is not defined、组件未注册等报错。

四、快速上手

1. 祝福摆台

<template>
  <view style="width: 100%; height: 540rpx;">
    <sw-wish-canvas
      :effect="'cube'"
      :image-paths="photoList"
      :text="'生日快乐 · 万事顺遂'"
      :text-size="30"
      :text-color="'#7FD4FF'"
      :bg-color="'#0A1430'"
      text-effect="neon-blue"
      text-layout="bottom"
      :photo-count="6"
      template-id="birthday-1"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue'
const photoList = ref([
  '/static/model/model-g1.jpg',
  '/static/model/model-g2.jpg'
])
</script>

常用 Props：

ref 方法： start() 开始渲染、stop() 暂停、resize() 容器尺寸变化后重新测量、generateImage() 导出当前帧竖版大图（1080×1440，返回临时文件路径）。

2. 滚动弹幕

<template>
  <view class="stage">
    <sw-bullet-screen
      :text="'生日快乐'"
      :font-size="40"
      :color="'#FF2626'"
      :bg-style="'led'"
      :speed="8"
      :effect="'scroll'"
    />
  </view>
</template>

常用 Props：

3. 云函数调用示例

// 模板列表
const { result } = await uniCloud.callFunction({
  name: 'sw-template-list',
  data: { category: 'birthday' }
})

// 收藏同步
await uniCloud.callFunction({
  name: 'sw-favorite-sync',
  data: { action: 'add', uid: 'user-001', item: { templateId: 'birthday-1' } }
})

// 文案内容安全过滤
await uniCloud.callFunction({
  name: 'sw-content-guard',
  data: { text: '用户输入的祝福语', uid: 'user-001' }
})

五、云端部署（可选）

1. 在工程根目录的 uniCloud-aliyun（或 uniCloud-alipay / uniCloud-tcb）目录右键 →「关联云服务空间」；
2. 右键 →「上传并部署所有云函数、公共模块及 actions」；
3. 右键 →「初始化云数据库」，自动创建 sw_favorites / sw_user 两张表。

说明：插件包内提供 uniCloud-aliyun/、uniCloud-alipay/、uniCloud-tcb/ 三套部署目录，按你绑定的服务空间类型上传对应目录即可。不部署云端时前端组件可完整独立使用（模板列表走内置默认数据），云端部分仅用于模板远程运营、收藏同步与内容安全示例。

六、3D 依赖与包体积

components/sw-wish-canvas/draw/ 下有两个 3D 相关文件，必须成对存在：

• 二者仅在小程序端被打包，H5 / App 端编译时不进包；
• 若主包体积吃紧，可删除这两个文件并去掉 sw-wish-canvas.vue 中对应的 require，组件自动回退 Canvas 2D 兜底渲染（功能完整，3D 观感有差异）；
• 不要把这两个文件移入 vendor/ 子目录：uniapp 编译器编译微信小程序时会剔除 vendor/ 目录，导致运行时 module is not defined。

七、跨端兼容说明

以微信小程序为主要适配与真机验证端；H5 / App 端 3D 特效自动回退 Canvas 2D。

八、常见问题

Q1：安装后提示找不到 sw-wish-canvas 组件？ 确认使用 HBuilderX 4.71+ 且工程为 Vue3；检查 pages.json 中 easycom 配置 "autoscan": true。

Q2：H5 端只看到背景、没有 3D 主体？ H5 端 WebGL 不可用时自动回退 Canvas 2D 渲染，属预期行为。

Q3：微信开发者工具中 3D 摆台不动或被回退为 2D？ 确认无 module is not defined 报错（若有，检查是否误将 draw/ 下文件移入 vendor/ 子目录）；开发者工具需开启 WebGL。真机表现以实机为准，已真机验证 3D 立方体 / 相框贴图正常。

Q4：替换照片后模板仍显示示例图？ image-paths 传入你自己的照片路径数组即可；photo-count 建议与照片数量一致，心形环等特效依赖该值布局。

Q5：不接 uniCloud 能用吗？ 能。全部前端组件零依赖云端，模板列表自动使用内置默认数据；云函数是可选增强。

九、更新日志

1.0.0（2026-09-07）

• 首次发布
• 5 个前端组件（easycom 自动注入）
• 2 个演示页（pages_init.json 自动注册）
• 12 套祝福摆台模板（生日 4 / 节日 4 / 纪念日 2 / 心情 2）与 16 种文字特效
• 3 个 uniCloud 示例云函数（模板下发 / 收藏同步 / 内容安全过滤）
• 2 个数据库 Schema（sw_favorites / sw_user）