xiaozhang/zhibo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
merge/unify-all
zhibo/android-app/礼物打赏功能说明.md

10 KiB
Raw Permalink Blame History

礼物打赏功能说明文档

功能概述

在直播间页面添加了礼物打赏功能，用户可以在观看直播时给主播赠送各种礼物。

功能特点

1. 礼物按钮位置

  • 礼物按钮位于直播间底部聊天输入框的右侧
  • 在发送按钮的左边，方便用户快速访问
  • 使用礼物图标（🎁），颜色为橙色（#FF9800），醒目易识别

2. 礼物种类（8种）

礼物名称 价格 等级 图标
玫瑰 10金币 ⭐ 🌹
爱心 20金币 ⭐ ❤️
蛋糕 50金币 ⭐⭐ 🎂
星星 100金币 ⭐⭐ ⭐
钻石 200金币 ⭐⭐⭐ 💎
皇冠 500金币 ⭐⭐⭐⭐ 👑
跑车 1000金币 ⭐⭐⭐⭐⭐ 🚗
火箭 2000金币 ⭐⭐⭐⭐⭐ 🚀

3. 礼物选择弹窗

弹窗布局

  • 底部弹出式设计（BottomSheetDialog）
  • 标题栏显示"选择礼物"、用户金币余额和充值按钮
  • 礼物列表采用4列网格布局（GridLayoutManager）
  • 每个礼物显示图标、名称和价格

交互功能

  • 礼物选择：点击礼物卡片进行选择，选中后显示蓝色边框
  • 数量调整：通过 +/- 按钮调整赠送数量（1-99）
  • 余额显示：实时显示用户当前金币余额
  • 充值按钮：点击充值按钮打开充值对话框
  • 选中信息：底部显示选中礼物的图标、名称和价格
  • 赠送按钮：点击赠送按钮完成礼物赠送

4. 充值功能

充值入口

  • 在礼物选择弹窗的标题栏右侧
  • 显示为带边框的"充值"按钮，带有加号图标
  • 颜色为橙色（#FF9800），与金币主题一致

充值对话框

  • 居中弹出式设计（MaterialAlertDialog）
  • 显示当前金币余额
  • 提供6种充值选项（2列网格布局）：
    • 100金币 - ¥10（首充优惠）
    • 300金币 - ¥30
    • 500金币 - ¥50（热门）
    • 1000金币 - ¥100
    • 3000金币 - ¥300（最划算）
    • 5000金币 - ¥500

充值流程

  1. 用户点击充值按钮
  2. 显示充值对话框
  3. 用户选择充值金额（选中后显示橙色边框）
  4. 点击"确认充值"按钮
  5. 调用支付接口（待集成支付SDK）
  6. 支付成功后更新金币余额
  7. 显示充值成功提示
  8. 关闭充值对话框

5. 赠送流程

  1. 用户点击礼物按钮
  2. 检查登录状态（未登录则提示登录）
  3. 显示礼物选择弹窗
  4. 用户选择礼物和数量
  5. 点击赠送按钮
  6. 检查金币余额是否足够
  7. 赠送成功后：
    • 扣除相应金币
    • 更新余额显示
    • 在聊天区显示赠送消息
    • 显示成功提示
    • 关闭弹窗

5. 聊天区显示

赠送礼物后，在聊天区会显示类似以下的消息：

我 送出了 1 个 玫瑰
我 送出了 5 个 钻石

礼物消息使用特殊标识（isGiftMessage），可以在后续添加特殊样式或动画效果。

文件结构

新增文件

Java类

  • Gift.java - 礼物数据模型
  • GiftAdapter.java - 礼物列表适配器
  • RechargeOption.java - 充值选项数据模型
  • RechargeAdapter.java - 充值选项适配器

布局文件

  • bottom_sheet_gift.xml - 礼物选择弹窗布局
  • item_gift.xml - 礼物列表项布局
  • dialog_recharge.xml - 充值对话框布局
  • item_recharge_option.xml - 充值选项列表项布局

图标资源

  • ic_gift_24.xml - 礼物按钮图标
  • ic_coin_24.xml - 金币图标
  • ic_add_24.xml - 增加数量图标
  • ic_remove_24.xml - 减少数量图标
  • ic_add_circle_24.xml - 充值按钮图标
  • ic_gift_rose.xml - 玫瑰礼物图标
  • ic_gift_heart.xml - 爱心礼物图标
  • ic_gift_cake.xml - 蛋糕礼物图标
  • ic_gift_star.xml - 星星礼物图标
  • ic_gift_diamond.xml - 钻石礼物图标
  • ic_gift_crown.xml - 皇冠礼物图标
  • ic_gift_car.xml - 跑车礼物图标
  • ic_gift_rocket.xml - 火箭礼物图标

背景资源

  • bg_gift_selected.xml - 礼物选中状态背景
  • bg_recharge_selected.xml - 充值选项选中状态背景
  • bg_discount_label.xml - 优惠标签背景

修改文件

  • RoomDetailActivity.java - 添加礼物功能逻辑
  • activity_room_detail_new.xml - 添加礼物按钮
  • ChatMessage.java - 添加礼物消息标识

后端接口对接

1. 获取礼物列表

GET /api/gifts

返回数据格式：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "1",
      "name": "玫瑰",
      "price": 10,
      "iconUrl": "https://example.com/gifts/rose.png",
      "description": "浪漫的玫瑰",
      "level": 1
    }
  ]
}

2. 获取用户金币余额

GET /api/user/balance

返回数据格式：

{
  "code": 200,
  "message": "success",
  "data": {
    "coinBalance": 1000
  }
}

3. 赠送礼物

POST /api/gifts/send

请求参数：

{
  "roomId": "room123",
  "streamerId": "user456",
  "giftId": "1",
  "count": 5
}

