更新记录

1.0.0（2025-11-06） 下载此版本

✨ 新增功能

平台兼容性

uni-app(3.6.13)

uni-app x(3.6.13)

其他

hy-lotteryGrid 九宫格跑马灯抽奖组件

功能强大、高度可定制的九宫格跑马灯抽奖组件，支持多平台、多种自定义配置

✨ 特性

• 🎯 灵活配置 - 支持自定义格子数量（9宫格、16宫格等）
• 🎨 高度可定制 - 丰富的样式配置，支持插槽自定义
• 📊 概率控制 - 精确的概率算法，支持服务端控制
• 🎬 流畅动画 - 可配置的加速减速效果，视觉体验流畅
• 🔊 音效系统 - 内置音效管理，支持自定义音效
• 📱 多端支持 - 完美支持 H5、小程序、App 等多个平台
• 🎮 交互友好 - 支持多次抽奖、结果确认等多种交互模式
• 💾 记录管理 - 内置中奖记录存储功能
• 🔒 类型安全 - 完整的 TypeScript 类型定义

📦 安装

方式一：uni_modules（推荐）

在 HBuilderX 中，通过插件市场导入 hy-lotteryGrid 插件。

方式二：npm 安装

npm install hy-lotteryGrid

🚀 快速开始

基础用法

<template>
  <view class="container">
    <hy-lottery-grid
      title="幸运大抽奖"
      :prizeList="prizes"
      @draw-end="onDrawEnd"
      @confirm="onConfirm"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      prizes: [
        { name: '一等奖', image: '/static/prize1.png', probability: 0.1 },
        { name: '二等奖', image: '/static/prize2.png', probability: 0.2 },
        { name: '三等奖', image: '/static/prize3.png', probability: 0.3 },
        { name: '谢谢参与', image: '/static/thanks.png', probability: 0.4 }
      ]
    }
  },
  methods: {
    onDrawEnd(result) {
      console.log('抽奖结束:', result.prize.name)
    },
    onConfirm(result) {
      console.log('确认结果:', result.prize.name)
    }
  }
}
</script>

高级用法

<template>
  <hy-lottery-grid
    title="超级抽奖"
    :gridCount="9"
    :prizeList="prizes"
    :speed="100"
    :circleCount="3"
    :enableMultipleDraw="true"
    :enableSound="true"
    :showProbability="true"
    :beforeDraw="beforeDraw"
    @draw-start="onDrawStart"
    @draw-end="onDrawEnd"
  >
    <!-- 自定义奖品显示 -->
    <template v-slot:prize="{ item, index, active }">
      <view class="custom-prize" :class="{ 'active': active }">
        <image :src="item.image" class="prize-img" />
        <text class="prize-text">{{ item.name }}</text>
      </view>
    </template>

    <!-- 自定义抽奖按钮 -->
    <template v-slot:center-btn="{ disabled }">
      <view class="custom-btn" :class="{ 'disabled': disabled }">
        <text>点我抽奖</text>
      </view>
    </template>

    <!-- 自定义结果弹窗 -->
    <template v-slot:result="{ result }">
      <view class="custom-result">
        <image :src="result.image" class="result-img" />
        <text class="result-title">恭喜获得</text>
        <text class="result-name">{{ result.name }}</text>
      </view>
    </template>
  </hy-lottery-grid>
</template>

<script>
export default {
  data() {
    return {
      prizes: [
        { 
          name: 'iPhone 15 Pro', 
          image: '/static/iphone.png', 
          probability: 0.01,
          description: '256GB 蓝色钛金属',
          value: 8999
        },
        { 
          name: '100元红包', 
          image: '/static/money.png', 
          probability: 0.1,
          description: '现金红包'
        },
        { 
          name: '10元优惠券', 
          image: '/static/coupon.png', 
          probability: 0.3,
          description: '全场通用'
        },
        { 
          name: '谢谢参与', 
          image: '/static/thanks.png', 
          probability: 0.59,
          description: '再接再厉'
        }
      ]
    }
  },
  methods: {
    // 抽奖前置检查
    async beforeDraw() {
      // 检查用户是否有抽奖次数
      const hasChance = await this.checkDrawChance()
      if (!hasChance) {
        uni.showToast({ title: '抽奖次数不足', icon: 'none' })
        return false
      }
      return true
    },

    async checkDrawChance() {
      // 这里可以调用后端接口检查
      return true
    },

    onDrawStart() {
      console.log('开始抽奖')
    },

    onDrawEnd(result) {
      console.log('抽奖结束:', result)
      // 可以在这里上报中奖结果到服务器
      this.reportResult(result)
    },

    async reportResult(result) {
      // 上报到服务器
      await uni.request({
        url: '/api/lottery/report',
        method: 'POST',
        data: {
          prizeId: result.prize.id,
          prizeName: result.prize.name
        }
      })
    }
  }
}
</script>

