> 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 Unity SDK 包含一个现成的 `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 覆盖层会显示在 Game 视图中。该组件会自动找到 `ConvaiManager` 当场景启动时自动连接——无需手动绑定。

{% hint style="warning" %}
聊天输入字段需要一个 `EventSystem` 位于场景中。如果你的场景尚未包含一个，请通过 **GameObject > UI > Event System**.
{% endhint %}

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

### ChatTranscriptUI 检视面板字段

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

**UI 参考：**

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

**淡入淡出设置：**

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

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

### 用法示例

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

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

**设置：**

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

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

### 下一步

在放置好转录 UI 后，添加口型同步，以根据音频驱动角色 BlendShape。

{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.