返回数据格式：

{
  "code": 200,
  "message": "赠送成功",
  "data": {
    "success": true,
    "newBalance": 950,
    "message": "赠送成功！"
  }
}

4. 获取充值选项列表

GET /api/recharge/options

返回数据格式：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "1",
      "coinAmount": 100,
      "price": 10.0,
      "discountLabel": "首充优惠"
    },
    {
      "id": "2",
      "coinAmount": 300,
      "price": 30.0,
      "discountLabel": null
    }
  ]
}

5. 创建充值订单

POST /api/recharge/create

请求参数：

{
  "optionId": "1",
  "coinAmount": 100,
  "price": 10.0
}

返回数据格式：

{
  "code": 200,
  "message": "订单创建成功",
  "data": {
    "orderId": "order123456",
    "paymentUrl": "https://pay.example.com/order123456",
    "qrCode": "https://example.com/qr/order123456.png"
  }
}

6. 查询充值订单状态

GET /api/recharge/status/{orderId}

返回数据格式：

{
  "code": 200,
  "message": "success",
  "data": {
    "orderId": "order123456",
    "status": "paid",
    "coinAmount": 100,
    "newBalance": 1100
  }
}

使用说明

测试步骤

  1. 运行应用并进入任意直播间
  2. 点击底部聊天输入框右侧的礼物图标（🎁）
  3. 在弹出的礼物选择窗口中：
    • 查看顶部显示的金币余额（默认1000金币）
    • 点击"充值"按钮测试充值功能
    • 在充值对话框中选择充值金额
    • 点击"确认充值"按钮（模拟充值成功）
    • 查看余额是否增加
  4. 选择礼物进行赠送：
    • 点击任意礼物进行选择
    • 使用 +/- 按钮调整赠送数量
    • 点击"赠送"按钮完成赠送
  5. 观察聊天区显示的赠送消息
  6. 再次打开礼物窗口，查看余额是否已扣除

注意事项

  1. 登录检查：赠送礼物需要登录，未登录用户会看到登录提示
  2. 余额检查：金币不足时会提示"金币余额不足，请充值"
  3. 数量限制：单次赠送数量限制为1-99个
  4. 礼物选择：必须选择礼物才能赠送，否则会提示"请选择礼物"
  5. 充值选择：必须选择充值金额才能充值，否则会提示"请选择充值金额"
  6. 支付集成：当前为模拟充值，实际使用需要集成支付SDK

后续优化建议

1. 礼物动画

  • 添加礼物赠送的动画效果（如礼物飞入屏幕）
  • 使用Lottie动画库实现更炫酷的效果
  • 不同等级的礼物使用不同的动画效果

2. 礼物特效

  • 高价值礼物（如火箭、跑车）添加全屏特效
  • 连续赠送相同礼物时显示连击效果
  • 添加音效和震动反馈

3. 礼物排行榜

  • 显示直播间礼物贡献榜
  • 显示主播收到的礼物总价值
  • 显示用户赠送礼物的历史记录

4. 礼物墙

  • 在直播间右侧显示最近的礼物赠送记录
  • 滚动显示礼物消息
  • 点击可查看赠送者信息

5. 充值功能

  • 添加金币充值入口
  • 集成支付SDK（微信支付、支付宝等）
  • 显示充值优惠活动

6. 礼物分类

  • 按价格分类（普通、高级、豪华）
  • 按主题分类（浪漫、节日、特殊）
  • 添加限时礼物和活动礼物

7. 社交功能

  • 赠送礼物时可以添加留言
  • 支持@主播或其他用户
  • 礼物赠送记录可分享到社交平台

技术实现细节

1. 数据模型

public class Gift {
    private String id;           // 礼物ID
    private String name;         // 礼物名称
    private int price;           // 价格（金币）
    private int iconResId;       // 本地图标资源ID
    private String iconUrl;      // 服务器图标URL
    private String description;  // 礼物描述
    private int level;           // 礼物等级（1-5星）
}

2. 适配器实现

  • 使用RecyclerView + GridLayoutManager实现网格布局
  • 支持礼物选中状态切换
  • 使用接口回调通知选中事件

3. 弹窗管理

  • 使用BottomSheetDialog实现底部弹窗
  • 在Activity销毁时自动释放弹窗资源
  • 支持点击外部区域关闭弹窗

4. 状态管理

  • 使用局部变量管理礼物数量
  • 实时更新金币余额显示
  • 礼物选择状态通过Adapter管理

常见问题

Q1: 礼物图标不显示？

A: 检查drawable资源文件是否正确创建，确保文件名和引用一致。

Q2: 点击礼物按钮没有反应？

A: 检查是否已登录，未登录用户会看到登录提示。

Q3: 赠送后金币没有扣除？

A: 当前使用模拟数据，金币余额存储在内存中，重启应用会重置。对接后端接口后会从服务器获取真实余额。

Q4: 如何添加新的礼物？

A:

  1. 在drawable目录创建新的礼物图标XML文件
  2. 在setupGifts()方法中添加新的Gift对象
  3. 指定礼物名称、价格、图标资源ID和等级

Q5: 如何修改礼物价格？

A: 在setupGifts()方法中修改对应Gift对象的price参数。

更新日志

v1.0.0 (2024-12-24)

  • ✅ 实现礼物选择弹窗
  • ✅ 添加8种不同价格的礼物
  • ✅ 实现礼物数量调整功能
  • ✅ 实现金币余额检查
  • ✅ 在聊天区显示赠送消息
  • ✅ 添加登录状态检查
  • ✅ 创建礼物相关图标资源

联系方式

如有问题或建议，请联系开发团队。

文档版本: v1.0.0
最后更新: 2024年12月24日