> 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/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.md).

# 聊天与字幕模式

Convai Unity SDK 自带两种内置的转录显示模式。聊天模式会以可滚动的对话历史形式累积内容，消息气泡按发送者着色，并可选显示反馈按钮。字幕模式只在固定位置显示当前语音片段，并在轮次结束时自动隐藏。两种模式都可配置、可在运行时切换，并可替换为自定义的 `ITranscriptUI` 实现。

### 聊天模式与字幕模式一览

|           | 聊天                                | 字幕                                     |
| --------- | --------------------------------- | -------------------------------------- |
| **布局**    | 带发送者标签的可滚动消息气泡列表                  | 带可选说话者标签的单个居中文本块                       |
| **历史记录**  | 屏幕上保留完整对话                         | 没有历史记录——每一轮都会替换上一轮                     |
| **自动隐藏**  | 面板随活动淡入/淡出                        | 文本会在可配置的延迟后消失                          |
| **部分转录**  | 气泡会在说话过程中按词更新                     | 文本会在说话过程中按词更新                          |
| **反馈按钮**  | 通过以下方式支持 `FeedbackButtons.prefab` | 不适用                                    |
| **内置预制体** | `TranscriptUI_Chat.prefab` （SDK）  | `SubtitleTranscriptUI` （SamplesShared） |
| **最适合**   | 完整对话回顾、培训复盘、支持场景                  | AR/VR 覆盖层、信息亭、电影式演示                    |

### 聊天模式

聊天面板会在垂直可滚动容器中将每一轮渲染为独立的消息气泡。角色和玩家轮次会显示在不同的气泡列中，并带有按发送者着色的名称标签。新气泡会在部分识别期间实时更新，并在轮次完成时固定下来。

#### `ChatTranscriptUI` 检视面板字段

| 字段                       | 说明                                           |
| ------------------------ | -------------------------------------------- |
| `scrollRect`             | `ScrollRect` 包含消息列表。自动滚动所需                   |
| `chatContainer`          | `RectTransform` 消息气泡 GameObject 将作为其子对象挂载到这里 |
| `characterMessagePrefab` | 为每个角色轮次实例化的预制体                               |
| `playerMessagePrefab`    | 为每个玩家轮次实例化的预制体                               |
| `chatInputField`         | 可选 `TMP_InputField` 用于文本输入模式                 |
| `fadeDuration`           | 面板淡入/淡出动画的秒数（默认 `0.5`)                       |
| `canvasFader`            | `CanvasFader` 驱动淡入/淡出动画                      |
| `canvasGroup`            | `CanvasGroup` 控制淡入/淡出期间的可交互性                 |

#### `ChatMessageBubble` 检视面板字段

每个消息气泡预制体的根部必须包含一个 `ChatMessageBubble` 组件：

| 字段          | 说明                        |
| ----------- | ------------------------- |
| `senderUI`  | `TextMeshProUGUI` 显示说话者名称 |
| `messageUI` | `TextMeshProUGUI` 显示转录文本  |

发送者名称会根据角色注册表自动着色——场景中的每个 `ConvaiCharacter` 都会获得一个分配给其名称标签的唯一颜色。要在脚本中覆盖此行为： `bubble.SetSenderColor(Color)`.

#### 清除聊天显示

