Agency-Notify：通知应像 iOS 一样，而非 2014 年的 FiveM

通知贫民区

大多数FiveM服务器上的通知仍然像2019年的默认ESX。顶部基本的彩色条，可能有图标，一行文本。玩家已经习惯忽略它们。这是一个巨大的浪费渠道，无法有效传达重要信息。

现代通知的样子

Agency-Notify ships toast-style notifications that stack cleanly, support rich content (icons, images, multi-line text, action buttons), and have clear severity levels with distinct visual treatments. Success, warning, error, info, each has its own animation, color, and typography weight.

防止垃圾信息的分组

如果三条相似通知快速连续触发，Agency-Notify会将它们合并为一条分组通知。不再有三个相同的“您获得了$500”弹窗阻塞屏幕。这是玩家对任何现代应用的预期行为，FiveM终于实现了。

程序员友好的 API

从任何脚本调用通知只需一个函数： exports['agency-notify']:Show({title, body, icon, level, duration, actions}). 返回一个 ID，您可以稍后用它来更新或关闭通知。就是这样。无框架绑定，无魔法全局变量。

独立版的原因

Agency-Notify is a framework-independent building block. Your QBCore scripts, ESX scripts, and standalone custom code all call the same API. This is how you keep a server's visual language consistent across dozens of scripts from different authors.

安装与设置

运行 Agency-Notify 不到十分钟。从您的 Tebex 库下载资源，拖动 agency-notify 将文件夹放入服务器资源目录，并添加 ensure agency-notify 您的 server.cfg. 资源无数据库依赖，所有通知状态均在客户端内存中处理。

运行后，服务器上的任何脚本都可以立即调用导出API。无需安装后配置即可开始发送通知；默认设置开箱即用且合理。

配置选项

打开 config.lua 自定义视觉和行为默认值：

• 位置，右上角（默认）、左上角、右下角或左下角锚点。
• 最大可见数，通知堆叠数量上限，超过则旧通知被清除。默认5条。
• 默认持续时间，自动关闭前的毫秒数。单个通知可覆盖此设置。
• 动画风格，右滑入（默认）、淡入或缩放。全局应用于所有通知。
• 组窗口，毫秒内的时间窗口，重复通知将被合并。
• 启用声音，按严重级别切换细微通知提示音开关。

所有设置均存放在单一扁平配置表中，无需查找嵌套结构，无需区分客户端和服务器配置。

框架兼容性

Agency-Notify is 100% standalone. It has no framework imports, no QBCore dependency, no ESX dependency. This means:

• 它适用于任何 FiveM 服务器，无论您的基础框架是什么。
• 以后切换框架不会破坏您的通知调用。
• 每个作者的每个脚本都能通过相同API发送通知，无需了解你运行的框架。

如果您替换现有通知系统（如 ox_lib 的 notify、QBCore 的 QBNotify 等），只需更新脚本中的导出调用。签名与常见模式足够接近，查找替换即可处理大部分迁移。

为什么这对角色扮演很重要

通知是服务器系统与玩家之间的主要反馈渠道。当毒品交易完成，当敌对帮派进入你的地盘，当管理员需要提醒所有人某个事件，所有这些都通过通知进行。如果该渠道显得过时或被忽视，关键的服务器通信将无声失败。

信任通知系统的玩家会关注它。习惯屏蔽垃圾且丑陋通知栏的玩家容易错过信息，感到脱节。Agency-Notify的分组系统专门解决垃圾信息问题：如果服务器在抢劫期间快速发送三条通知，玩家看到的是一条分组消息，而非三条争夺注意力的弹窗。

严重性等级（success, warning, error, info）增加了第二层信号。玩家很快就会学会绿色代表良好，红色代表立即行动。这种颜色识别减少了高强度操作情况下的认知负担。

常见问题

我可以在通知显示后更新或关闭它吗？

是的。 Show() export返回一个ID。将该ID传递给 exports['agency-notify']:Update(id, {body, level}) 更改内容，或 exports['agency-notify']:Dismiss(id) 提前移除它。这对状态变化的进度式通知（例如“处理中…”→“完成”）很有用。

是否替换 ox_lib 通知？

可以。Agency-Notify 覆盖相同的使用场景，但视觉风格不同。如果您想要与其他 Agency 脚本一致的玻璃拟态美学，替换非常简单。如果您的服务器深度集成了 ox_lib 并且您满意这种外观，继续使用 ox_lib 进行通知也没问题，没有冲突。

玩家可以自定义通知位置吗？

默认不支持，位置由服务器级配置决定。这是有意为之：服务器所有者控制视觉语言，而非单个玩家。如需每玩家偏好，需将选择保存至数据库，并在玩家加入时通过玩家数据传递。

是否有防止脚本通知垃圾信息的速率限制？

分组系统自动处理去重。对于严格速率限制，设置 Config.RateLimit = true 和 Config.RateLimitWindow = 1000 (毫秒)在 config.lua 中。此设置限制任何单个脚本在该时间窗口内触发的唯一通知数量。

需求

• FiveM 服务器（任意框架或独立）
• 拥有带有效 Agency-Notify 许可证密钥的 cfx.re 账户
• 无数据库依赖
• 无外部资源依赖

比较 Agency-Notify 与替代方案

FiveM通知生态有多种选择：ox_lib通知，QBCore内置通知，以及各种standalone脚本。以下是各自适用场景：

ox_lib 通知功能完善且维护良好，但其风格与 ox_lib 视觉语言紧密绑定。如果你的服务器已全面运行 ox_lib，视觉一致性可能比升级更重要。如果你构建的是以 Agency 为核心的堆栈，Agency-Notify 的匹配美学更合适。

QBCore 的 QBNotify 功能实用但极简，没有分组、没有更新 API、没有操作按钮。它适用于基本用例，如果您已经使用 QBCore，则无需额外费用。如果您需要超过简单提示的功能，说明您已经超出其范围。

Agency-Notify targets servers that care about the notification experience as a product detail rather than an afterthought. If you've ever thought "our notifications look bad and players ignore them," that's the problem this script exists to solve.