> 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/jin-du-tiao-progress.md).

# 进度条（Progress）

## ⏳ Progress（进度条）模块导出文档

### 📋 概述

Progress 模块是 ak-lib 的进度条系统，支持条形/圆形动画、道具绑定、动画播放、可取消等功能。

### 🚀 导出方式

#### 客户端

```lua
exports['ak-lib']:Progress(data)
exports['ak-lib']:StopProgress(reason)
exports['ak-lib']:IsProgressActive()
exports['ak-lib']:ReplaceProgress(data)
```

#### 服务端

```lua
exports['ak-lib']:Progress(target, data)
exports['ak-lib']:StopProgress(target)
```

### 📖 可用导出

#### 客户端

| 导出                      | 说明        | 参数                    | 返回值     |
| ----------------------- | --------- | --------------------- | ------- |
| `Progress(data)`        | 显示进度条     | `data` (table)        | boolean |
| `StopProgress(reason)`  | 停止进度条     | `reason` (string, 可选) | boolean |
| `IsProgressActive()`    | 检查进度条是否活动 | -                     | boolean |
| `ReplaceProgress(data)` | 替换当前进度条   | `data` (table)        | boolean |

#### 服务端

| 导出                       | 说明         | 参数                                | 返回值 |
| ------------------------ | ---------- | --------------------------------- | --- |
| `Progress(target, data)` | 向指定玩家显示进度条 | `target` (number), `data` (table) | nil |
| `StopProgress(target)`   | 停止指定玩家的进度条 | `target` (number)                 | nil |

### 💡 使用示例

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

```lua
-- 基础进度条
exports['ak-lib']:Progress({
    duration = 5000,
    label = "进行中..."
})

-- 带回调
exports['ak-lib']:Progress({
    duration = 5000,
    label = "修理车辆中...",
    onComplete = function()
        print("修理完成")
    end,
    onCancel = function()
        print("取消修理")
    end
})

-- 条形进度条（默认）
exports['ak-lib']:Progress({
    duration = 5000,
    label = "条形进度条",
    style = 'bar'
})

-- 圆形进度条
exports['ak-lib']:Progress({
    duration = 5000,
    label = "圆形进度条",
    style = 'circle'
})

-- 不可取消
exports['ak-lib']:Progress({
    duration = 5000,
    label = "重要操作中...",
    canCancel = false
})

-- 自定义取消键
exports['ak-lib']:Progress({
    duration = 5000,
    label = "操作中...",
    cancelKey = 73  -- X 键
})

-- 播放动画
exports['ak-lib']:Progress({
    duration = 5000,
    label = "修理中...",
    anim = {
        dict = "mini@repair",
        clip = "fixing_a_player",
        flag = 49
    }
})

-- 绑定道具
exports['ak-lib']:Progress({
    duration = 5000,
    label = "吃汉堡中...",
    prop = {
        model = "prop_cs_burger_01",
        bone = 60309,
        pos = { x = 0.02, y = 0.02, z = 0.02 },
        rot = { x = 0.0, y = 0.0, z = 0.0 }
    }
})

-- 禁用控制（防止移动、射击等）
exports['ak-lib']:Progress({
    duration = 5000,
    label = "操作中...",
    disable = {
        move = true,
        car = true,
        combat = true,
        mouse = false
    }
})

-- 中断条件
exports['ak-lib']:Progress({
    duration = 5000,
    label = "操作中...",
    useWhileDead = false,      -- 死亡时中断
    allowRagdoll = false,       -- 布娃娃状态时中断
    allowCuffed = false         -- 被铐时中断
})

-- 检查是否活动
if exports['ak-lib']:IsProgressActive() then
    print("进度条正在运行")
end

-- 停止进度条
exports['ak-lib']:StopProgress("操作被取消")

-- 替换进度条
exports['ak-lib']:Progress({
    duration = 3000,
    label = "第一阶段..."
})

Wait(2000)

exports['ak-lib']:ReplaceProgress({
    duration = 5000,
    label = "第二阶段..."
})
```

#### 服务端：向玩家发送进度条

```lua
-- 向指定玩家显示进度条
exports['ak-lib']:Progress(source, {
    duration = 5000,
    label = "处理中..."
})

-- 停止指定玩家的进度条
exports['ak-lib']:StopProgress(source)
```

