> 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

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

Unity 的 Convai SDK 内置了一个现成的 `ChatTranscriptUI` 预制件，可实时显示滚动的聊天记录。该预制件包含自己的 `Canvas` ——将其拖入场景后，它会自动连接到 `ConvaiManager` 。

### 聊天记录和字幕

`ConvaiManager.ActiveManager.Transcripts` (`ConvaiTranscripts`）提供了对话的两种独立且可组合的呈现方式：持久聊天记录和与语音实时同步的字幕。本页介绍如何使用随 SDK 提供的 `ChatTranscriptUI` 预制件添加聊天记录。字幕使用单独的示例脚本，SDK 未提供对应预制件——请参阅 [聊天和字幕模式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.md) ，了解如何添加字幕，或在同一场景中组合显示两者。

| 投影   | 使用方                                        | 说明                        |
| ---- | ------------------------------------------ | ------------------------- |
| 聊天记录 | `ChatTranscriptUI` （随 SDK 提供的预制件，本页介绍）     | 滚动消息气泡——玩家和角色的发言分别显示为独立条目 |
| 字幕   | `SubtitleTranscriptUI` （参考脚本，SDK 未提供对应预制件） | 单个字幕块会随每轮对话流式更新，随后自动隐藏    |

### 添加聊天 UI 预制件

{% stepper %}
{% step %}

#### 定位预制件

在 Project 窗口中，导航至：

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

{% endstep %}

{% step %}

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

将 `TranscriptUI_Chat.prefab` 拖入 Hierarchy。该预制件包含自己的 `Canvas` ——无需单独进行 `Canvas` 设置。

聊天 UI 覆盖层会显示在 Game 视图中。场景启动时，该组件会自动查找 `ConvaiManager` ，无需手动连接。

聊天输入框要求场景中存在一个 `EventSystem` 。如果场景中还没有，请通过以下菜单添加： **GameObject > UI > Event System**.

{% hint style="warning" %}
如果启动时未找到 `ConvaiManager` ，Console 会记录以下内容： `[ChatTranscriptUI] No active ConvaiManager found.`。请确认场景中包含 `ConvaiManager` 。
{% endhint %}
{% endstep %}
{% endstepper %}

### ChatTranscriptUI 检视器字段

如需自定义布局，请选中预制件实例并检查 `ChatTranscriptUI` 组件。

**UI 引用：**

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

**淡入淡出设置：**

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

{% hint style="warning" %}
如果 `chatContainer` 未指定，消息将不会显示，并且控制台会记录： `[ChatTranscriptUI] chatContainer is not assigned - messages will not display`。随附的预制件已预先配置好所有引用。
{% endhint %}

### 使用示例

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

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

**设置：**

* 将 `TranscriptUI_Chat.prefab` 拖入层级视图
* 所有引用保持预制件默认设置

**预期结果：** 每轮对话都会显示为一个新气泡——玩家文本位于右侧，角色文本位于左侧。随着对话内容增多，列表会自动滚动。

### 后续步骤

设置好对话记录 UI 后，添加口型同步，让角色的混合形状由音频驱动。

{% content-ref url="/pages/ed9168a8079f978e6efcf4613ab9296537de8035" %}
[添加口型同步](https://docs.convai.com/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.
