> 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/convai-unity-sdk/getting-started/add-chat-ui.md).

# 添加聊天 UI

添加随附的聊天文字记录预制体，以便在角色交互期间在屏幕上显示可滚动的对话历史。

Convai SDK for Unity 包含一个现成的 `ChatTranscriptUI` 用于实时显示可滚动聊天历史的预制件。该预制件包含其自己的 `Canvas` ——把它拖入场景中，它会连接到 `ConvaiManager` 自动。

### 聊天历史和字幕

`ConvaiManager.ActiveManager.Transcripts` (`ConvaiTranscripts`) 提供对话的两个独立且可组合的呈现：持久聊天历史和与语音同步的实时字幕。本页使用随附的 `ChatTranscriptUI` 预制件添加聊天历史。字幕使用一个单独的、仅供示例的脚本，没有随附的预制件——请参见 [聊天和字幕模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.md) 以添加字幕，或在同一场景中将两种显示结合起来。

| 投影   | 被以下对象消费                               | 说明                          |
| ---- | ------------------------------------- | --------------------------- |
| 聊天历史 | `ChatTranscriptUI` （随附预制件，本页介绍）       | 可滚动消息气泡——玩家和角色回合分别显示        |
| 字幕   | `SubtitleTranscriptUI` （参考脚本，没有随附预制件） | 单个字幕块，会随着每次回合流式传输而更新，然后自动隐藏 |

### 添加聊天 UI 预制件

{% stepper %}
{% step %}

#### 定位预制件

在 Project 窗口中，导航到：

```
Packages/Convai SDK for Unity/Prefabs/TranscriptUI/TranscriptUI_Chat.prefab
```

{% endstep %}

{% step %}

#### 将预制件拖入场景

拖拽 `TranscriptUI_Chat.prefab` 到 Hierarchy 中。该预制件包含其自己的 `Canvas` ——无需单独的 `Canvas` 设置。

聊天 UI 覆盖层会出现在游戏视图中。该组件会在场景启动时自动查找 `ConvaiManager` ——无需手动连接。

聊天输入框需要场景中的一个 `EventSystem` 位于场景中。如果你的场景还没有一个，请通过以下方式添加： **GameObject > UI > Event System**.

{% hint style="warning" %}
如果启动时未找到 `ConvaiManager` ，控制台会记录： `[ChatTranscriptUI] 未找到活动的 ConvaiManager。`. 请检查 `ConvaiManager` 是否在场景中。
{% endhint %}
{% endstep %}
{% endstepper %}

### ChatTranscriptUI 检视器字段

如果你需要自定义布局，请选择预制件实例并查看 `ChatTranscriptUI` 组件。

**UI References：**

| 字段                       | 类型               | 说明              |
| ------------------------ | ---------------- | --------------- |
| `scrollRect`             | `ScrollRect`     | 消息列表的滚动容器       |
| `chatContainer`          | `RectTransform`  | 创建消息气泡的父级变换     |
| `characterMessagePrefab` | `GameObject`     | 角色语音气泡模板        |
| `playerMessagePrefab`    | `GameObject`     | 玩家语音气泡模板        |
| `chatInputField`         | `TMP_InputField` | 用于输入文本的文本字段（可选） |

**淡入/淡出设置：**

| 字段             | 默认    | 说明           |
| -------------- | ----- | ------------ |
| `fadeDuration` | `0.5` | 淡入/淡出过渡所需的秒数 |

{% hint style="warning" %}
如果 `chatContainer` 未分配，则消息将不会显示，控制台会记录： `[ChatTranscriptUI] chatContainer 未分配 - 消息将不会显示`。捆绑的预制件已预先连接好所有引用。
{% endhint %}

### 使用示例

#### 示例 1：企业培训模拟中的全屏聊天覆盖层

**场景：** 企业入职体验会显示全屏聊天历史，以便培训人员回顾 AI 导师说过的所有内容。

**设置：**

* 拖拽 `TranscriptUI_Chat.prefab` 到 Hierarchy 中
* 将所有引用保持为预制件默认值

**预期结果：** 每个回合都会显示为一个新的气泡——玩家文本在右侧，角色文本在左侧。随着对话推进，列表会自动滚动。

### 下一步

在转录 UI 就位后，添加口型同步，以便根据音频驱动角色的混合形状。

{% content-ref url="/pages/ed9168a8079f978e6efcf4613ab9296537de8035" %}
[添加口型同步](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-lip-sync.md)
{% endcontent-ref %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-chat-ui.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.