更新记录

1.0.0（2026-08-31） 下载此版本

首个版本发布，支持以下功能：

1.转盘完全可配置：背景图片、指针图片、奖品图片、奖品数量、奖品名称与描述均可自定义 2.每个扇形颜色可单独配置，也支持默认间隔色循环 3.概率自动验证，总和必须为 1 4.转盘大小、动画时长、旋转圈数可配置 5.指针图片宽高可配置，支持抽奖次数用尽后的禁用态指针图片 6.奖品文字距转盘中心的距离可调节 7.支持是否允许重复抽奖、最大抽奖次数限制 8.中奖弹窗可开关，奖品列表可开关 9.支持指定奖品抽奖（startLotteryWithPrizeId）与按索引测试抽奖（testFixedLottery） 10.提供 reset、setLotteryCount 等外部控制方法 11.中奖事件 onWin、历史记录更新事件 onHistoryUpdate

平台兼容性

uni-app(5.24)

Prize Wheel 幸运大转盘

一款高度可配置的 uni-app 转盘抽奖组件。奖品数量、中奖概率、扇形颜色、背景图、指针图、奖品图、动画时长、抽奖次数等全部可通过配置控制，开箱即用，无需切图。

🚀 功能特性

核心玩法

• 🎯 任意奖品数量：3~12 个奖品均可，扇形角度与奖品文字位置自动计算，无需手工切图
• 📊 自定义中奖概率：每个奖品独立配置 probability（0~1），组件自动校验概率总和是否为 1，保证公平性
• 🎨 扇形颜色：支持默认间隔色循环，也支持为每个奖品单独指定颜色
• 🎁 奖品图文配置：奖品名称、描述、图片均可单独设置，未配置图片时自动显示默认图

图片与外观

• 🖼️ 转盘背景图：任意替换转盘背景图片
• 👉 指针图片：可配置指针图片及其宽高（pointerWidth / pointerHeight）
• ⛔ 禁用态指针：抽奖次数用尽后自动切换为禁用态指针图片（pointerDisabledImage）
• 📏 转盘大小：通过 wheelSize 自定义转盘尺寸
• ✨ 文字位置：奖品文字距转盘中心的距离可调（prizeTextRadius）

抽奖控制

• 🔄 重复抽奖：allowRepeat 控制是否允许重复抽奖
• 🔢 次数限制：maxLotteryCount 限制最大抽奖次数
• 🎯 指定奖品抽奖：startLotteryWithPrizeId 支持按奖品 ID 固定中奖结果，方便对接服务端下发中奖
• ⏱️ 动画控制：旋转圈数（spinRounds）、动画时长（spinDuration）可自定义
• 🧹 外部控制：提供 reset 重置、setLotteryCount 设置次数等方法

交互与展示

• 🏆 中奖弹窗：内置中奖成功弹窗，可通过 showSuccessModal 开关
• 📋 奖品列表：可选的奖品及概率展示列表（showPrizeList）
• 📜 历史记录：自动记录中奖历史并通过事件回调给外部
• 📡 事件回调：onWin 中奖事件、onHistoryUpdate 历史更新事件

📦 安装引入

1. 将 uni_modules/prize-wheel 整个目录复制到项目的 uni_modules 目录下；
2. 开启 easycom 时可直接使用 <prize-wheel> 标签，无需手动引入；
3. 若未开启 easycom，可在页面中手动引入：

<script setup>
import PrizeWheel from "@/uni_modules/prize-wheel/components/prizeWheel/prizeWheel.vue";
</script>

🚀 快速开始

基础用法

<template>
  <prize-wheel
    :wheel-config="wheelConfig"
    @onWin="handleWin"
    @onHistoryUpdate="handleHistoryUpdate"
  />
</template>

<script setup>
import { ref } from "vue";

const wheelConfig = ref({
  backgroundImage: "/uni_modules/prize-wheel/static/zhuanPan.png",
  pointerImage: "/uni_modules/prize-wheel/static/pointer.png",
  pointerDisabledImage: "/uni_modules/prize-wheel/static/pointer-disabled.png",
  prizes: [
    { name: "一等奖", desc: "iPhone 15", probability: 0.05, image: "/uni_modules/prize-wheel/static/prize1.png", color: "#ff6b6b" },
    { name: "二等奖", desc: "AirPods", probability: 0.15, image: "/uni_modules/prize-wheel/static/prize2.png", color: "#4ecdc4" },
    { name: "三等奖", desc: "100元红包", probability: 0.30, image: "/uni_modules/prize-wheel/static/prize3.png", color: "#45b7d1" },
    { name: "谢谢参与", desc: "下次再来", probability: 0.50, image: "/uni_modules/prize-wheel/static/prize4.png", color: "#96ceb4" },
  ],
  sectorColors: ["#cdd7ff", "#abbaf4"],
  useCustomColors: false,
});

