> 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 窗口中右键单击 → **创建 → Convai → 通知系统 → 通知**

**字段：**

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

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

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

方法返回 `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 条通知。当已有 3 条通知处于活动状态时请求第 4 条通知，它会进入队列，并在其中一条活动通知关闭后立即显示。

**每条通知的动画顺序：** 滑入（`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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.