> 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/jiao-hu-mu-biao-target.md).

# 交互目标（Target）

## 🎯 Target（交互目标）模块导出文档

### 📋 概述

Target 模块是 ak-lib 的交互系统桥接层，提供了对 ox\_target 和 qb-target 的统一抽象接口。Target 系统本质是客户端能力，因此核心 API 都在客户端模块中。

### 🚀 导出方式

#### 客户端

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

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

**方式 2：获取模块对象（兼容写法）**

```lua
local Target = exports['ak-lib']:TargetModule()
```

**方式 3：单独导出函数**

```lua
local targetName = exports['ak-lib']:GetTargetName()
```

### 📖 可用导出

#### 客户端

**模块对象方法**

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

| 方法                                      | 说明               | 参数                                                                             | 返回值                                                  |
| --------------------------------------- | ---------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `GetName()`                             | 获取 Target 系统名称   | -                                                                              | string (`'ox_target'` / `'qb-target'` / `'unknown'`) |
| `IsAvailable()`                         | 检查 Target 系统是否可用 | -                                                                              | boolean                                              |
| `GetTarget()`                           | 获取底层 Target 系统对象 | -                                                                              | object / nil                                         |
| `AddEntity(entity, options)`            | 添加实体 Target      | `entity` (number), `options` (table)                                           | boolean                                              |
| `AddModel(model, options)`              | 添加模型 Target      | `model` (string / number), `options` (table)                                   | boolean                                              |
| `AddBoxZone(id, coords, size, options)` | 添加区域 Target      | `id` (string), `coords` (vector3), `size` (vector3 / table), `options` (table) | boolean                                              |
| `RemoveEntity(entity)`                  | 移除实体 Target      | `entity` (number)                                                              | boolean                                              |
| `RemoveZone(id)`                        | 移除区域 Target      | `id` (string)                                                                  | boolean                                              |

**单独导出函数**

| 导出                                      | 说明                  | 参数                                | 返回值                 |
| --------------------------------------- | ------------------- | --------------------------------- | ------------------- |
| `Target()` / `TargetModule()`           | 返回模块对象              | -                                 | `AKTargetClient` 对象 |
| `GetTargetName()`                       | 获取 Target 系统名称      | -                                 | string              |
| `GetName()`                             | 同 `GetTargetName()` | -                                 | string              |
| `IsAvailable()`                         | 检查是否可用              | -                                 | boolean             |
| `GetTarget()`                           | 获取底层 Target 对象      | -                                 | object / nil        |
| `AddEntity(entity, options)`            | 添加实体 Target         | `entity`, `options`               | boolean             |
| `AddModel(model, options)`              | 添加模型 Target         | `model`, `options`                | boolean             |
| `AddBoxZone(id, coords, size, options)` | 添加区域 Target         | `id`, `coords`, `size`, `options` | boolean             |
| `RemoveEntity(entity)`                  | 移除实体 Target         | `entity`                          | boolean             |
| `RemoveZone(id)`                        | 移除区域 Target         | `id`                              | boolean             |

### 💡 使用示例

#### 基础使用

```lua
-- 客户端
local Target = exports['ak-lib']:Target()

-- 检查 Target 系统是否可用
if not Target.IsAvailable() then
    print("Target 系统不可用")
    return
end

-- 获取 Target 系统名称
local targetName = Target.GetName()
print("当前 Target 系统:", targetName)  -- 输出: "ox_target" 或 "qb-target"
```

#### 添加实体 Target

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

-- 添加实体 Target
local entity = GetPlayerPed(PlayerId())
Target.AddEntity(entity, {
    label = "开门",
    icon = "fa-solid fa-door-open",
    onSelect = function(data)
        TriggerServerEvent('myplugin:openDoor', data.entity)
    end
})

-- 带条件检查
Target.AddEntity(entity, {
    label = "修理车辆",
    icon = "fa-solid fa-wrench",
    canInteract = function(entity, distance, coords, name, bone)
        -- 只有距离小于 3 米时才能交互
        return distance < 3.0
    end,
    onSelect = function(data)
        TriggerServerEvent('myplugin:repairVehicle', data.entity)
    end,
    distance = 2.0  -- 交互距离（可选）
})
```

#### 添加模型 Target

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

-- 添加模型 Target（所有该模型的实体都会显示）
Target.AddModel('prop_atm_01', {
    label = "ATM",
    icon = "fa-solid fa-credit-card",
    onSelect = function(data)
        -- 打开 ATM UI
        TriggerServerEvent('bank:openATM')
    end
})

-- 添加载具模型
Target.AddModel('adder', {
    label = "超级跑车",
    icon = "fa-solid fa-car",
    onSelect = function(data)
        print("选择了超级跑车:", data.entity)
    end
})
```

#### 添加区域 Target

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

-- 添加区域 Target（BoxZone）
Target.AddBoxZone('shop_1', vector3(24.0, -1346.0, 29.5), vector3(2.0, 2.0, 2.0), {
    label = "商店",
    icon = "fa-solid fa-shop",
    onSelect = function(data)
        -- 打开商店
        TriggerServerEvent('shop:open', 'shop_1')
    end
})

