> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/utilities/transcript-ui-system.md).

# 转录 UI 系统

## 概述

动态 UI 系统是 Convai Unity SDK 中的一项功能，为开发者提供了一个强大的游戏内通信系统。此功能支持显示来自角色和玩家的消息，并支持用于聊天、问答会话、字幕以及自定义 UI 类型的各种 UI 组件。本文档将指导你在 Unity 项目中集成、使用以及创建 Dynamic UI 功能的自定义 UI 类型。

## 使用方法

### 访问聊天 UI 处理器

要与聊天系统交互，你需要在 `ConvaiChatUIHandler` 中引用它。你可以在 Prefabs 文件夹中找到 Transcript UI 预制体。

<figure><img src="/files/544e4fa84d1885fa5769d5c4d918ed46ccbdc559" alt="" width="338"><figcaption></figcaption></figure>

\
以下是查找并赋值该处理器的示例：

```csharp
private ConvaiChatUIHandler _convaiChatUIHandler;

private void OnEnable()
{
    // 在场景中查找并赋值 ConvaiChatUIHandler 组件
    _convaiChatUIHandler = ConvaiChatUIHandler.Instance;
    if (_convaiChatUIHandler != null) _convaiChatUIHandler.UpdateCharacterList();
}
```

### 发送消息

一旦你有了对 `ConvaiChatUIHandler`的引用，你就可以使用以下方法发送消息：

**发送玩家文本**

要以玩家身份发送文本：

```csharp
_convaiChatUIHandler.SendPlayerText(input);
```

* `input`：包含玩家消息的字符串。

### **发送角色文本**

要以角色身份发送文本：

{% code overflow="wrap" %}

```csharp
_convaiChatUIHandler.SendCharacterText(characterName, currentResponseAudio.AudioTranscript.Trim());
```

{% endcode %}

* `characterName`：发送消息的角色名称。
* `currentResponseAudio.AudioTranscript`：角色音频回复的转录文本，已去除首尾空白字符。

## 向 Dynamic Chatbox 添加自定义 UI 类型

虽然 [SDK 中的动态 UI 系统提供了若干预构建的 UI 类型](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/utilities/convai-ui-prefabs.md)，但你可能希望创建一个更符合游戏风格和需求的自定义 UI，并且它被设计为可扩展的，允许开发者添加他们自己的自定义 UI 类型。这可以通过继承 `ChatUIBase` 类并实现所需的方法来完成。 `ConvaiChatUIHandler` 负责管理不同的 UI 类型，并提供在它们之间切换的系统。

### 创建自定义 UI 类

要创建自定义 UI 类型，请按以下步骤操作：

#### 步骤 1：定义你的自定义类

在你的 Unity 项目中创建一个新的 C# 脚本，并定义你的类继承自 `ChatUIBase`。例如：

```csharp
using Convai.Scripts.Utils;
using UnityEngine;

public class CustomChatUI : ChatUIBase
{
    // 在这里实现 ChatUIBase 中要求的方法。
}
```

#### 步骤 2：实现所需方法

实现 `ChatUIBase`中的抽象方法。你必须为 `Initialize`, `SendCharacterText`，以及 `SendPlayerText`:

{% code overflow="wrap" lineNumbers="true" %}

```csharp
public override void Initialize(GameObject uiPrefab)
{
    // 在这里实例化并设置你的自定义 UI 预制体。
}

public override void SendCharacterText(string charName, string text, Color characterTextColor)
{
    // 在这里处理向你的自定义 UI 发送角色文本。
}

public override void SendPlayerText(string playerName, string text, Color playerTextColor)
{
    在这里处理向你的自定义 UI 发送玩家文本。
}
```

{% endcode %}

#### 步骤 3：添加自定义功能

添加你的自定义 UI 可能需要的任何额外功能或自定义选项。

#### 步骤 4：分配并使用你的自定义 UI

要在字典中使用你的自定义 UI 类`ConvaiChatUIHandler`，你需要将其添加到 `GetUIAppearances` 字典中。这涉及为你的自定义 UI 创建一个预制体，并在 `ConvaiChatUIHandler`.

中进行赋值。以下是示例：

1. 为你的自定义 UI 创建一个预制体，并将你的 `CustomChatUI` 组件添加到其中。
2. 将该预制体赋值给 `ConvaiChatUIHandler` 脚本中的一个公共变量。
3. 修改 `InitializeUIStrategies` 方法，在 `ConvaiChatUIHandler` 脚本中包含你的自定义 UI 类型。

{% code overflow="wrap" lineNumbers="true" %}

```csharp
[Tooltip (用于 customChatUI 的预制体。)]
public GameObject customChatUIPrefab;

private void InitializeUIStrategies()
{
    现有 UI 类型
    InitializeUI(chatBoxPrefab, UIType.ChatBox);
    InitializeUI(questionAnswerPrefab, UIType.QuestionAnswer);
    InitializeUI(subtitlePrefab, UIType.Subtitle);

    // 自定义 UI 类型
    InitializeUI(customChatUIPrefab, UIType.Custom); // 确保在 UIType 枚举中定义 UIType.Custom
}

private void InitializeUI (GameObject uiPrefab, UIType uiType)
{
    // 现有代码...

    在这里添加你的自定义 UI 初始化
    if (uiType == UIType.Custom)
    {
        CustomChatUI customUIComponent = uiPrefab.GetComponent<CustomChatUI>();
        if (customUIComponent == null)
        {
            Debug.LogError("在预制体上未找到 CustomChatUI 组件。");
            return;
        }

        customUIComponent.Initialize(uiPrefab);
        GetUIAppearances[uiType] = customUIComponent;
    }
}
```

{% endcode %}

4. 确保你的自定义 UI 类型已添加到 `UIType` 枚举：

```csharp
public enum UIType
{
    ChatBox,
    QuestionAnswer,
    Subtitle,
    CustomUI // 你的自定义 UI 类型
}
```

5. 现在你可以在设置面板中将你的自定义 UI 类型设为当前活动 UI [设置面板](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/utilities/settings-panel.md).

按照这些步骤，你可以将自定义 UI 类型集成到 Dynamic Chatbox 系统中，并在运行时在不同的 UI 类型之间切换。


---

# 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://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/utilities/transcript-ui-system.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.