Skip to content

Developer API

Developer API

由于 BUPA Chat provide 'chat'，它实现了标准 FiveM chat API。任何已经使用 chat:addMessage、chat:addSuggestion 等的代码库都可以继续正常运行，无需修改。BUPA Chat 将这些 API 同时公开为网络事件（chat:<name>）和导出函数（采用 lowercase 和 Capitalized 格式）。

API 接口注册在 utils/chat.lua 中：

utils/chat.lua
registerEvent("addMessage", chatUtility.addMessage)
registerEvent("addSuggestion", chatUtility.addSuggestion)
registerEvent("addSuggestions", chatUtility.addSuggestions)
registerEvent("removeSuggestion", chatUtility.removeSuggestion)
registerEvent("removeSuggestions", chatUtility.removeSuggestions)
registerEvent("clear", chatUtility.clearMessages)

registerEvent 会关联事件 chat:<name>，以及 exports(name) 和 exports(Name)，因此下面三种调用方式是完全等效的。

添加聊天消息

在客户端，直接将消息推送到聊天框中：

client
-- 标准事件（适用于任何资源）
TriggerEvent("chat:addMessage", {
    color = { 255, 0, 0 },
    multiline = true,
    args = { "Dispatch", "A robbery is in progress downtown." },
})

-- 导出函数形式
exports.chat:addMessage({ args = { "System", "Server restarting soon." } })

消息结构：

字段 类型 描述
args table 消息内容部分。在启用 config.defaultAddTag 的情况下，如果参数多于一个且没有指定 tags，则第一个参数将成为标签，其余部分为正文
color RGB 消息 / 第一个标签的颜色 { r, g, b }
tags table[] 显式标签 { tag, bgColor, textColor }
multiline boolean 允许消息换行显示

经典的 chatMessage 客户端事件也得到了支持（name, color, message），因此旧版的 TriggerClientEvent('chatMessage', ...) 输出依然可以正常显示。

建议

建议（Suggestions）驱动着命令自动补全面板。它们可以逐个添加或批量添加，也可以用同样的方式移除。

client
TriggerEvent("chat:addSuggestion", "/revive", "Revive a nearby player", {
    { name = "id", help = "Server ID of the target" },
})

TriggerEvent("chat:addSuggestions", {
    { name = "/heal", help = "Heal yourself" },
    { name = "/car",  help = "Spawn a vehicle", params = {
        { name = "model", help = "Vehicle model", optional = true },
    } },
})

TriggerEvent("chat:removeSuggestion", "/car")
exports.chat:clear()   -- 清除所有消息
ℹ

BUPA Chat 会在加载时以及每次资源启动/停止时，自动从玩家拥有 ACE 权限（command.<name>）的所有已注册命令中提取并填充建议。你只需要针对需要自定义帮助文本或参数的命令使用 chat:addSuggestion(s)。

通知

BUPA Chat 提供了一个名为 <resource>:notify（即 bupa-chat:notify）的通知事件，由 ox_lib 的 lib.notify 提供支持。它在客户端和服务器端均可使用。

server
-- 通知单个玩家（服务器 -> 客户端）：source，然后是 Notify 参数
TriggerClientEvent("bupa-chat:notify", targetSrc, "MY_LOCALE_KEY", "success", 4000)
client
TriggerEvent("bupa-chat:notify", "MY_LOCALE_KEY", "error", 5000)

处理程序为 Notify(text, notifyType, duration, ...)。text 会通过 t() 本地化包装器进行处理，因此你可以传入一个本地化键（带格式化参数）或纯文本。notifyType 默认为 inform，duration 默认为 4000 毫秒。

本地化助手

资源内部（以及在其上下文中加载的文件）可以使用以下全局变量：

符号 描述
t(key, ...) ox_lib locale() 的精简包装器。使用 %s/%d 参数进行格式化，如果找不到翻译则返回键名本身
GetLang() 返回当前扁平化的本地化字典
Notify(text, type, duration, ...) 触发 bupa-chat:notify 通知

运行时语言切换 — bupa:changeLanguage

触发此客户端事件可实时更改玩家的聊天语言，无需重启。它会重新加载本地化语言并将其推送到 React UI：

client
TriggerEvent("bupa:changeLanguage", "fr")

详情请参阅 Localization。

PreviousDiscord LoggingNext Localization