-- 使用表格格式的 size
Target.AddBoxZone('warehouse', vector3(100.0, 200.0, 30.0), {x = 5.0, y = 5.0, z = 3.0}, {
    label = "仓库",
    icon = "fa-solid fa-warehouse",
    onSelect = function(data)
        TriggerServerEvent('warehouse:enter')
    end
})
```

#### 移除 Target

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

-- 移除实体 Target
local entity = GetPlayerPed(PlayerId())
Target.RemoveEntity(entity)

-- 移除区域 Target
Target.RemoveZone('shop_1')
```

#### options 参数说明

所有 Target 方法都接受 `options` 表，包含以下字段：

| 字段            | 类型       | 说明                 | 必需  |
| ------------- | -------- | ------------------ | --- |
| `label`       | string   | 显示的标签文本            | ✅ 是 |
| `icon`        | string   | 图标（FontAwesome 类名） | 否   |
| `onSelect`    | function | 选择时的回调函数           | ✅ 是 |
| `canInteract` | function | 是否可交互的检查函数         | 否   |
| `distance`    | number   | 交互距离（米）            | 否   |

**`onSelect` 回调参数：**

* `data` (table): 包含交互信息，通常包含 `entity`（实体 handle）等字段

**`canInteract` 回调参数：**

* `entity` (number): 实体 handle
* `distance` (number): 距离（米）
* `coords` (vector3): 坐标
* `name` (string): 名称
* `bone` (string): 骨骼名称（如果有）

**返回值：**

* `true`: 可以交互
* `false`: 不可以交互

#### 完整示例：商店系统

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

-- 创建商店区域
CreateThread(function()
    -- 添加商店区域
    Target.AddBoxZone('shop_1', vector3(24.0, -1346.0, 29.5), vector3(2.0, 2.0, 2.0), {
        label = "24/7 商店",
        icon = "fa-solid fa-shop",
        onSelect = function(data)
            TriggerServerEvent('shop:open', 'shop_1')
        end
    })
    
    -- 添加 NPC 实体（示例）
    local ped = CreatePed(4, GetHashKey('mp_m_shopkeep_01'), 24.0, -1346.0, 29.5, 0.0, false, true)
    Target.AddEntity(ped, {
        label = "和店主对话",
        icon = "fa-solid fa-comments",
        onSelect = function(data)
            TriggerServerEvent('shop:talkToOwner')
        end
    })
end)

-- 资源停止时清理
AddEventHandler('onResourceStop', function(resourceName)
    if GetCurrentResourceName() ~= resourceName then return end
    
    Target.RemoveZone('shop_1')
end)
```

### 📝 API 详细说明

#### 支持的 Target 系统

* **ox\_target**
* **qb-target**

#### 设计原则

Target 模块采用最低限度桥接原则：

1. **暴露 Target 类型**：提供 `GetName()` 和 `IsAvailable()` 函数
2. **统一入口函数**：提供统一的 API，内部处理不同系统的差异
3. **不保证 feature parity**：只支持 80% 公共功能（label, icon, onSelect, canInteract）

#### GetTarget() 使用

如果需要访问底层 Target 系统的原生功能（如 ox\_target 的 groups、qb-target 的 job 等），可以使用 `GetTarget()`：

```lua
local Target = exports['ak-lib']:Target()
local targetSystem = Target.GetTarget()

if Target.GetName() == 'ox_target' then
    -- 使用 ox_target 原生 API
    targetSystem.addModel('prop_atm_01', {
        groups = {'police'},
        -- ox_target 特定选项
    })
elseif Target.GetName() == 'qb-target' then
    -- 使用 qb-target 原生 API
    targetSystem:AddTargetModel('prop_atm_01', {
        options = {
            {
                job = 'police',
                -- qb-target 特定选项
            }
        }
    })
end
```

### ⚠️ 注意事项

1. **客户端模块**：Target 操作必须在客户端进行，服务端模块仅用于检测。
2. **动态访问**：使用 `GetName()` 等函数进行动态访问，避免静态赋值导致的异步问题。
3. **高级功能**：高级功能（如 ox\_target 的 groups/distance、qb-target 的 job）需要直接访问底层系统（使用 `GetTarget()`）。
4. **不支持的场景**：Target 模块不处理 job/gang 权限判断、money/item 校验、UI 行为等，这些应该在 `onSelect` 回调中处理。
5. **资源清理**：在资源停止时，建议移除所有添加的 Target，避免内存泄漏。
6. **性能考虑**：大量 Target 可能影响性能，建议合理使用。
7. **检查可用性**：在使用前检查 `IsAvailable()`，确保 Target 系统已加载。
8. **服务端检测**：服务端可以通过 `exports['ak-lib']:GetTargetName()` 检测 Target 系统，但只能检测，不能操作。

### 🔗 相关文档

* 交互目标说明
* Framework 模块导出文档


---

# 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/jiao-hu-mu-biao-target.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.