微信小程序中使用 lucky-canvas 抽奖插件踩坑实录

前言

最近公司抽卡机要做一个营销活动在，需要加入转盘抽奖功能。在掘金搜索了一圈之后，发现了lucky-canvas这个开源的抽奖插件库，它支持大转盘、九宫格和老虎机等多种抽奖形式，而且跨平台支持做得很好。

看了官方文档和 demo 后，我满怀信心地开始了集成工作，想着"这不就是引入、配置、完事儿~"，结果却踩了好几个坑...此刻我只想说：....! 那就写一篇文章记录下这些坑，以免下次再次"中招"。

初次接触

首先想要说的是，这个库的功能的确很强大，API 设计得挺友好的，文档也比较详细。

按照官方的介绍，它已经支持了多个平台：

JavaScript/TypeScript
Vue/React
微信小程序
UniApp
Taro 等

第一步就是 npm,yarn 安装到小程序项目中：

npm install lucky-canvas --save
或
yarn add @lucky-canvas/uni@latest

然后在微信开发者工具中构建，再按照文档引入并初始化：

// pages/lottery/index.js
import { LuckyWheel } from "lucky-canvas/miniprogram/lucky-wheel";

Page({
  data: {
    width: 300,
    height: 300,
  },
  onLoad() {
    // 初始化抽奖组件
    this.initLuckyWheel();
  },
  initLuckyWheel() {
    // 获取canvas实例
    const query = wx.createSelectorQuery();
    query
      .select("#lucky-wheel")
      .fields({ node: true, size: true })
      .exec((res) => {
        // 页面内可能没有这个元素
        if (!res[0] || !res[0].node) return;
        const canvas = res[0].node;

        // 初始化抽奖组件
        this.myLucky = new LuckyWheel({
          flag: "MP-WX",
          ctx: canvas.getContext("2d"),
          dpr: wx.getSystemInfoSync().pixelRatio,
          width: this.data.width,
          height: this.data.height,
          // 其他配置...
          prizes: [
            { background: "#f8d384", fonts: [{ text: "一等奖", top: "10%" }] },
            { background: "#f9e3bb", fonts: [{ text: "二等奖", top: "10%" }] },
            { background: "#f8d384", fonts: [{ text: "三等奖", top: "10%" }] },
            { background: "#f9e3bb", fonts: [{ text: "四等奖", top: "10%" }] },
            { background: "#f8d384", fonts: [{ text: "五等奖", top: "10%" }] },
            { background: "#f9e3bb", fonts: [{ text: "六等奖", top: "10%" }] },
          ],
          buttons: [
            {
              radius: "40%",
              background: "#617df2",
              fonts: [{ text: "开始", top: "32%" }],
            },
          ],
        });
      });
  },

  // 开始抽奖按钮
  startLottery() {
    // 随机获取一个中奖索引
    const index = Math.floor(Math.random() * 6);

    // 开始旋转
    this.myLucky.play();

    // 模拟请求接口
    setTimeout(() => {
      // 停止旋转并传递中奖索引
      this.myLucky.stop(index);
    }, 2500);
  },
});

配套的 WXML 模板：

<!-- pages/lottery/index.wxml -->
<view class="lottery-container">
  <canvas
    type="2d"
    id="lucky-wheel"
    style="width: {{width}}px; height: {{height}}px"
    bindtap="startLottery"
  ></canvas>
</view>

看起来很简单，对吧？但问题很快就来了...

踩坑记录

1. Canvas 层级问题

集成之后首先遇到的就是这个问题，抽奖轮盘是能正常显示和使用的，但每次抽奖后想弹出中奖信息的弹窗，却发现弹窗被 Canvas 挡住了！

问题在于：微信小程序中的 Canvas 是原生组件，默认层级很高（层级 999+），会覆盖在普通小程序组件之上。

查阅官方文档才发现有这么一段说明：

