# ctx.notification

Глобальный API уведомлений на базе Ant Design Notification, используемый для отображения панелей уведомлений в **правом верхнем углу** страницы. По сравнению с `ctx.message`, уведомления могут содержать заголовок и описание, что делает их подходящими для контента, который должен отображаться в течение длительного времени или требует внимания пользователя.

## Сценарии использования

| Сценарий | Описание |
|------|------|
| **JSBlock / События действий** | Уведомления о завершении задач, результаты массовых операций, завершение экспорта и т. д. |
| **Потоки событий** | Системные оповещения после завершения асинхронных процессов. |
| **Контент, требующий длительного отображения** | Полные уведомления с заголовками, описаниями и кнопками действий. |

## Определение типа

```ts
notification: NotificationInstance;
```

`NotificationInstance` — это интерфейс уведомлений Ant Design, предоставляющий следующие методы.

## Общие методы

| Метод | Описание |
|------|------|
| `open(config)` | Открывает уведомление с произвольной конфигурацией |
| `success(config)` | Отображает уведомление об успехе |
| `info(config)` | Отображает информационное уведомление |
| `warning(config)` | Отображает уведомление с предупреждением |
| `error(config)` | Отображает уведомление об ошибке |
| `destroy(key?)` | Закрывает уведомление с указанным ключом; если ключ не передан, закрывает все уведомления |

**Параметры конфигурации** (соответствуют [Ant Design notification](https://ant.design/components/notification)):

| Параметр | Тип | Описание |
|------|------|------|
| `message` | `ReactNode` | Заголовок уведомления |
| `description` | `ReactNode` | Описание уведомления |
| `duration` | `number` | Задержка автоматического закрытия (в секундах). По умолчанию 4,5 секунды; установите 0, чтобы отключить автозакрытие |
| `key` | `string` | Уникальный идентификатор уведомления, используемый в `destroy(key)` для закрытия конкретного уведомления |
| `onClose` | `() => void` | Функция обратного вызова при закрытии |
| `placement` | `string` | Расположение: `topLeft` \| `topRight` \| `bottomLeft` \| `bottomRight` |

## Примеры

### Базовое использование

```ts
ctx.notification.open({
  message: 'Операция выполнена',
  description: 'Данные были успешно сохранены на сервере.',
});
```

### Быстрые вызовы по типу

```ts
ctx.notification.success({
  message: ctx.t('Export completed'),
  description: ctx.t('Exported {{count}} records', { count: 10 }),
});

ctx.notification.error({
  message: ctx.t('Export failed'),
  description: ctx.t('Please check the console for details'),
});

ctx.notification.warning({
  message: ctx.t('Warning'),
  description: ctx.t('Some data may be incomplete'),
});
```

### Настройка длительности и ключа

```ts
ctx.notification.open({
  key: 'task-123',
  message: ctx.t('Task in progress'),
  description: ctx.t('Please wait...'),
  duration: 0,  // Не закрывать автоматически
});

// Ручное закрытие после завершения задачи
ctx.notification.destroy('task-123');
```

### Закрытие всех уведомлений

```ts
ctx.notification.destroy();
```

## Отличия от ctx.message

| Характеристика | ctx.message | ctx.notification |
|------|--------------|------------------|
| **Расположение** | Вверху по центру страницы | В правом верхнем углу (настраивается) |
| **Структура** | Однострочная легкая подсказка | Включает заголовок + описание |
| **Назначение** | Временная обратная связь, исчезает автоматически | Полное уведомление, может отображаться долго |
| **Типичные сценарии** | Успех операции, ошибка валидации, успешное копирование | Завершение задачи, системные сообщения, длинный контент, требующий внимания |

## Связанные разделы

- [ctx.message](./message.md) — подсказка в верхней части экрана, подходит для быстрой обратной связи
- [ctx.modal](./modal.md) — модальное окно подтверждения, блокирующее взаимодействие
- [ctx.t()](./t.md) — интернационализация, часто используется вместе с уведомлениями