function handleWin(data) {
  console.log("中奖了！", data.prize.name, "索引:", data.index, "次数:", data.lotteryCount);
}
function handleHistoryUpdate(history) {
  console.log("抽奖历史更新", history);
}
</script>

高级用法

<template>
  <prize-wheel
    ref="wheelRef"
    :wheel-config="wheelConfig"
    :wheel-size="650"
    :spin-duration="4"
    :spin-rounds="6"
    :allow-repeat="true"
    :max-lottery-count="3"
    :show-prize-list="false"
    :show-success-modal="true"
    :pointer-width="136"
    :pointer-height="159"
    @onWin="handleWin"
  />
</template>

<script setup>
import { ref } from "vue";

const wheelRef = ref(null);
const wheelConfig = ref({ /* 同基础用法 */ });

// 重置转盘（清空状态、恢复可抽奖）
function handleReset() {
  wheelRef.value.reset();
}

// 由服务端返回中奖结果时，按奖品 ID 固定抽奖（奖品需配置 id 或 originalData.id）
function handleServerResult(prizeId) {
  wheelRef.value.startLotteryWithPrizeId(prizeId);
}

function handleWin(data) {
  console.log("中奖了！", data);
}
</script>

🔧 Props 属性配置

📦 wheelConfig 转盘配置

{
  backgroundImage: String,      // 转盘背景图片路径
  pointerImage: String,         // 指针图片路径
  pointerDisabledImage: String, // 抽奖次数用尽后的禁用态指针图片（可选）
  prizes: Array,                // 奖品数组
  sectorColors: Array,          // 默认扇形间隔色数组
  useCustomColors: Boolean      // 是否使用奖品自定义颜色，默认 false
}

prizes 奖品字段

扇形颜色说明

• sectorColors：默认间隔色数组，循环使用，如 ['#cdd7ff', '#abbaf4']
• useCustomColors: false（默认）：使用 sectorColors 间隔色循环
• useCustomColors: true：使用每个奖品的 color 属性作为该扇形颜色
• 支持任意有效 CSS 颜色值：十六进制、RGB、RGBA、颜色名称等

📡 事件

onWin 参数：

{
  prize: Object,        // 中奖奖品对象
  index: Number,        // 奖品在 prizes 数组中的索引
  lotteryCount: Number  // 当前累计抽奖次数
}

onHistoryUpdate 参数：

[
  { time: String, prize: Object } // 抽奖时间、奖品对象，最多保留 10 条
]

🎯 组件方法

通过 ref="wheelRef" 获取组件实例后调用：

// 示例
this.$refs.wheelRef.reset();
this.$refs.wheelRef.setLotteryCount(0);
this.$refs.wheelRef.startLotteryWithPrizeId("3");

🎨 样式自定义

组件内置样式类，可在外部覆盖：

/* 示例：自定义转盘容器背景 */
.wheel-container {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

⚠️ 使用注意事项

1. 概率总和必须为 1：组件会自动校验，若不为 1 会在控制台输出警告，且抽奖结果可能不符合预期
2. 图片路径：建议使用绝对路径；组件自带默认图位于 /uni_modules/prize-wheel/static/，自行替换时需保证路径正确
3. 奖品数量：建议 3~12 个，过多会影响扇形与文字的展示效果
4. 概率精度：建议保留 2~3 位小数，避免浮点精度导致的误差
5. 组件引用：调用组件方法前需设置 ref="wheelRef"，并在页面挂载完成后调用
6. 指定抽奖：startLotteryWithPrizeId 要求奖品配置了 id 或 originalData.id 字段，否则会提示"未找到指定奖品"
7. 平台兼容：组件使用 teleport、requestAnimationFrame 与 v-bind() CSS 变量，App-nvue 等受限平台可能存在兼容性问题，请以实际运行端测试为准
8. 重复抽奖：allowRepeat=false 时抽完一次即置为完成态；allowRepeat=true 时受 maxLotteryCount 限制

📞 更新日志

v1.0.0（2026-08-31）

• 🎉 首个版本发布，支持：任意奖品数量与概率配置、扇形颜色自定义、背景/指针/奖品图片可配置、抽奖次数与重复抽奖控制、指定奖品抽奖、中奖弹窗、奖品列表、历史记录、完整事件与外部控制方法

祝您使用愉快！ 🎉