> 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/dui-hua-kuang-dialog.md).

# 对话框（Dialog）

## 💬 Dialog（对话框）模块导出文档

### 📋 概述

Dialog 模块是 ak-lib 的对话框系统，支持确认/取消、超时回调、队列机制、多按钮选择等功能。

### 🚀 导出方式

#### 客户端

```lua
exports['ak-lib']:Dialog(data, callback)
exports['ak-lib']:OpenDialog(data, callback)
exports['ak-lib']:CloseDialog()
exports['ak-lib']:IsDialogOpen()
exports['ak-lib']:GetCurrentDialog()
```

#### 服务端

```lua
exports['ak-lib']:Dialog(target, data, callback)
exports['ak-lib']:OpenDialog(target, data, callback)
```

### 📖 可用导出

#### 客户端

| 导出                           | 说明        | 参数                                    | 返回值                   |
| ---------------------------- | --------- | ------------------------------------- | --------------------- |
| `Dialog(data, callback)`     | 显示对话框     | `data` (table), `callback` (function) | boolean               |
| `OpenDialog(data, callback)` | 显示对话框（别名） | `data` (table), `callback` (function) | boolean               |
| `CloseDialog()`              | 关闭对话框     | -                                     | boolean               |
| `IsDialogOpen()`             | 检查对话框是否打开 | -                                     | boolean, table (当前数据) |
| `GetCurrentDialog()`         | 获取当前对话框数据 | -                                     | table / nil           |

#### 服务端

| 导出                                   | 说明             | 参数                                                       | 返回值 |
| ------------------------------------ | -------------- | -------------------------------------------------------- | --- |
| `Dialog(target, data, callback)`     | 向指定玩家显示对话框     | `target` (number), `data` (table), `callback` (function) | nil |
| `OpenDialog(target, data, callback)` | 向指定玩家显示对话框（别名） | `target` (number), `data` (table), `callback` (function) | nil |

### 💡 使用示例

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

```lua
-- 基础确认/取消对话框
exports['ak-lib']:Dialog({
    title = "确认操作",
    message = "你确定要继续吗？"
}, function(result)
    if result == true then
        print("用户选择了确认")
    elseif result == false then
        print("用户选择了取消")
    else
        print("对话框超时")
    end
end)

-- 自定义按钮文本
exports['ak-lib']:Dialog({
    title = "删除确认",
    message = "确定要删除这个物品吗？此操作不可撤销。",
    yes = "确认删除",
    no = "取消"
}, function(result)
    if result == true then
        -- 用户点击了"确认删除"
        DeleteItem(itemId)
    end
end)

-- 超时功能
exports['ak-lib']:Dialog({
    title = "操作确认",
    message = "请在 5 秒内做出选择",
    timeout = 5000  -- 5 秒后自动关闭
}, function(result)
    if result == nil then
        print("对话框超时")
    elseif result == true then
        print("用户选择了确认")
    else
        print("用户选择了取消")
    end
end)

-- 队列支持（多个对话框自动排队）
exports['ak-lib']:Dialog({
    title = "第一个对话框",
    message = "这是第一个对话框",
    queue = true  -- 启用队列
}, function(result)
    print("第一个对话框结果:", result)
end)

exports['ak-lib']:Dialog({
    title = "第二个对话框",
    message = "这是第二个对话框（会自动排队）",
    queue = true
}, function(result)
    print("第二个对话框结果:", result)
end)

-- 多按钮选择
exports['ak-lib']:Dialog({
    title = "选择操作",
    message = "请选择一个操作",
    buttons = {
        { label = "选项 1", value = "option1" },
        { label = "选项 2", value = "option2" },
        { label = "选项 3", value = "option3" }
    }
}, function(result)
    if result then
        print("选择了:", result)
    end
end)

-- 检查对话框是否打开
local isOpen, data = exports['ak-lib']:IsDialogOpen()
if isOpen then
    print("对话框已打开")
end

-- 关闭对话框
exports['ak-lib']:CloseDialog()
```

#### 服务端：向玩家发送对话框

```lua
-- 向指定玩家显示对话框
exports['ak-lib']:Dialog(source, {
    title = "确认操作",
    message = "你确定要继续吗？"
}, function(result)
    if result == true then
        print("玩家选择了确认")
    elseif result == false then
        print("玩家选择了取消")
    else
        print("对话框超时")
    end
end)
```

### 📝 参数说明

#### data 参数（table）

| 字段         | 类型       | 说明                 | 必需  | 默认值                      |
| ---------- | -------- | ------------------ | --- | ------------------------ |
| `title`    | string   | 对话框标题              | ✅ 是 | -                        |
| `message`  | string   | 对话框消息              | ✅ 是 | -                        |
| `yes`      | string   | 确认按钮文本             | 否   | `'是'`                    |
| `no`       | string   | 取消按钮文本             | 否   | `'否'`                    |
| `buttons`  | table\[] | 多按钮列表              | 否   | -                        |
| `timeout`  | number   | 超时时间（毫秒），0 = 不超时   | 否   | `Config.Dialog.Timeout`  |
| `queue`    | boolean  | 是否启用队列             | 否   | `Config.Dialog.Queue`    |
| `position` | string   | 位置（九宫格）            | 否   | `Config.Dialog.Position` |
| `icon`     | string   | 对话框图标（FontAwesome） | 否   | -                        |

#### button 参数（table）

多按钮模式下的按钮配置：

| 字段      | 类型     | 说明                | 必需  |
| ------- | ------ | ----------------- | --- |
| `label` | string | 按钮文本              | ✅ 是 |
| `value` | any    | 按钮值（回调时返回）        | 否   |
| `icon`  | string | 按钮图标（FontAwesome） | 否   |

#### callback 回调函数

```lua
function(result)
    -- result: true / false / any / nil
    -- true: 用户点击了确认按钮（或第一个按钮）
    -- false: 用户点击了取消按钮（或最后一个按钮）
    -- any: 多按钮模式下返回按钮的 value
    -- nil: 对话框超时
end
```

#### 位置选项（position）

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

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

### ⚠️ 注意事项

1. **title 和 message 必需**：`title` 和 `message` 字段都是必需的。
2. **同时只能显示一个**：Dialog 同时只能显示一个，新的会根据 `queue` 设置决定是否排队。
3. **队列机制**：如果当前有对话框打开且 `queue = true`，新的对话框会自动排队，等待当前对话框关闭后显示。
4. **超时处理**：如果设置了 `timeout`，对话框会在指定时间后自动关闭，回调函数会收到 `nil`。
5. **多按钮模式**：使用 `buttons` 字段可以创建多按钮对话框，回调函数返回按钮的 `value`。
6. **按钮文本本地化**：按钮文本支持本地化，可以通过 `yes`、`no` 或 `locale` 字段设置。
7. **服务端调用**：服务端调用时需要提供 `target` 参数（玩家服务器 ID）。
8. **返回值**：客户端 `Dialog()` 返回 boolean（是否成功打开）。

### 🔗 相关文档

* 对话框说明


---

# 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/dui-hua-kuang-dialog.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.