> 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/customizing-ui-components.md).

# 自定义 UI 组件

使用角色可见性筛选器或替换预制件，重新设计或替换内置的转录文本、通知和设置 UI。

两种扩展方式可让你自定义 SDK 的场景级 UI，而无需替换其数据管线。角色可见性筛选用于控制哪些角色的转录内容会显示在当前 UI 中。视觉自定义则用于替换渲染这些转录内容、通知和设置控件的预制件。

如果只需轻量级的转录回调，不需要自定义 UI，请使用 `ITranscriptListener`。如果要创建完整的自定义转录显示界面，以替换内置聊天或字幕面板，请使用 `ITranscriptUI`。这两个接口的文档都位于 [转录 UI](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui.md).

### 角色可见性筛选

控制 `TranscriptUIController` 将哪些角色的转录内容路由到当前 UI——这对于多角色场景至关重要，因为同时显示多个转录内容会造成混乱。

**基类：** `TranscriptFilterBase` （SDK 提供，位于 `SDK/Runtime/Presentation/Services/Utilities/`)

* 如果 `GameObject` 上不存在 `5f`，则自动添加一个 `SphereCollider`
* （半径为 `，并启用触发模式）` 通过 `OnTriggerEnter` / `和` OnTriggerExit
* 回调维护 `CharactersInsideColliderList` 与 `IVisibleCharacterService` 集成——启动时会从
* ConvaiManager `自动解析该服务` 将其添加到玩家的

**GameObject** 或其子对象上 `两种开箱即用的实现` （位于

#### `SamplesShared/Scripts/UI/Utilities/`

——修改前请先复制）： **SingleCharacterFilter**.

* 跟踪玩家视锥范围内最近的角色
* 适用于包含多个角色的字幕模式
* 玩家只能看到其正面所朝角色的转录内容
* 默认视锥角度：总计 90°（正前方 45° 范围内的任意角色） `若要覆盖视锥角度，请在玩家代理上实现` IVisionConeProvider `。该接口定义在` ProximityCharacterFilter.cs（命名空间 `Convai.Sample.UI.Utilities`, SamplesShared 层）：

```csharp
// 在 ProximityCharacterFilter.cs 中定义 — 命名空间 Convai.Sample.UI.Utilities
public interface IVisionConeProvider
{
    float VisionConeAngle { get; }
}
```

#### `ProximityCharacterFilter`

跟踪 **半径范围和视锥内的所有角色**.

* 最适合包含群组对话的聊天模式
* 可同时查看多个角色的对话转录
* 视野锥行为与 `SingleCharacterFilter`

**场景设置检查清单：**

* [ ] 将 `SingleCharacterFilter` 或 `ProximityCharacterFilter` 添加到玩家的 `GameObject`
* [ ] 确保有一个 `Rigidbody` 存在于玩家或角色上（触发器回调所必需）
* [ ] `ConvaiManager` 自动解析 `IVisibleCharacterService` 筛选器启动时
* [ ] 在播放模式下，通过走近和远离角色进行测试

{% hint style="warning" %}
`SingleCharacterFilter` 和 `ProximityCharacterFilter` 是参考实现，位于  `SamplesShared`。修改前请将其复制到您自己的程序集中，因为对  `SamplesShared` 脚本所做的更改会在 SDK 更新时被覆盖。
{% endhint %}

### 视觉自定义

#### 聊天消息气泡

`ChatTranscriptUI` 根据其 Inspector 字段实例化角色和玩家消息预制件。要更改样式：

1. 复制以下位置的默认气泡： `Prefabs/TranscriptUI/` 在 <code class="expression">space.vars.sdk\_package\_id</code> 包中
2. 重新设置副本的样式（颜色、字体、背景、布局）
3. 将其赋给 `characterMessagePrefab` 或 `playerMessagePrefab` 在 `ChatTranscriptUI`

替换用的预制件必须包含一个 `ChatMessageBubble` 组件，并连接以下字段：

| 字段          | 类型                | 说明       |
| ----------- | ----------------- | -------- |
| `senderUI`  | `TextMeshProUGUI` | 显示发言者的名称 |
| `messageUI` | `TextMeshProUGUI` | 显示转录文本   |

ChatMessageBubble `上可用的样式设置方法`:

