> 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).

# 通知系统参考

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

### `SONotification`

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

**创建：** 在项目窗口中右键单击 → **创建 → Convai → 通知系统 → 通知**

**字段：**

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

**用于运行时创建的流式设置器：**

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

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

```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。

**创建：** 右键单击 → **创建 → Convai → 通知系统 → 通知组**

**字段：**

| 字段                | 类型                 | 描述                            |
| ----------------- | ------------------ | ----------------------------- |
| `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))
    {
        // 使用 notification
    }
}
```

{% hint style="danger" %}
组资源必须保存到 `Assets/Resources/SONotificationGroup.asset`。运行时使用的路径字符串是 `"SONotificationGroup"` ——没有文件扩展名，也没有子目录。如果资源缺失， `NotificationHandler` 会记录 `"[NotificationHandler] SONotificationGroup 资源无法解析。"` 并且不会显示任何通知。
{% 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 条通知。当第 4 条通知在已有 3 条激活时请求显示，它会进入队列，并在任一当前激活通知关闭后立即显示。

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

### `SONotificationErrorMap`

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

**创建：** 右键单击 → **创建 → Convai → 通知系统 → 会话错误映射表**

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

**字段：**

| 字段   | 类型                                   | 描述                        |
| ---- | ------------------------------------ | ------------------------- |
| `规则` | `List<SessionErrorNotificationRule>` | 按顺序排列的错误到通知规则列表。首个匹配的规则生效 |

#### `SessionErrorNotificationRule`

| 字段             | 类型                      | 描述                                |
| -------------- | ----------------------- | --------------------------------- |
| `ErrorPattern` | `string`                | 用于与会话错误匹配的错误代码字符串                 |
| `MatchType`    | `SessionErrorMatchType` | `精确` ——完整字符串相等。 `前缀` ——错误代码以此模式开头 |
| `通知`           | `SONotification`        | `SONotification` 当此规则匹配时显示的资源     |

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

**示例规则配置：**

| ErrorPattern  | MatchType | 通知                             |
| ------------- | --------- | ------------------------------ |
| `AUTH_FAILED` | `精确`      | `Notification_AuthError`       |
| `CONNECTION_` | `前缀`      | `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 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/notification-system/notification-system-reference.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.