> For the complete documentation index, see [llms.txt](https://ak-scripts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ak-scripts.gitbook.io/docs/yi-lai/markdown/gong-neng-mo-kuai-dao-chu/kuang-jia-qiao-jie-framework.md).

# 框架桥接（Framework）

## 🌉 Framework（框架桥接）模块导出文档

### 📋 概述

Framework 模块是 ak-lib 的框架桥接层，提供了对 ESX / QBCore / QBX / ox\_core 四大主流框架的统一抽象接口，让你的脚本无需关心底层框架差异。

### 🚀 导出方式

#### 方式 1：获取模块对象（推荐）⭐

```lua
local FW = exports['ak-lib']:Framework()
```

#### 方式 2：单独导出函数

```lua
local framework = exports['ak-lib']:GetFramework()
local player = exports['ak-lib']:GetPlayer(source)
local identifier = exports['ak-lib']:GetIdentifier(source)
```

#### 方式 3：获取模块对象（兼容写法）

```lua
local FW = exports['ak-lib']:FrameworkModule()
```

### 📖 可用导出

#### 模块对象方法

使用 `exports['ak-lib']:Framework()` 获取的对象包含以下方法：

<table><thead><tr><th width="206">方法</th><th>说明</th><th>参数</th><th>返回值</th></tr></thead><tbody><tr><td><code>GetFramework()</code></td><td>获取当前框架名称</td><td>-</td><td><code>"esx"</code> / <code>"qb"</code> / <code>"qbx"</code> / <code>"ox"</code> / <code>"none"</code></td></tr><tr><td><code>GetCore()</code></td><td>获取框架核心对象</td><td>-</td><td>框架原生对象（table）</td></tr><tr><td><code>GetPlayer(source)</code></td><td>获取玩家对象（服务端）</td><td><code>source</code> (number)</td><td>xPlayer / Player 对象</td></tr><tr><td><code>GetIdentifier(source)</code></td><td>获取玩家唯一标识符（服务端）</td><td><code>source</code> (number)</td><td>string (license)</td></tr><tr><td><code>GetPlayerName(source)</code></td><td>获取玩家角色名（服务端）</td><td><code>source</code> (number)</td><td><code>{firstname, lastname, fullname}</code></td></tr><tr><td><code>GetMoney(source, type)</code></td><td>获取玩家金钱（服务端）</td><td><code>source</code> (number), <code>type</code> (string)</td><td>number</td></tr><tr><td><code>AddMoney(source, type, amount, reason)</code></td><td>添加金钱（服务端）</td><td><code>source</code>, <code>type</code>, <code>amount</code>, <code>reason</code></td><td>boolean</td></tr><tr><td><code>RemoveMoney(source, type, amount, reason)</code></td><td>移除金钱（服务端）</td><td><code>source</code>, <code>type</code>, <code>amount</code>, <code>reason</code></td><td>boolean</td></tr><tr><td><code>GetJob(source)</code></td><td>获取玩家职业（服务端）</td><td><code>source</code> (number)</td><td><code>{name, grade, label}</code></td></tr><tr><td><code>HasJob(source, job, grade)</code></td><td>检查玩家职业（服务端）</td><td><code>source</code>, <code>job</code> (string), <code>grade</code> (number, 可选)</td><td>boolean</td></tr><tr><td><code>SetJob(source, job, grade)</code></td><td>设置玩家职业（服务端）</td><td><code>source</code>, <code>job</code> (string), <code>grade</code> (number)</td><td>boolean</td></tr><tr><td><code>GetGang(source)</code></td><td>获取玩家帮派（服务端）</td><td><code>source</code> (number)</td><td><code>{name, grade, label}</code></td></tr><tr><td><code>HasGang(source, gang, grade)</code></td><td>检查玩家帮派（服务端）</td><td><code>source</code>, <code>gang</code> (string), <code>grade</code> (number, 可选)</td><td>boolean</td></tr><tr><td><code>IsAdmin(source)</code></td><td>检查是否为管理员（服务端）</td><td><code>source</code> (number)</td><td>boolean</td></tr><tr><td><code>HasPermission(source, permission)</code></td><td>检查权限（服务端）</td><td><code>source</code>, <code>permission</code> (string)</td><td>boolean</td></tr><tr><td><code>GetPermissionGroup(source)</code></td><td>获取权限组（服务端）</td><td><code>source</code> (number)</td><td>string</td></tr><tr><td><code>GetInventoryName()</code></td><td>获取库存系统名称（服务端）</td><td>-</td><td>string</td></tr><tr><td><code>GetItem(source, item)</code></td><td>获取物品数量（服务端）</td><td><code>source</code>, <code>item</code> (string)</td><td>number</td></tr><tr><td><code>HasItem(source, item, count)</code></td><td>检查物品（服务端）</td><td><code>source</code>, <code>item</code>, <code>count</code> (number, 可选)</td><td>boolean</td></tr><tr><td><code>AddItem(source, item, count, metadata)</code></td><td>添加物品（服务端）</td><td><code>source</code>, <code>item</code>, <code>count</code>, <code>metadata</code> (可选)</td><td>boolean / number</td></tr><tr><td><code>RemoveItem(source, item, count, metadata)</code></td><td>移除物品（服务端）</td><td><code>source</code>, <code>item</code>, <code>count</code>, <code>metadata</code> (可选)</td><td>boolean / number</td></tr><tr><td><code>RegisterCallback(name, cb)</code></td><td>注册回调（服务端）</td><td><code>name</code> (string), <code>cb</code> (function)</td><td>boolean</td></tr></tbody></table>

#### 单独导出函数

以下函数可以直接通过 `exports` 调用：

| 导出                                  | 说明       | 参数                        | 返回值     |
| ----------------------------------- | -------- | ------------------------- | ------- |
| `GetFramework()`                    | 获取当前框架名称 | -                         | string  |
| `GetCore()`                         | 获取框架核心对象 | -                         | table   |
| `GetPlayer(source)`                 | 获取玩家对象   | `source`                  | object  |
| `GetIdentifier(source)`             | 获取玩家标识符  | `source`                  | string  |
| `GetPlayerName(source)`             | 获取玩家名字   | `source`                  | table   |
| `GetJob(source)`                    | 获取玩家职业   | `source`                  | table   |
| `HasJob(source, job, grade)`        | 检查玩家职业   | `source`, `job`, `grade`  | boolean |
| `SetJob(source, job, grade)`        | 设置玩家职业   | `source`, `job`, `grade`  | boolean |
| `GetGang(source)`                   | 获取玩家帮派   | `source`                  | table   |
| `HasGang(source, gang, grade)`      | 检查玩家帮派   | `source`, `gang`, `grade` | boolean |
| `IsAdmin(source)`                   | 检查是否为管理员 | `source`                  | boolean |
| `HasPermission(source, permission)` | 检查权限     | `source`, `permission`    | boolean |
| `GetPermissionGroup(source)`        | 获取权限组    | `source`                  | string  |
| `RegisterCallback(name, cb)`        | 注册回调     | `name`, `cb`              | boolean |

### 💡 使用示例

#### 基础使用

```lua
-- 推荐方式：获取模块对象
local FW = exports['ak-lib']:Framework()

-- 获取框架信息
local frameworkName = FW.GetFramework()
print("当前框架:", frameworkName)  -- 输出: "qb" / "esx" / "qbx" / "ox"

-- 获取框架核心对象（需要直接访问框架 API 时使用）
local core = FW.GetCore()
```

#### 玩家信息

```lua
local FW = exports['ak-lib']:Framework()

-- 获取玩家对象
local player = FW.GetPlayer(source)

-- 获取玩家标识符
local identifier = FW.GetIdentifier(source)
print("玩家标识符:", identifier)

-- 获取玩家名字
local nameData = FW.GetPlayerName(source)
print(string.format("玩家姓名: %s %s (%s)", 
    nameData.firstname, 
    nameData.lastname, 
    nameData.fullname))
```

#### 金钱操作

```lua
local FW = exports['ak-lib']:Framework()

-- 获取玩家金钱
local cash = FW.GetMoney(source, 'cash')
local bank = FW.GetMoney(source, 'bank')

-- 添加金钱
FW.AddMoney(source, 'cash', 1000, '任务奖励')

-- 移除金钱
FW.RemoveMoney(source, 'cash', 500, '购买物品')
```

#### 职业系统

```lua
local FW = exports['ak-lib']:Framework()

-- 获取玩家职业
local job = FW.GetJob(source)
print(string.format("职业: %s (等级: %d)", job.name, job.grade))

-- 检查职业
if FW.HasJob(source, 'police', 2) then
    print("玩家是警察，等级 >= 2")
end

-- 设置职业
FW.SetJob(source, 'police', 3)
```

#### 帮派系统

```lua
local FW = exports['ak-lib']:Framework()

-- 获取帮派
local gang = FW.GetGang(source)

-- 检查帮派
if FW.HasGang(source, 'ballas') then
    print("玩家是 Ballas 帮派成员")
end
```

#### 权限系统

```lua
local FW = exports['ak-lib']:Framework()

-- 检查是否为管理员
if FW.IsAdmin(source) then
    print("玩家是管理员")
end

-- 检查权限
if FW.HasPermission(source, 'admin.kick') then
    -- 允许踢人
end

-- 获取权限组
local group = FW.GetPermissionGroup(source)
print("权限组:", group)
```

#### 物品操作

```lua
local FW = exports['ak-lib']:Framework()

-- 获取物品数量
local count = FW.GetItem(source, 'bread')
print("面包数量:", count)

-- 检查物品
if FW.HasItem(source, 'bread', 1) then
    print("玩家有至少 1 个面包")
end

-- 添加物品
FW.AddItem(source, 'bread', 5)

-- 移除物品
FW.RemoveItem(source, 'bread', 2)
```

#### 回调注册

```lua
local FW = exports['ak-lib']:Framework()

-- 注册回调（推荐使用 Callback 模块，这里仅作演示）
FW.RegisterCallback('shop:getPrice', function(source, itemName)
    return Items[itemName] and Items[itemName].price or 0
end)
```

### ⚠️ 注意事项

1. **推荐使用模块对象方式**：使用 `exports['ak-lib']:Framework()` 获取对象，代码更清晰，功能更完整。
2. **服务端专用**：大部分功能只能在服务端使用（除 `GetFramework()` 和 `GetCore()` 外）。
3. **初始化时机**：框架检测需要时间，建议在资源启动后等待几秒再使用。
4. **统一接口优势**：`Framework()` 返回的对象整合了 Framework 和 Inventory 的功能，推荐使用统一接口。
5. **防御性编程**：所有函数都包含参数检查，未初始化时返回安全默认值。
6. **框架检测**：如果未检测到任何框架，`GetFramework()` 返回 `"none"`。
7. **库存系统整合**：通过 `Framework()` 获取的对象可以直接使用 `GetItem()`, `AddItem()` 等方法，无需单独调用 Inventory 模块。

### 🔗 相关文档

* 框架桥接说明
* 库存系统说明
* Callback 模块导出文档


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ak-scripts.gitbook.io/docs/yi-lai/markdown/gong-neng-mo-kuai-dao-chu/kuang-jia-qiao-jie-framework.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.