小程序内 canvas 是原生组件，所以默认就是顶层渲染，我特意对此进行了优化，在第一次开始游戏之后: 每次结束游戏都会切换成图片来显示, 但是当游戏开始时, 抽奖组件还是会切换到 canvas 来渲染。

所以 lucky-canvas 已经做了优化，在抽奖结束时会将 canvas 替换为图片，这样可以避免一直挡住其他内容。但在抽奖过程中，canvas 还是会显示出来并处于最高层级。

解决方案：

方法一：调整弹窗的显示时机，确保在抽奖结束并切换为图片后再显示：

startLottery() {
  // 随机获取中奖索引
  const index = Math.floor(Math.random() * 6)

  // 开始旋转
  this.myLucky.play()

  // 模拟请求接口
  setTimeout(() => {
    // 停止旋转并传递中奖索引
    this.myLucky.stop(index)

    // 延迟显示弹窗，确保Canvas已转为图片
    setTimeout(() => {
      this.setData({
        showResultModal: true
      })
    }, 300) // 给转换留点时间
  }, 2500)
}

方法二：使用微信小程序的 cover-view 和 cover-image 在 Canvas 上方显示内容：

<view class="lottery-container">
  <canvas
    type="2d"
    id="lucky-wheel"
    style="width: {{width}}px; height: {{height}}px"
    bindtap="startLottery"
  ></canvas>

  <!-- 使用cover-view在canvas上层显示 -->
  <cover-view class="result-modal" wx:if="{{showResultModal}}">
    <cover-view class="modal-content"
      >恭喜获得{{prizes[prizeIndex].fonts[0].text}}</cover-view
    >
    <cover-view class="modal-btn" bindtap="closeModal">我知道了</cover-view>
  </cover-view>
</view>

但 cover-view 的样式支持有限，复杂样式不一定能实现。总的来说，方案一更可靠。

2. 抽奖动画卡顿问题

在一些低端设备上，发现抽奖动画会出现卡顿，特别是在配置了复杂图片和动画效果后。

解决方案：

优化配置，减少不必要的动画效果：

this.myLucky = new LuckyWheel({
  // 其他配置...

  // 降低动画复杂度
  speed: 8, // 默认是10，可以适当降低

  // 降低DPR，减少渲染压力
  dpr: Math.min(wx.getSystemInfoSync().pixelRatio, 2), // 限制最大DPR为2

  // 减少图片资源
  prizes: [
    // 使用纯色背景代替图片背景
    { background: "#f8d384", fonts: [{ text: "一等奖", top: "10%" }] },
    // ...
  ],
});

当然,最后狠狠地用了公司的cdn流量解决了图片卡顿的问题

#### 3. 后台切换导致的状态异常

当用户在抽奖过程中切换到后台，再回来时，有时会发现抽奖状态错乱，比如转盘不继续转动，或者卡在某个状态。

**解决方案：**

监听小程序的显示/隐藏事件，并处理状态：

```javascript
Page({
  // 其他代码...

  onHide() {
    // 记录当前是否在抽奖中
    this.isLotteryRunning = this.data.isPlaying;
  },

  onShow() {
    if (this.isLotteryRunning) {
      // 用户从后台回来，且之前在抽奖中
      // 可以选择重置抽奖状态或显示提示
      this.setData({
        showResumeModal: true,
        isPlaying: false,
      });
    }
  },

  // 恢复抽奖
  resumeLottery() {
    this.setData({
      showResumeModal: false,
    });
    // 重新初始化抽奖组件
    this.initLuckyWheel();
  },
});

## 总结

Lucky Canvas 确实是一个不错的抽奖组件库，功能丰富且使用相对简单。虽然在微信小程序中集成会碰到一些坑，但官方也在不断优化。

通过这次踩坑记录，记住，原生组件的层级问题是重中之重，提前规划好 UI 布局和交互流程，可以避免很多麻烦。

如果你还在纠结用哪个抽奖库，我个人是比较推荐 lucky-canvas 的，活跃度高，更新快，支持平台多。