### 📝 参数说明

#### data 参数（table）

| 字段             | 类型       | 说明                      | 必需  | 默认值                                  |
| -------------- | -------- | ----------------------- | --- | ------------------------------------ |
| `duration`     | number   | 持续时间（毫秒）                | ✅ 是 | -                                    |
| `label`        | string   | 进度条标签文本                 | 否   | `""`                                 |
| `style`        | string   | 样式：`'bar'` / `'circle'` | 否   | `Config.Progress.Style`              |
| `canCancel`    | boolean  | 是否允许取消                  | 否   | `Config.Progress.CanCancel`          |
| `cancelKey`    | number   | 取消键（GTA 键码）             | 否   | `Config.Progress.CancelKey` (73 = X) |
| `position`     | string   | 位置（九宫格）                 | 否   | `Config.Progress.Position`           |
| `anim`         | table    | 动画配置                    | 否   | -                                    |
| `prop`         | table    | 道具配置                    | 否   | -                                    |
| `disable`      | table    | 禁用控制配置                  | 否   | -                                    |
| `useWhileDead` | boolean  | 死亡时是否继续                 | 否   | `false`                              |
| `allowRagdoll` | boolean  | 布娃娃状态时是否继续              | 否   | `false`                              |
| `allowCuffed`  | boolean  | 被铐时是否继续                 | 否   | `false`                              |
| `onComplete`   | function | 完成时的回调                  | 否   | -                                    |
| `onCancel`     | function | 取消时的回调                  | 否   | -                                    |

#### anim 参数（table）

| 字段             | 类型      | 说明                 | 必需  |
| -------------- | ------- | ------------------ | --- |
| `dict`         | string  | 动画字典名称             | ✅ 是 |
| `clip`         | string  | 动画剪辑名称             | ✅ 是 |
| `flag`         | number  | 动画标志               | 否   |
| `blendIn`      | number  | 混合进入时间             | 否   |
| `blendOut`     | number  | 混合退出时间             | 否   |
| `duration`     | number  | 动画持续时间             | 否   |
| `playbackRate` | number  | 播放速度               | 否   |
| `scenario`     | string  | 场景名称（替代 dict/clip） | 否   |
| `playEnter`    | boolean | 是否播放进入动画           | 否   |

#### prop 参数（table / table\[]）

单个道具对象或道具数组：

| 字段                       | 类型             | 说明                  | 必需  |
| ------------------------ | -------------- | ------------------- | --- |
| `model`                  | string         | 道具模型名称              | ✅ 是 |
| `bone`                   | number         | 骨骼索引（默认 60309 = 右手） | 否   |
| `pos` / `x`, `y`, `z`    | table / number | 位置偏移                | 否   |
| `rot` / `rx`, `ry`, `rz` | table / number | 旋转偏移                | 否   |
| `rotOrder`               | number         | 旋转顺序                | 否   |

#### disable 参数（table）

| 字段       | 类型      | 说明      | 默认值     |
| -------- | ------- | ------- | ------- |
| `move`   | boolean | 禁用移动    | `false` |
| `car`    | boolean | 禁用载具控制  | `false` |
| `combat` | boolean | 禁用战斗/射击 | `false` |
| `mouse`  | boolean | 禁用鼠标    | `false` |

#### 位置选项（position）

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

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

### ⚠️ 注意事项

1. **duration 必需**：`duration` 字段是必需的。
2. **同时只能显示一个**：Progress 同时只能显示一个，新的会替换旧的。
3. **ReplaceProgress**：使用 `ReplaceProgress()` 可以无缝替换当前进度条，不会中断。
4. **中断条件**：当满足中断条件（死亡、布娃娃状态、被铐等）时，进度条会自动停止并触发 `onCancel` 回调。
5. **回调函数**：`onComplete` 在进度条完成时调用，`onCancel` 在取消或中断时调用。
6. **道具清理**：进度条结束后，绑定的道具会自动清理。
7. **动画清理**：进度条结束后，播放的动画会自动停止。
8. **服务端调用**：服务端调用时需要提供 `target` 参数（玩家服务器 ID）。

### 🔗 相关文档

* 进度条说明


---

# 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/jin-du-tiao-progress.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.