fivem-nui

FiveM NUI

用于 FiveM 的 HTML/CSS/JS 界面：清单设置、Lua 到浏览器的消息、NUI 回调和焦点处理。

激活条件

当用户要求创建或编辑 FiveM UI、在资源中编写 HTML/CSS/JS、设置 ui_page，或询问 SendNUIMessage、SetNUIFocus 或 RegisterNUICallback 时，加载此技能。

硬性规则

• 在 fxmanifest.lua 中声明 ui_page，并将每个 UI 文件都加入 files；缺少文件会导致加载失败，且不会显示任何提示。
• 使用 https://cfx-nui-<resource>/path 引用资源；nui:// 协议已弃用。
• RegisterNUICallback 处理程序必须始终调用 cb(...)（至少调用 cb({})），否则浏览器请求会一直挂起。
• 浏览器通过 fetch('https://' + GetParentResourceName() + '/<name>', { method: 'POST', body: JSON.stringify(...) }) 调用回调；URL 名称必须与注册名称完全一致。
• SetNUIFocus(keyboard, mouse)：关闭 UI 时务必调用 SetNUIFocus(false, false)。
• NUI 回调在客户端运行。先在客户端验证数据，然后在服务器上再次验证，再进行任何状态更改；绝不要信任 UI 发送的价格、数量或 ID。
• 尽量减少 SendNUIMessage 调用：批量发送更新，不要每帧都发送。
• 使用 F8 和 Chrome DevTools 进行调试；使用模拟模式在浏览器中测试页面。

决策条件

方向	机制
Lua 到浏览器	SendNUIMessage({ type = ..., data = ... }) + window.addEventListener('message')
浏览器到 Lua	使用 fetch POST 请求 https://<resource>/<callback> + RegisterNUICallback
浏览器需要服务器数据	回调 Lua 客户端，然后再调用服务器回调
显示 / 隐藏光标	SetNUIFocus(true, true) / SetNUIFocus(false, false)
仅键盘	SetNUIFocus(true, false)

执行步骤

1. 在清单中添加 ui_page 和 files（阅读 rules/setup.md）。
2. 构建 index.html、CSS 和 JS；监听按 type 区分的 message 事件。
3. 为 UI 可能请求的每个操作注册 Lua 回调；所有路径都必须调用 cb。
4. 在打开 / 关闭时管理焦点；处理 Escape 以关闭界面。
5. 将任何会更改状态的操作转发到服务器，并在那里进行验证。

输出要求

返回清单条目、HTML/CSS/JS 文件，以及包含回调和焦点处理的 Lua 客户端脚本。将安全相关逻辑保留在服务器上。

参考资料

• rules/setup.md — 文件夹布局、清单、构建工具、常见错误。
• rules/fullscreen-nui.md — SendNUIMessage、SetNUIFocus、焦点栈、资源、DevTools。
• rules/nui-callbacks.md — RegisterNUICallback、fetch、异步处理、错误、安全性。
• rules/best-practices.md — 性能、安全性、状态、错误处理、测试。
• rules/reference-links.md — 官方文档和原生函数参考。

上游文档：https://docs.fivem.net/docs/scripting-manual/nui-development/