> 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/notification-system/notification-system-reference.md).

# 通知系统参考

SONotification、SONotificationGroup、UINotificationController 和 SONotificationErrorMap 的参考——字段、方法和配置选项。

用于构成通知系统的 ScriptableObject 资源和控制器组件的参考。有关设置说明以及从代码中触发通知，请参见 [通知系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/notification-system.md).

### `SONotification`

每个通知都是一个 `ScriptableObject` 包含要显示内容的资源。

**创建：** 在 Project 窗口中右键 → **Create → Convai → Notification System → Notification**

**字段：**

| 字段                    | 类型       | 说明                                 |
| --------------------- | -------- | ---------------------------------- |
| `图标`                  | `Sprite` | 显示在通知图标槽位中的 Sprite。可选——留空则不显示图标    |
| `notificationTitle`   | `string` | 以粗体显示的标题文本                         |
| `notificationMessage` | `string` | 正文文本。支持多行内容                        |
| `Id`                  | `string` | 用于错误映射和去重冷却的稳定字符串标识符。如果为空，则默认为资源名称 |

**用于运行时创建的流式 setter：**

| 方法                           | 返回类型             | 说明       |
| ---------------------------- | ---------------- | -------- |
| `SetTitle(string title)`     | `SONotification` | 设置通知标题   |
| `SetMessage(string message)` | `SONotification` | 设置通知正文文本 |
| `SetIcon(Sprite newIcon)`    | `SONotification` | 设置通知图标精灵 |

方法返回 `此`，从而支持链式调用：

```csharp
var notification = ScriptableObject.CreateInstance<SONotification>();
notification
    .SetTitle("Scenario Complete")
    .SetMessage("All required steps have been completed. Proceed to debrief.")
    .SetIcon(successIcon);
```

### `SONotificationGroup`

`SONotificationGroup` 注册场景可识别的所有 `SONotification` 资源。 `NotificationHandler` 在运行时根据该组解析通知 ID。

**创建：** 右键 → **Create → Convai → Notification System → Notification Group**

**字段：**

| 字段                | 类型                 | 说明                            |
| ----------------- | ------------------ | ----------------------------- |
| `soNotifications` | `SONotification[]` | 所有 `SONotification` 通知系统可用的资源 |

**静态查找方法：**

| 方法                                                                   | 返回类型   | 说明                                                       |
| -------------------------------------------------------------------- | ------ | -------------------------------------------------------- |
| `GetGroup(out SONotificationGroup group)`                            | `bool` | 从 `Resources/SONotificationGroup`。返回 `false` 加载该组，如果资源缺失 |
| `TryGetById(string notificationId, out SONotification notification)` | `bool` | 根据其 `Id` 字段查找通知。返回 `false` 如果没有匹配项则返回                    |

```csharp
if (SONotificationGroup.GetGroup(out SONotificationGroup group))
{
    if (group.TryGetById("scenario-complete", out SONotification notification))
    {
        // 使用通知
    }
}
```

{% hint style="danger" %}
该组资源必须保存到 `Assets/Resources/SONotificationGroup.asset`。运行时使用的路径字符串是 `"SONotificationGroup"` ——没有文件扩展名，也没有子目录。如果资源缺失， `NotificationHandler` 记录 `"[NotificationHandler] SONotificationGroup asset could not be resolved."` 且不会显示任何通知。
{% endhint %}

### `UINotificationController`

管理可复用的 `UINotification` 元素池，并控制每个通知的滑入滑出动画。

**检查器字段：**

| 字段                           | 类型               | 默认值   | 说明                       |
| ---------------------------- | ---------------- | ----- | ------------------------ |
| `uiNotificationPrefab`       | `UINotification` | —     | `UINotification` 要入池的预制体 |
| `spacing`                    | `int`            | `100` | 堆叠通知之间的垂直像素间距            |
| `activeNotificationPos`      | `Vector2`        | —     | 可见通知出现时的锚点位置             |
| `deactivatedNotificationPos` | `Vector2`        | —     | 隐藏通知在屏幕外等待时的锚点位置         |
| `activeDuration`             | `float`          | `4.0` | 通知在滑出前保持可见的秒数            |
| `slipDuration`               | `float`          | `0.3` | 滑入和滑出动画所需的秒数             |
| `delay`                      | `float`          | `0.3` | 开始滑动动画前的延迟秒数             |
| `slipAnimationCurve`         | `AnimationCurve` | —     | 滑动动画的缓动曲线                |

**并发与排队：** 最多可同时显示 3 条通知。当已有 3 条通知处于活动状态时请求第 4 条通知，它会进入队列，并在任意一条活动通知消失后立即显示。

**每个通知的动画顺序：** 滑入（`slipDuration`）→ 显示 `activeDuration` 秒 → 延迟（`delay`）→ 滑出（`slipDuration`）→ 下一条排队的通知开始。

### `SONotificationErrorMap`

使用有序规则列表将会话错误代码字符串映射到 `SONotification` 资源。可从 `Resources/SONotificationErrorMap` 自动加载，或手动分配。

**创建：** 右键 → **Create → Convai → Notification System → Session Error Map**

保存到 `Assets/Resources/SONotificationErrorMap.asset` 以便自动加载。

**字段：**

| 字段   | 类型                                   | 说明                      |
| ---- | ------------------------------------ | ----------------------- |
| `规则` | `List<SessionErrorNotificationRule>` | 错误到通知的有序规则列表。第一个匹配的规则生效 |

#### `SessionErrorNotificationRule`

| 字段             | 类型                      | 说明                                      |
| -------------- | ----------------------- | --------------------------------------- |
| `ErrorPattern` | `string`                | 用于与会话错误匹配的错误代码字符串                       |
| `MatchType`    | `SessionErrorMatchType` | `完全匹配` — 完整字符串相等。 `Prefix` — 错误代码以此模式开头 |
| `Notification` | `SONotification`        | `SONotification` 此规则匹配时要显示的资源           |

规则按从上到下的顺序评估。将更具体的规则放在更宽泛的前缀匹配之上。

**示例规则配置：**

| ErrorPattern  | MatchType | Notification                   |
| ------------- | --------- | ------------------------------ |
| `AUTH_FAILED` | `完全匹配`    | `Notification_AuthError`       |
| `CONNECTION_` | `Prefix`  | `Notification_ConnectionError` |
| `RATE_LIMIT`  | `完全匹配`    | `Notification_RateLimit`       |

### 下一步

{% content-ref url="/pages/1e289d6d26e0f600f68032dc64a489bc29fe1a00" %}
[通知系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/notification-system.md)
{% endcontent-ref %}

{% 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 %}


---

# 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/notification-system/notification-system-reference.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.