📖 API 文档

Props

PrizeItem

奖品项数据结构：

interface PrizeItem {
  name: string              // 奖品名称（必填）
  image?: string            // 奖品图片URL
  icon?: string             // 奖品图标URL（别名）
  probability: number       // 中奖概率（0-1之间，必填）
  description?: string      // 奖品描述
  id?: string | number      // 奖品ID
  color?: string            // 奖品名称颜色
  stock?: number            // 奖品库存数量
  value?: number            // 奖品价值
  [key: string]: any        // 其他自定义数据
}

Events

DrawResult

抽奖结果数据结构：

interface DrawResult {
  prize: PrizeItem    // 中奖奖品信息
  index: number       // 奖品在列表中的索引
}

Slots

Methods

通过 ref 调用组件方法：

<hy-lottery-grid ref="lottery" />

<script>
export default {
  methods: {
    start() {
      this.$refs.lottery.startLottery()
    },
    reset() {
      this.$refs.lottery.reset()
    }
  }
}
</script>

🎯 使用场景

1. 服务器控制中奖

<template>
  <hy-lottery-grid
    :prizeList="prizes"
    :customDrawLogic="serverDraw"
    @draw-end="onDrawEnd"
  />
</template>

<script>
export default {
  data() {
    return {
      prizes: [...]
    }
  },
  methods: {
    // 服务器控制中奖逻辑
    async serverDraw() {
      const res = await uni.request({
        url: '/api/lottery/draw',
        method: 'POST'
      })
      // 返回服务器指定的中奖奖品索引
      return res.data.prizeIndex
    },

    onDrawEnd(result) {
      // 抽奖完成后处理
      console.log('中奖:', result.prize.name)
    }
  }
}
</script>

2. 限制抽奖次数

<template>
  <hy-lottery-grid
    :prizeList="prizes"
    :beforeDraw="checkDrawTimes"
    :disabled="drawTimes <= 0"
  />
  <view>剩余抽奖次数：{{ drawTimes }}</view>
</template>

<script>
export default {
  data() {
    return {
      prizes: [...],
      drawTimes: 3
    }
  },
  methods: {
    async checkDrawTimes() {
      if (this.drawTimes <= 0) {
        uni.showToast({
          title: '抽奖次数已用完',
          icon: 'none'
        })
        return false
      }
      this.drawTimes--
      return true
    }
  }
}
</script>

3. 中奖记录管理

<script>
import { saveLotteryRecord, getLotteryRecords } from '@/uni_modules/hy-lotteryGrid/js_sdk/utils.js'

export default {
  data() {
    return {
      records: []
    }
  },
  mounted() {
    this.loadRecords()
  },
  methods: {
    onDrawEnd(result) {
      // 保存中奖记录
      saveLotteryRecord({
        prizeName: result.prize.name,
        prizeImage: result.prize.image
      })

      // 重新加载记录
      this.loadRecords()
    },

    loadRecords() {
      this.records = getLotteryRecords()
    }
  }
}
</script>

🎨 样式定制

自定义颜色主题

<hy-lottery-grid
  :containerStyle="{
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)'
  }"
  :itemStyle="{
    backgroundColor: '#f5f5f5',
    borderRadius: '16rpx'
  }"
  :activeStyle="{
    backgroundColor: '#ff6b6b',
    transform: 'scale(0.9)',
    boxShadow: '0 0 30rpx rgba(255, 107, 107, 0.8)'
  }"
  :centerBtnStyle="{
    background: 'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)'
  }"
/>

调整网格大小

<hy-lottery-grid
  :gridSize="750"
  :gridCount="16"
/>

⚠️ 注意事项

1. 概率配置：所有奖品的 probability 总和应该为 1
2. 格子数量：gridCount 必须是平方数（9、16、25等）
3. 音效文件：启用音效前需要准备音效文件并配置路径
4. 服务器控制：使用 customDrawLogic 时，需要返回有效的奖品索引
5. 性能优化：大量奖品时，建议使用懒加载图片

📝 更新日志

查看 CHANGELOG.md

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT License

💬 技术支持

如有问题，欢迎通过以下方式联系：

• 插件市场评论区
• GitHub Issues
• QQ群：[待补充]

Made with ❤️ by HY Team