聊天与字幕模式

配置 Chat 模式的可滚动消息气泡或 Subtitle 模式的自动隐藏覆盖层，在运行时切换它们，并为聊天添加每条回复的反馈按钮。

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 — 清除转录显示 以了解访问模式以及关于底层轮次历史的重要注意事项。

聊天消息反馈

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

1

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

将 FeedbackButtons.prefab 作为你的角色消息气泡预制体的子对象。可在 Prefabs/TranscriptUI/FeedbackButtons.prefab 中找到它，位于 com.convai.convai-sdk-for-unity 包内。该预制体包含反馈按钮视觉效果和一个 FeedbackHandler 组件。

2

确保气泡设置了交互 ID

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

3

运行你的场景

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

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	轮次完成后等待多少秒再隐藏

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

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

切换模式

设置面板

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

默认情况下，设置面板的下拉框只显示聊天模式。要从面板启用字幕模式，请先通过程序切换它（参见脚本选项卡），然后面板会反映当前状态。有关设置，请参阅 设置面板 。

脚本

使用示例

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

工作场所安全培训模拟使用聊天模式，这样受训者在完成场景后可以回顾完整的 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 组件”。要让用户控制当前激活的模式，请参阅“设置面板”。

自定义 UI 组件设置面板