| 方法                              | 说明                  |
| ------------------------------- | ------------------- |
| `SetSender(string sender)`      | 设置发言者的显示名称          |
| `SetSenderColor(Color color)`   | 覆盖自动分配的发言者名称颜色      |
| `SetMessage(string message)`    | 设置完整的消息文本           |
| `AppendMessage(string message)` | 将文本追加到当前消息中（用于流式传输） |

#### 通知预制件

`UINotificationController` 会实例化 `UINotification` 预制件，该预制件来自其 `uiNotificationPrefab` 字段。要更改其样式：

1. 复制 `Notification.prefab` 从 `Prefabs/Notifications/` 目录（位于 <code class="expression">space.vars.sdk\_package\_id</code> 包）中
2. 调整副本的样式
3. 将其指定给 `uiNotificationPrefab` 上的 `UINotificationController`

必需的 `UINotification` 引用：

| 字段                          | 类型                | 说明     |
| --------------------------- | ----------------- | ------ |
| `notificationRectTransform` | `RectTransform`   | 用于滑动定位 |
| `notificationIcon`          | `Image`           | 显示精灵图  |
| `notificationTitleText`     | `TextMeshProUGUI` | 标题     |
| `notificationMessageText`   | `TextMeshProUGUI` | 正文     |

#### 设置面板视图

实现 `ISettingsPanelView` 并连接到 `SettingsPanelPresenter` ，用于完全自定义设置 UI。Presenter 负责所有业务逻辑，视图只负责渲染和处理输入事件。

```csharp
// 将自定义视图绑定到现有的 presenter
settingsPanelPresenter.Bind(myCustomView);

// 销毁视图时取消绑定
settingsPanelPresenter.Unbind();
```

### 使用示例

#### 多角色字幕焦点

包含多个 AI 角色（医生、护士、患者）的医疗模拟项目会在受训者身上使用 `SingleCharacterFilter` ，使字幕显示自动切换为受训者正面对的 AI 角色。将此组件添加到玩家 `GameObject`上，确认存在 `Rigidbody` ，并保留默认的 90° 视野锥。运行时，受训者在不同角色之间转身时，当前字幕会自动切换为其正前方角色的字幕，无需手动干预。

#### 自定义通知外观

军事训练模拟项目将默认通知预制件替换为符合模拟项目 UI 风格的 HUD 式警报。复制默认通知预制件，将其重新设计为右上角状态指示器，然后将其指定给 `UINotificationController.uiNotificationPrefab`。运行时，所有系统和会话错误警报都会采用项目的视觉风格显示，无需更改任何通知逻辑。

### 故障排查

| 症状                               | 可能原因                                                         | 解决方法                                                             |
| -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- |
| `TranscriptFilterBase` 未跟踪角色     | 否 `Rigidbody` 未添加到玩家或角色上                                     | 在每组角色与玩家对象中的至少一方添加 `Rigidbody` 组件                                |
| `SingleCharacterFilter` 跟踪了错误的角色 | 玩家 `GameObject` 未能通过 `GetComponentInParent<ConvaiPlayer>()`  | 将筛选器放置在玩家 `GameObject` 上，或通过 `IPlayerInputService` 调用 `Inject()` |
| 自定义 `ISettingsPanelView` 未收到保存回调 | 视图尚未绑定到 presenter                                            | 在 presenter 可用后调用 `settingsPanelPresenter.Bind(myCustomView)` 。  |
| 替换后的气泡预制件不显示文本                   | `senderUI` 或 `messageUI` 未在 `ChatMessageBubble`              | 将两者都连接 `TextMeshProUGUI` 在预制件 Inspector 中的引用                     |
| 自定义通知预制件未显示                      | `uiNotificationPrefab` 上 `UINotificationController` 仍指向默认预制件 | 将重新设计样式的预制件分配给 `uiNotificationPrefab` 字段                         |

### 后续步骤

{% content-ref url="/pages/49fed70bb2b468bcc6348096af1fc53fdb0656ce" %}
[转录 UI](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui.md)
{% endcontent-ref %}

{% content-ref url="/pages/6695eb978b08dbf5023b367d38af0912574c4f52" %}
[聊天和字幕模式](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)
{% 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/ui-and-presentation/customizing-ui-components.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.
