Agency-ProgressBar：悄然提升每款脚本体验的界面细节

一个小脚本，巨大的影响

进度条在 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 是一款即插即用的实用工具，不依赖数据库。通过 Tebex 下载，将文件夹放入 resources 目录，然后添加 ensure agency-progressbar 到 server.cfg. 就这样。资源立即开始工作，任何脚本都可以在下一次重启时调用 exports API。

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

配置选项

打开 config.lua 调整默认值：

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

框架兼容性

Agency-ProgressBar 完全 standalone，不依赖任何框架。在 QBCore、ESX 和自定义服务器配置中，它的运行方式完全相同。唯一的集成接口是 exports API，没有共享全局变量、框架事件或权限检查。安装后，无论其他脚本来自何处，都可以直接调用。

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

进度条是 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 用于不可中断的脚本证据收集（防止玩家取消以避免现场留指纹）。不可取消的进度条向玩家传达此操作为强制执行，非可选。

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