调用 `ClearAll()` 于 `ChatTranscriptUI` 以销毁所有消息气泡并重置面板。请参阅 [Transcript UI — 清除转录显示](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui.md#clear-the-transcript-display) 以了解访问模式以及关于底层轮次历史的重要注意事项。

### 聊天消息反馈

聊天气泡可以包含点赞/点踩反馈按钮，让用户对单个 AI 回复进行评分。这在企业培训和支持场景中很有用，因为这些场景需要跟踪回复质量。

{% stepper %}
{% step %}

#### 将 FeedbackButtons 添加到你的气泡预制体中

将 `FeedbackButtons.prefab` 作为你的角色消息气泡预制体的子对象。可在 `Prefabs/TranscriptUI/FeedbackButtons.prefab` 中找到它，位于 <code class="expression">space.vars.sdk\_package\_id</code> 包内。该预制体包含反馈按钮视觉效果和一个 `FeedbackHandler` 组件。
{% endstep %}

{% step %}

#### 确保气泡设置了交互 ID

`ChatTranscriptUI` 调用 `ChatMessageBubble.SetInteractionID(string)` 当角色轮次包含来自 Convai 的交互 ID 时会自动执行。若没有有效 ID，反馈提交会返回 `false` ，且视觉状态不会改变。
{% endstep %}

{% step %}

#### 运行你的场景

使用拇指按钮为角色回复评分。选中的按钮会高亮；相对的按钮会停用。 `FeedbackHandler.ResetState()` 在调用时会将两个按钮重置为中性状态。
{% endstep %}
{% endstepper %}

#### `ChatMessageBubble` 反馈 API

| 方法                                               | 说明                                                           |
| ------------------------------------------------ | ------------------------------------------------------------ |
| `SetInteractionID(string interactionID)`         | 发送反馈前必需。由 `ChatTranscriptUI`                                 |
| `SetAgentRegistry(IAgentRegistry agentRegistry)` | 角色查找所需。由 `ChatTranscriptUI`                                  |
| `bool SendFeedback(bool isPositiveFeedback)`     | 返回 `true` 如果反馈发送成功。返回 `false` 如果 `interactionID` 为空或代理注册表不可用 |

`FeedbackHandler.ResetState()` 会停用正面和负面按钮的填充视觉效果，使按钮恢复到中性状态。

反馈按钮仅与角色消息气泡相关——玩家气泡不会接收交互 ID。视觉状态是本地的；反馈数据会发送到 Convai 用于跟踪回复质量。

### 字幕模式

字幕模式会在固定的屏幕位置显示一块文本。当一轮完成后，文本会在可配置的延迟后自动隐藏。说话者名称和颜色可快速标识来源，而无需完整的气泡布局。

#### `SubtitleTranscriptUI` 检视面板字段

| 字段                  | 默认    | 说明                          |
| ------------------- | ----- | --------------------------- |
| `subtitleText`      | —     | `TMP_Text` 渲染转录内容           |
| `speakerLabel`      | —     | `TMP_Text` 渲染说话者名称          |
| `subtitleContainer` | —     | `GameObject` 包裹两个文本元素，切换开/关 |
| `fadeDuration`      | `0.3` | 淡入/淡出动画的秒数                  |
| `canvasFader`       | —     | `CanvasFader` 驱动淡入/淡出动画     |
| `canvasGroup`       | —     | `CanvasGroup` 控制可交互性        |
| `autoHideDelay`     | `3.0` | 轮次完成后等待多少秒再隐藏               |

**说话者标签颜色：** 角色语音——青色；玩家语音——绿色。

{% hint style="warning" %}
`SubtitleTranscriptUI` 位于 `SamplesShared` 中，并作为参考实现提供。修改前请将其复制到你自己的程序集里——对 `SamplesShared` 脚本的更改会在 SDK 更新时被覆盖。
{% endhint %}

### 切换模式

{% tabs %}
{% tab title="设置面板" %}
用户可以使用内置的设置面板在运行时在聊天和字幕之间切换。该面板提供一个 **转录样式** 下拉框。

{% hint style="info" %}
默认情况下，设置面板的下拉框只显示聊天模式。要从面板启用字幕模式，请先通过程序切换它（参见脚本选项卡），然后面板会反映当前状态。有关设置，请参阅 [设置面板](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/settings-panel.md) 。
{% endhint %}
{% endtab %}

{% tab title="脚本" %}
通过运行时设置服务切换模式。 `ConvaiRuntimeSettingsApplyResult` 指示切换是否成功。

```csharp
using Convai.Runtime.Components;
using Convai.Shared.Types;
using UnityEngine;

public class ModeSwitcher : MonoBehaviour
{
    public void SwitchToSubtitle()
    {
        if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings))
        {
            var result = settings.Apply(new ConvaiRuntimeSettingsPatch
            {
                TranscriptMode = ConvaiTranscriptMode.Subtitle
            });

            if (!result.Success)
                Debug.LogWarning($"模式切换失败：{result.ValidationMessage}");
        }
    }

    public void SwitchToChat()
    {
        if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings))
        {
            settings.Apply(new ConvaiRuntimeSettingsPatch
            {
                TranscriptMode = ConvaiTranscriptMode.Chat
            });
        }
    }
}
```

该补丁会以原子方式应用——任何保留为 `null` 的字段都保持不变。
{% endtab %}
{% endtabs %}

### 使用示例

#### 安全培训——带会后回顾的聊天模式

工作场所安全培训模拟使用聊天模式，这样受训者在完成场景后可以回顾完整的 AI 讲师对话：

* 使用 `TranscriptUI_Chat.prefab` 在场景 Canvas 中
* 设置 `fadeDuration` 为 `0.3` 以便在进行中的场景中实现响应式切换
* 每个场景结束后，暂停模拟，这样受训者就可以滚动查看完整对话
* 调用 `ClearAll()` 于 `ChatTranscriptUI` 在开始新场景时，确保旧消息不会延续过来

在运行时，受训者可以看到 AI 讲师所说内容的持久记录，并在复盘过程中滚动查看，然后再进入下一个模块。

#### 客户服务培训——用于回复质量反馈的按钮

客户服务培训模拟会在 AI 角色消息气泡上启用反馈按钮，以便主管在会话回顾期间标记高质量或低质量的 AI 回复：

* 将 `FeedbackButtons.prefab` 到 `characterMessagePrefab` 由 `ChatTranscriptUI`
* 反馈按钮会自动出现在每个角色气泡上
* `SetInteractionID` 由 SDK 设置——无需额外代码即可启用按钮行为

在运行时，每个 AI 回复都有点赞/点踩按钮。主管评分会反馈给 Convai，以便随着时间推移提升回复质量。

#### 医疗模拟——用于简洁覆盖层的字幕模式

程序化医疗模拟使用字幕模式，使 AI 患者的语音以简洁的覆盖层显示在患者模型上方，同时不遮挡屏幕上的临床读数：

* 放置 `SubtitleTranscriptUI` 与 `subtitleContainer` 锚定底部居中
* 设置 `autoHideDelay` 为 `2.0` ——患者回复之间的快速清除可保持屏幕整洁
* `speakerLabel` 在他们发言时显示患者名称；容器会在轮次之间自动隐藏

在运行时，每条患者回复都会短暂地以字幕形式出现，并在不累积历史记录的情况下清除，从而在整个流程中保持模拟界面整洁。

### 故障排查

| 症状                                                     | 可能原因                                                       | 修复方法                                                         |
| ------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------ |
| `"[ChatTranscriptUI] chatContainer 未分配 - 消息将不会显示"`     | `chatContainer` 未在检视面板中连接                                  | 分配 `RectTransform` 消息气泡应挂载到的对象                               |
| `"[ChatTranscriptUI] scrollRect 未分配 - 自动滚动将无法工作"`      | `scrollRect` 未在检视面板中连接                                     | 分配 `ScrollRect` 组件；不会自动滚动，但气泡仍会显示                            |
| `"[ChatTranscriptUI] 依赖项未注入 - 请确保场景中存在 ConvaiManager"` | `ConvaiManager` 在聊天 UI `Start()` 运行时缺失或未初始化                | 将 `ConvaiManager` 加入场景；确保它在 `ChatTranscriptUI.Start()`       |
| `"[ChatTranscriptUI] 无法发送消息 - 依赖项未注入"`                 | 输入到 `chatInputField` 但未找到玩家                                | 确保 `ConvaiPlayer` 在场景中并且 `ConvaiManager` 已初始化                |
| 反馈按钮未高亮                                                | `interactionID` 未设置或注册表不可用                                 | 二者都由 `ChatTranscriptUI` 自动设置——请确保 `ConvaiManager` 已初始化且角色已注册 |
| 字幕文本未消失                                                | `autoHideDelay` 值过高                                        | 降低 `autoHideDelay` 中找到它，位于 `SubtitleTranscriptUI` 检视面板       |
| 字幕模式未激活                                                | 没有 `SubtitleTranscriptUI` 在场景中与 `Identifier == "Subtitle"` | 添加示例或自定义 `ITranscriptUI` 与 `Identifier = "Subtitle"`         |

### 下一步

你已经配置了聊天或字幕显示，并且可以在运行时在它们之间切换。要自定义气泡的视觉外观或构建完全自定义的转录 UI，请参阅“自定义 UI 组件”。要让用户控制当前激活的模式，请参阅“设置面板”。

{% content-ref url="/pages/5f60eaa8d444f5ee8a995392852da827736d3b54" %}
[自定义 UI 组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/customizing-ui-components.md)
{% endcontent-ref %}

{% content-ref url="/pages/dddf624ca0ae7ec32afa0c9e601f2cb7c7ab2b6a" %}
[设置面板](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/settings-panel.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/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.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.