> 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/ui-mo-kuai-dao-chu/jing-xiang-cai-dan-radial.md).

# 径向菜单（Radial）

## 🧭 Radial（环形菜单）模块导出文档

### 📋 概述

Radial 模块是 ak-lib 的环形菜单系统，支持快捷键、动态菜单、队列显示、多层级子菜单、权限控制等功能。

### 🚀 导出方式

#### 客户端

```lua
exports['ak-lib']:Radial(data)
exports['ak-lib']:CloseRadial()
exports['ak-lib']:IsRadialOpen()
exports['ak-lib']:GetCurrentRadial()
exports['ak-lib']:RegisterRadial(id, data)
exports['ak-lib']:UnregisterRadial(id)
exports['ak-lib']:GetRegisteredRadials()
exports['ak-lib']:RegisterRadialKey(key, data)
exports['ak-lib']:UnregisterRadialKey(key)
```

#### 服务端

```lua
exports['ak-lib']:Radial(target, data)
exports['ak-lib']:CloseRadial(target)
exports['ak-lib']:RegisterRadial(target, id, data)
exports['ak-lib']:UnregisterRadial(target, id)
```

### 📖 可用导出

#### 客户端

| 导出                             | 说明         | 参数                             | 返回值                   |
| ------------------------------ | ---------- | ------------------------------ | --------------------- |
| `Radial(data)`                 | 显示环形菜单     | `data` (table)                 | boolean               |
| `CloseRadial()`                | 关闭环形菜单     | -                              | boolean               |
| `IsRadialOpen()`               | 检查环形菜单是否打开 | -                              | boolean, table (当前数据) |
| `GetCurrentRadial()`           | 获取当前环形菜单数据 | -                              | table / nil           |
| `RegisterRadial(id, data)`     | 注册菜单（动态）   | `id` (string), `data` (table)  | boolean               |
| `UnregisterRadial(id)`         | 取消注册菜单     | `id` (string)                  | boolean               |
| `GetRegisteredRadials()`       | 获取所有已注册的菜单 | -                              | table                 |
| `RegisterRadialKey(key, data)` | 注册按键绑定     | `key` (string), `data` (table) | boolean               |
| `UnregisterRadialKey(key)`     | 取消按键绑定     | `key` (string)                 | boolean               |

#### 服务端

| 导出                                 | 说明          | 参数                                               | 返回值 |
| ---------------------------------- | ----------- | ------------------------------------------------ | --- |
| `Radial(target, data)`             | 向指定玩家显示环形菜单 | `target` (number), `data` (table)                | nil |
| `CloseRadial(target)`              | 关闭指定玩家的环形菜单 | `target` (number)                                | nil |
| `RegisterRadial(target, id, data)` | 向指定玩家注册菜单   | `target` (number), `id` (string), `data` (table) | nil |
| `UnregisterRadial(target, id)`     | 取消指定玩家的菜单注册 | `target` (number), `id` (string)                 | nil |

### 💡 使用示例

#### 客户端：基础使用

```lua
-- 基础环形菜单
exports['ak-lib']:Radial({
    id = "simple_menu",
    title = "简单菜单",
    items = {
        {
            id = "option1",
            title = "选项 1",
            icon = "fa-solid fa-check",
            type = "client",
            event = "my-script:option1"
        },
        {
            id = "option2",
            title = "选项 2",
            icon = "fa-solid fa-star",
            type = "client",
            event = "my-script:option2"
        }
    }
})

-- 带子菜单
exports['ak-lib']:Radial({
    id = "menu_with_submenu",
    title = "主菜单",
    items = {
        {
            id = "submenu1",
            title = "子菜单 1",
            icon = "fa-solid fa-folder",
            items = {
                {
                    id = "sub1_option1",
                    title = "子选项 1",
                    icon = "fa-solid fa-file",
                    type = "client",
                    event = "my-script:sub1_option1"
                }
            }
        }
    }
})

-- 权限控制
exports['ak-lib']:Radial({
    id = "permission_menu",
    title = "权限菜单",
    items = {
        {
            id = "admin_only",
            title = "管理员选项",
            icon = "fa-solid fa-user-shield",
            condition = function()
                -- 权限检查逻辑
                return IsPlayerAdmin()
            end,
            type = "client",
            event = "my-script:admin_action"
        }
    }
})

-- 条件显示
exports['ak-lib']:Radial({
    id = "conditional_menu",
    title = "条件菜单",
    items = {
        {
            id = "in_vehicle",
            title = "载具选项",
            icon = "fa-solid fa-car",
            condition = function()
                return IsPedInAnyVehicle(PlayerPedId(), false)
            end,
            type = "client",
            event = "my-script:vehicle_action"
        }
    }
})

-- 禁用选项
exports['ak-lib']:Radial({
    id = "disabled_menu",
    title = "菜单",
    items = {
        {
            id = "disabled_option",
            title = "禁用选项",
            icon = "fa-solid fa-ban",
            disabled = true,
            disabledReason = "需要等级 10"
        }
    }
})

-- 服务端事件
exports['ak-lib']:Radial({
    id = "server_menu",
    title = "服务端菜单",
    items = {
        {
            id = "server_action",
            title = "服务端操作",
            icon = "fa-solid fa-server",
            type = "server",
            event = "my-script:server_action",
            args = { arg1 = "value1" }
        }
    }
})

-- 注册菜单（动态注册）
exports['ak-lib']:RegisterRadial("my_menu", {
    id = "my_menu",
    title = "动态菜单",
    items = {
        {
            id = "option1",
            title = "选项 1",
            type = "client",
            event = "my-script:option1"
        }
    }
})

-- 使用已注册的菜单
exports['ak-lib']:Radial({
    id = "my_menu"  -- 使用已注册的菜单 ID
})

-- 取消注册
exports['ak-lib']:UnregisterRadial("my_menu")

-- 获取所有已注册的菜单
local registered = exports['ak-lib']:GetRegisteredRadials()
for id, menu in pairs(registered) do
    print("已注册菜单:", id)
end

-- 注册按键绑定
exports['ak-lib']:RegisterRadialKey("F1", {
    id = "quick_menu",
    title = "快速菜单",
    items = {
        {
            id = "quick_action",
            title = "快速操作",
            type = "client",
            event = "my-script:quick_action"
        }
    }
})

-- 取消按键绑定
exports['ak-lib']:UnregisterRadialKey("F1")

-- 检查环形菜单是否打开
local isOpen, data = exports['ak-lib']:IsRadialOpen()
if isOpen then
    print("环形菜单已打开")
end

-- 关闭环形菜单
exports['ak-lib']:CloseRadial()
```

