功能:奖励发放聊天室公告 + 右下角 Toast 通知卡片

后端(AdminCommandController::reward):
- 新增聊天室公开公告消息(系统公告,所有在场用户可见)
- 接收者私信附带 toast_notification 字段触发前端小卡片
- 公告文案:「🪙 [职务人] 向 [目标] 发放了 [N] 枚奖励金币!」

前端:
- 新建 chat/partials/toast-notification.blade.php:
  全局右下角 Toast 组件,window.chatToast.show() API
  支持 title/message/icon/color/duration/action 配置
  多条 Toast 从右下角向上堆叠,独立计时、独立关闭
- chat:message 事件监听中检测 toast_notification 字段,
  自动弹出右下角通知卡片(仅接收方可见)
- showFriendToast 迁移至 window.chatToast.show(),
  删除 80 行旧实现,代码量净减
- frame.blade.php 引入新 partial

DEVELOPMENT.md:
- 新增 §7.9 chatToast 完整文档(API、使用场景、迁移说明)
- 原 chatBanner 章节编号改为 §7.10
This commit is contained in:
2026-03-01 12:15:18 +08:00
parent 2ae3d83349
commit 3d7b86f06d
5 changed files with 275 additions and 96 deletions
+65 -1
View File
@@ -711,7 +711,71 @@ if (ok) {
---
### 7.9 全局大卡片通知 `window.chatBanner`
### 7.9 全局右下角 Toast 通知卡片 `window.chatToast`
> [!NOTE]
> `chatToast` 是固定在**右下角**的轻量通知卡片,适用于实时事件通知(奖励到账、好友动态等)。
> 与 `chatDialog` 不同,它不阻断操作流程,自动消失,可堆叠多条。
#### 文件位置
```
resources/views/chat/partials/toast-notification.blade.php ← Toast 组件 HTML + JS
resources/views/chat/frame.blade.php ← 已 @include,全页面可用
```
#### API 说明
```javascript
window.chatToast.show({
title: "标题文字", // 必填
message: "正文内容", // 必填,支持 HTML
icon: "🪙", // 可选,左侧 Emoji,默认 💬
color: "#f59e0b", // 可选,强调色,默认 #336699
duration: 6000, // 可选,自动消失毫秒,0 = 不自动消失,默认 6000
action: {
// 可选,操作按钮
label: "操作文字",
onClick: () => {
/* ... */
},
},
});
```
#### 通过消息字段自动触发(后端控制)
后端 broadcast 的消息中包含 `toast_notification` 字段,且接收方是当前用户时,前端脚本会自动弹出 Toast:
```php
// AdminCommandController::reward() 示例
$msg['toast_notification'] = [
'title' => '🪙 奖励金币到账',
'message' => "<b>{$admin->username}</b> 向你发放了 <b>{$amount}</b> 枚金币!",
'icon' => '🪙',
'color' => '#f59e0b',
'duration' => 8000,
];
```
#### 使用场景
| 场景 | 颜色 | 图标 |
| ---------------- | --------------- | ---- |
| 奖励金币到账 | `#f59e0b`(橙) | 🪙 |
| 好友动态通知 | `#6b7280`(灰) | 👥 |
| 礼物收到 | `#e11d48`(玫) | 🎁 |
| 系统提示(普通) | `#336699`(蓝) | 💬 |
| 等级晋升 | `#7c3aed`(紫) | 🌟 |
#### 原 `showFriendToast` 迁移说明
旧函数 `showFriendToast()` 已被 `window.chatToast.show()` 替代,好友删除通知已改用新 API。
新增功能只需调用 `window.chatToast.show()`**勿新增** `showFriendToast` 调用。
---
### 7.10 全局大卡片通知 `window.chatBanner`
> [!NOTE]
> `chatBanner` 是居中弹出的沉浸式大卡片通知组件,适用于好友通知、任命公告、系统广播等重要事件。与 `chatDialog` 不同,它**不阻断操作流程**,支持自动消失和自定义按钮。