Agency-ProgressBar：悄然提升每个脚本的UI细节

一个小脚本，巨大的影响

进度条在 FiveM 中无处不在，如开锁、修理、洗钱、采矿、医疗援助。默认实现功能性强但平淡。Agency-ProgressBar 是我们对细节关怀下该工具应有感觉的诠释。

优秀进度条的构成

一个好的进度条同时传达四个信息：正在进行的动作、进度、剩余时间和是否可取消。大多数实现只处理前两个。Agency-ProgressBar显示全部四项，配以细腻动画，使进度感觉流畅而非断续。

有效的取消

玩家主动取消时，会触发一个短暂的淡出动画，在300毫秒内将进度条的不透明度恢复到零。没有突兀的消失。开发者可以注册取消回调，以便脚本在玩家中途放弃动作时正确清理。

上下文定位

进度条出现在相关屏幕元素附近，自身目标动作时在头顶上方，交互NPC动作时在目标NPC上方。无需再从屏幕底部读取动作状态，而动作发生在顶部。此上下文定位是细微的用户体验升级，玩家能感受到但难以言明。

导出模式

与我们所有的实用脚本一样，Agency-ProgressBar 提供了简单的导出 API： exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}). 几分钟内即可将其集成到任何脚本中。它可与Agency-Notify、Agency-Hud及我们生态系统的其他部分无特殊配置地组合使用。

安装与设置

Agency-ProgressBar is a drop-in utility with zero database dependency. Download from Tebex, drop the folder into your resources directory, add ensure agency-progressbar 到 server.cfg. 就这样。资源立即开始工作，任何脚本都可以在下一次重启时调用 exports API。

如果您替换现有进度条（如 ox_lib 的 progressBar、qb-progressbar 等），查找替换导出调用名称即可在几分钟内完成大部分迁移。参数结构故意接近社区常用模式。

配置选项

打开 config.lua 调整默认值：

• 默认位置，玩家头顶上方（默认）或固定底部中央。
• 配色方案，填充颜色渐变。支持单色、双色渐变或严重度映射（绿色表示正常，橙色表示缓慢，红色表示关键）。
• 取消键，取消可取消进度条的按键。默认：退格键。
• 取消动画，淡出（默认）、滑出或瞬间消失。
• 时间显示，显示剩余秒数（默认）、百分比或不显示。
• 最短持续时间，动作短于此阈值则跳过进度条。默认：500 毫秒。

框架兼容性

Agency-ProgressBar is fully standalone with no framework dependencies. It functions identically on QBCore, ESX, and custom server setups. The exports API is the only integration surface, no shared globals, no framework events, no permission checks. Install it and call it from any script regardless of origin.

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

进度条是 UX 原始元素，出现在许多游戏环节中，如开锁、手铐、制作、治疗、收集证据、黑客攻击。当这些进度条在不同脚本中外观不匹配或行为不一致时，会产生细微的视觉噪音，破坏服务器的一致性。

当服务器上的每个进度条都使用 Agency-ProgressBar 时，视觉语言统一。玩家会直观理解进度条的含义及其行为。取消行为一致。排版与其他 UI 匹配。细节虽小，但累积起来显著提升玩家体验的精致度。

上下文定位比听起来更重要。锁车时锚定在角色头顶的进度条让你专注于动作，而非屏幕角落。在紧张时刻，比如被追逐时开锁，这让玩家在进度条可见时保持空间感知。

常见问题

我可以同时运行多个进度条吗？

是的。每个 Play() 调用返回一个 ID 并管理其自身状态。多个进度条垂直堆叠在玩家上方，间距合理。这对于多步骤操作很有用，可以同时显示并行任务的进度，尽管大多数 RP 场景一次只使用一个进度条。

如何将进度条附加到道具或NPC而不是玩家？

通过一个 target = {type = 'entity', id = entityNetId} 选项表中的字段。进度条悬停在指定实体上，而不是玩家身上。用于修理动作、对倒地玩家的医疗动作，或任何动作焦点在外部的情况。

服务器端可以强制进度条不可取消吗？

是的。设置 canCancel = false 调用 Play() 时。取消键无效且不会播放取消动画。这适用于服务器强制执行的动作（逮捕动画、脚本过场动画），玩家中断会破坏流程。

是否支持 ox_lib 动画？

是的。Agency-ProgressBar与动画无关，您在自己的脚本中处理动画，与进度条调用并行。进度条纯粹是UI元素。可独立搭配任何动画库或原生FiveM动画调用。

需求

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

实用集成示例

以下是将 Agency-ProgressBar 集成到现有脚本中的常见模式：

开锁： 呼叫 Play({label = 'Picking lock...', duration = 8000, canCancel = true, onCancel = cleanupFunction}) 在开锁尝试开始时。与并行运行的开锁小游戏配合使用。若小游戏失败，调用Dismiss()并传入返回的ID。成功则让进度条自然完成。

医疗治疗： 使用 target = {type = 'entity', id = patientNetId} 将进度条锚定在患者上方而非医护人员头顶。观看场景的玩家会看到治疗点的进度，而不是悬浮在医护人员头顶。

证据收集： 设置 canCancel = false 用于不可中断的脚本证据收集（防止玩家取消以避免现场留指纹）。不可取消的进度条向玩家传达此操作为强制执行，非可选。

服务器端操作： 客户端显示进度条，服务器端异步执行操作。服务器回调返回时，根据结果让进度条完成或提前关闭。视觉持续时间应大致匹配服务器处理时间。