> 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/wen-ben-textui.md).

# 文本（TextUI）

## 🪧 TextUI（文本提示）模块导出文档

### 📋 概述

TextUI 模块是 ak-lib 的屏幕文本提示系统，支持自定义位置、样式、图标、自动关闭、更新不闪烁等功能。

### 🚀 导出方式

#### 客户端

```lua
exports['ak-lib']:TextUI(data)
exports['ak-lib']:ShowTextUI(data)
exports['ak-lib']:HideTextUI()
exports['ak-lib']:UpdateTextUI(data)
exports['ak-lib']:IsTextUIOpen()
```

#### 服务端

```lua
exports['ak-lib']:TextUI(target, data)
exports['ak-lib']:HideTextUI(target)
```

### 📖 可用导出

#### 客户端

| 导出                   | 说明          | 参数                      | 返回值                    |
| -------------------- | ----------- | ----------------------- | ---------------------- |
| `TextUI(data)`       | 显示文本提示      | `data` (table / string) | boolean                |
| `ShowTextUI(data)`   | 显示文本提示（别名）  | `data` (table / string) | boolean                |
| `HideTextUI()`       | 隐藏文本提示      | -                       | boolean                |
| `UpdateTextUI(data)` | 更新文本提示（不闪烁） | `data` (table)          | boolean                |
| `IsTextUIOpen()`     | 检查是否已打开     | -                       | boolean, string (当前消息) |

#### 服务端

| 导出                     | 说明          | 参数                                | 返回值 |
| ---------------------- | ----------- | --------------------------------- | --- |
| `TextUI(target, data)` | 向指定玩家显示文本提示 | `target` (number), `data` (table) | nil |
| `HideTextUI(target)`   | 隐藏指定玩家的文本提示 | `target` (number)                 | nil |

### 💡 使用示例

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

```lua
-- 方式一：字符串输入（自动转换为 message）
exports['ak-lib']:TextUI("按 E 打开商店")

-- 方式二：表输入（推荐）
exports['ak-lib']:TextUI({
    message = "按 E 打开商店"
})

-- 带图标
exports['ak-lib']:TextUI({
    message = "按 G 开始任务",
    icon = "fa-solid fa-rocket"  -- FontAwesome 图标类
})

-- 自定义样式
exports['ak-lib']:TextUI({
    message = "VIP 专属通道",
    icon = "fa-solid fa-magic",
    style = {
        backgroundColor = "rgba(0,0,0,0.6)",
        color = "#00ff00",
        fontSize = "20px"
    }
})

-- 自定义时长（自动关闭）
exports['ak-lib']:TextUI({
    message = "限时活动中...",
    icon = "fa-solid fa-clock",
    duration = 5000  -- 5 秒后自动关闭（单位：毫秒）
})

-- 自定义位置（9宫格）
exports['ak-lib']:TextUI({
    message = "顶部显示",
    position = "top-center"
})

-- 音效控制
exports['ak-lib']:TextUI({
    message = "你触发了机关！",
    sound = false,  -- 禁用提示音
    volume = 0.3    -- 音量大小（0.0 ~ 1.0）
})

-- 永久显示（需手动关闭）
exports['ak-lib']:TextUI({
    message = "安全区内",
    duration = 0  -- 0 = 永不关闭，需手动 HideTextUI()
})

-- 更新 TextUI（不闪烁，覆盖显示）
exports['ak-lib']:TextUI({
    message = "按住 E 交互"
})

-- 稍后更新内容（不重新动画，直接覆盖）
exports['ak-lib']:UpdateTextUI({
    message = "松开 E 退出"
})

-- 检查是否已打开
local isOpen, message = exports['ak-lib']:IsTextUIOpen()
if isOpen then
    print("TextUI 已打开，当前消息:", message)
end

-- 隐藏 TextUI
exports['ak-lib']:HideTextUI()
```

#### 服务端：向玩家发送文本提示

```lua
-- 向指定玩家显示文本提示
exports['ak-lib']:TextUI(source, {
    message = "按 E 打开商店",
    icon = "fa-solid fa-shop"
})

-- 隐藏指定玩家的文本提示
exports['ak-lib']:HideTextUI(source)
```

### 📝 参数说明

#### data 参数（table / string）

如果传入字符串，会自动转换为 `{ message = "字符串" }`

| 字段         | 类型      | 说明                | 必需  | 默认值                      |
| ---------- | ------- | ----------------- | --- | ------------------------ |
| `message`  | string  | 提示文本              | ✅ 是 | -                        |
| `icon`     | string  | FontAwesome 图标类名  | 否   | -                        |
| `style`    | table   | CSS 样式对象          | 否   | `{}`                     |
| `position` | string  | 位置（九宫格）           | 否   | `Config.TextUI.Position` |
| `duration` | number  | 显示时长（毫秒），0 = 永不关闭 | 否   | `Config.TextUI.Duration` |
| `sound`    | boolean | 是否播放音效            | 否   | `Config.TextUI.Sound`    |
| `volume`   | number  | 音量（0.0 \~ 1.0）    | 否   | `Config.TextUI.Volume`   |

#### style 参数（table）

CSS 样式对象，支持的字段：

* `backgroundColor` - 背景颜色
* `color` - 文字颜色
* `fontSize` - 字体大小
* 其他 CSS 属性

#### 位置选项（position）

支持九宫格位置：

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

### ⚠️ 注意事项

1. **message 必需**：`message` 字段是必需的。
2. **字符串简化**：可以直接传入字符串，会自动转换为 `{ message = "字符串" }`。
3. **永久显示**：设置 `duration = 0` 可以永久显示，需要手动调用 `HideTextUI()` 关闭。
4. **更新不闪烁**：使用 `UpdateTextUI()` 更新 TextUI 时不会重新播放动画，直接覆盖显示。
5. **同时只能显示一个**：TextUI 同时只能显示一个，新的会替换旧的。
6. **服务端调用**：服务端调用时需要提供 `target` 参数（玩家服务器 ID）。
7. **IsTextUIOpen 返回值**：返回两个值，第一个是 boolean（是否打开），第二个是 string（当前消息内容）。

### 🔗 相关文档

* 文本说明


---

# 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/wen-ben-textui.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.