#### 服务端：向玩家发送环形菜单

```lua
-- 向指定玩家显示环形菜单
exports['ak-lib']:Radial(source, {
    id = "server_menu",
    title = "服务端菜单",
    items = {
        {
            id = "option1",
            title = "选项 1",
            type = "server",
            event = "my-script:option1"
        }
    }
})

-- 关闭指定玩家的环形菜单
exports['ak-lib']:CloseRadial(source)

-- 注册菜单
exports['ak-lib']:RegisterRadial(source, "my_menu", {
    id = "my_menu",
    title = "动态菜单",
    items = {}
})
```

### 📝 参数说明

#### data 参数（table）

| 字段         | 类型       | 说明          | 必需  | 默认值                      |
| ---------- | -------- | ----------- | --- | ------------------------ |
| `id`       | string   | 菜单 ID（唯一标识） | ✅ 是 | -                        |
| `title`    | string   | 菜单标题        | 否   | `'环形菜单'`                 |
| `items`    | table\[] | 菜单项列表       | ✅ 是 | -                        |
| `position` | string   | 位置（九宫格）     | 否   | `Config.Radial.Position` |
| `queue`    | boolean  | 是否启用队列      | 否   | `Config.Radial.Queue`    |

#### item 参数（table）

| 字段               | 类型       | 说明                                         | 必需  | 默认值     |
| ---------------- | -------- | ------------------------------------------ | --- | ------- |
| `id`             | string   | 菜单项 ID                                     | ✅ 是 | -       |
| `title`          | string   | 菜单项标题                                      | ✅ 是 | -       |
| `icon`           | string   | FontAwesome 图标类名                           | 否   | -       |
| `type`           | string   | 事件类型：`'client'` / `'server'` / `'command'` | 否   | -       |
| `event`          | string   | 事件名称（type 不为空时）                            | 否   | -       |
| `args`           | any      | 事件参数                                       | 否   | -       |
| `items`          | table\[] | 子菜单项列表                                     | 否   | -       |
| `condition`      | function | 条件函数（返回 boolean）                           | 否   | -       |
| `disabled`       | boolean  | 是否禁用                                       | 否   | `false` |
| `disabledReason` | string   | 禁用原因                                       | 否   | -       |
| `shouldClose`    | boolean  | 选择后是否关闭菜单                                  | 否   | `true`  |

#### 位置选项（position）

支持九宫格位置（默认：`'middle-center'`）：

* `'top-left'` - 左上角
* `'top-center'` - 顶部中间
* `'top-right'` - 右上角
* `'middle-left'` - 左边中间
* `'middle-center'` - 屏幕中央（默认）
* `'middle-right'` - 右边中间
* `'bottom-left'` - 左下角
* `'bottom-center'` - 底部中间
* `'bottom-right'` - 右下角

### ⚠️ 注意事项

1. **id 必需**：`id` 字段是必需的，用于唯一标识菜单。
2. **items 必需**：`items` 字段是必需的，至少包含一个菜单项。
3. **同时只能显示一个**：Radial 同时只能显示一个，新的会根据 `queue` 设置决定是否排队。
4. **队列机制**：如果当前有环形菜单打开且 `queue = true`，新的菜单会自动排队。
5. **子菜单**：支持多层嵌套子菜单，理论上可以无限层级。
6. **条件函数**：`condition` 函数用于权限控制和条件显示，返回 `true` 时显示，返回 `false` 时隐藏。
7. **动态注册**：可以使用 `RegisterRadial()` 动态注册菜单，后续可以通过 ID 直接使用。
8. **按键绑定**：可以使用 `RegisterRadialKey()` 绑定按键，按指定键时自动打开对应的菜单。
9. **服务端调用**：服务端调用时需要提供 `target` 参数（玩家服务器 ID）。
10. **事件触发**：使用 `type` 和 `event` 可以直接触发客户端/服务端事件，无需额外处理。

### 🔗 相关文档

* 环形菜单说明


---

# 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/ui-mo-kuai-dao-chu/jing-xiang-cai-dan-radial.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.