> 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 包含一个现成的转录 UI 预制体，可实时显示对话文本。该预制体包含自己的 Canvas——将其拖入场景，UI 会自动连接到 SDK。

### 转录显示模式

该 SDK 支持三种对话文本展示模式。

| 模式     | 标识符    | 说明                   |
| ------ | ------ | -------------------- |
| **聊天** | `“聊天”` | 滚动消息气泡——分别显示玩家和角色的发言 |
| **字幕** | `“字幕”` | 屏幕底部的一行文本，每轮替换一次     |
| **问答** | `“问答”` | 分屏显示——问题在上，答案在下      |

### 添加聊天 UI 预制体

{% stepper %}
{% step %}

#### 定位预制体

在项目窗口中，导航到：

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

{% endstep %}

{% step %}

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

拖动 `TranscriptUI_Chat.prefab` 到层级中。该预制体包含自己的 Canvas——无需单独设置 Canvas。

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

{% hint style="warning" %}
聊天输入字段需要场景中存在一个 **EventSystem** 。如果你的场景中还没有，请通过以下方式添加： **GameObject > UI > Event System**.
{% endhint %}

{% hint style="warning" %}
如果启动时未找到 `ConvaiManager` ，控制台会记录： `[ChatTranscriptUI] Dependencies not injected - ensure ConvaiManager is present in scene`。请检查 `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" %}
[添加口型同步](/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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-chat-ui.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.