#Поток событий

#Введение

Если вы хотите инициировать какие-либо пользовательские действия при изменении формы, вы можете использовать для этого поток событий. Помимо форм, страницы, блоки, кнопки и поля также поддерживают настройку пользовательских действий с помощью потоков событий.

#Как использовать

Ниже на простом примере показано, как настроить поток событий. Давайте реализуем связь между двумя таблицами: при нажатии на строку в левой таблице данные в правой таблице будут фильтроваться автоматически.

Шаги настройки следующие:

1. Нажмите на иконку «молнии» в правом верхнем углу блока левой таблицы, чтобы открыть интерфейс настройки потока событий.
2. Нажмите «Добавить поток событий (Add event flow)», в поле «Триггерное событие» выберите «Клик по строке (Row click)», что означает запуск при нажатии на строку таблицы.
3. Настройте «Время выполнения (Execution timing)», которое определяет очередность этого потока событий относительно встроенных системных процессов. Обычно можно оставить значение по умолчанию; если вы хотите вывести уведомление или выполнить переход после завершения встроенной логики, выберите «После всех потоков (After all flows)». Подробнее см. ниже в разделе Время выполнения.
4. «Условие триггера (Trigger condition)» используется для настройки условий, при которых будет запускаться поток событий. В данном случае настройка не требуется, поток будет срабатывать при каждом нажатии на строку.
5. Наведите курсор на «Добавить шаг (Add step)», чтобы добавить действия. Выберите «Установить область данных (Set data scope)», чтобы настроить область данных для правой таблицы.
6. Скопируйте UID правой таблицы и вставьте его в поле «UID целевого блока (Target block UID)». Сразу после этого отобразится интерфейс настройки условий, где можно задать область данных для правой таблицы.
7. Настройте условие, как показано на рисунке ниже:
8. После настройки области данных необходимо обновить блок, чтобы отобразить результаты фильтрации. Далее настроим обновление блока правой таблицы. Добавьте шаг «Обновить целевые блоки (Refresh target blocks)» и введите UID правой таблицы.
9. Наконец, нажмите кнопку сохранения в правом нижнем углу, и настройка будет завершена.

#Подробное описание событий

#Перед рендерингом (Before render)

Общее событие, которое можно использовать на страницах, в блоках, кнопках или полях. В этом событии можно выполнить задачи инициализации. Например, настроить различные области данных при разных условиях.

#Клик по строке (Row click)

Эксклюзивное событие для табличного блока. Запускается при нажатии на строку таблицы. При срабатывании в контекст добавляется переменная Clicked row record, которую можно использовать в условиях и шагах.

#Изменение значений формы (Form values change)

Эксклюзивное событие для блока формы. Запускается при изменении значения поля формы. В условиях и шагах можно получить значения формы через переменную Current form.

#Клик (Click)

Эксклюзивное событие для кнопок. Запускается при нажатии на кнопку.

#Время выполнения

В настройках потока событий есть два понятия, которые легко перепутать:

• Триггерное событие: когда начинать выполнение (например: Перед рендерингом, Клик по строке, Клик, Изменение значений формы и т. д.).
• Время выполнения: в какое место встроенного процесса после возникновения триггерного события должен быть вставлен ваш пользовательский поток событий.

#Что такое «встроенный процесс / встроенные шаги»?

Многие страницы, блоки или операции сами по себе имеют набор встроенных системных процессов обработки (например: отправка формы, открытие модального окна, запрос данных и т. д.). Когда вы добавляете пользовательский поток событий для того же события (например, «Клик»), «Время выполнения» определяет:

• Выполнить ли ваш поток событий до или после встроенной логики;
• Или вставить ваш поток событий до или после определенного шага встроенного процесса.

#Как понимать варианты времени выполнения в интерфейсе?

• До всех потоков (по умолчанию): выполняется первым. Подходит для «перехвата/подготовки» (например, валидация, подтверждение действия, инициализация переменных и т. д.).
• После всех потоков: выполняется после завершения встроенной логики. Подходит для «завершения/обратной связи» (например, показ уведомления, обновление других блоков, переход на страницу и т. д.).
• До указанного потока / После указанного потока: более точная точка вставки. После выбора необходимо выбрать конкретный «Встроенный процесс».
• До шага указанного потока / После шага указанного потока: максимально точная точка вставки. После выбора необходимо одновременно выбрать «Встроенный процесс» и «Шаг встроенного процесса».

Подсказка: если вы не уверены, какой встроенный процесс или шаг выбрать, приоритетно используйте первые два варианта («До» или «После»).

#Подробное описание шагов

#Пользовательская переменная (Custom variable)

Используется для определения пользовательской переменной с последующим использованием в контексте.

#Область действия

Пользовательские переменные имеют область действия. Например, переменная, определенная в потоке событий блока, может использоваться только в этом блоке. Если вы хотите, чтобы переменная была доступна во всех блоках на текущей странице, ее необходимо настроить в потоке событий страницы.

#Переменная формы (Form variable)

Использование значения определенного блока формы в качестве переменной. Настройка следующая:

• Variable title: Заголовок переменной
• Variable identifier: Идентификатор переменной
• Form UID: UID формы

#Другие переменные

Поддержка других переменных будет добавлена позже, следите за обновлениями.

#Установить область данных (Set data scope)

Установка области данных целевого блока. Настройка следующая:

• Target block UID: UID целевого блока
• Condition: Условие фильтрации

#Обновить целевые блоки (Refresh target blocks)

Обновление целевых блоков, позволяет настроить несколько блоков. Настройка следующая:

• Target block UID: UID целевого блока

#Навигация по URL (Navigate to URL)

Переход по определенному URL. Настройка следующая:

• URL: Целевой URL, поддерживает использование переменных
• Search parameters: Параметры запроса в URL
• Open in new window: Если флажок установлен, при переходе откроется новая вкладка браузера

#Показать сообщение (Show message)

Глобальное отображение информации об обратной связи операции.

#Когда использовать

• Может предоставлять информацию об успехе, предупреждении или ошибке.
• Отображается вверху по центру и автоматически исчезает. Это легкий способ уведомления, который не прерывает действия пользователя.

#Настройка

• Message type: Тип сообщения
• Message content: Содержимое сообщения
• Duration: Длительность отображения в секундах

#Показать уведомление (Show notification)

Глобальное отображение уведомлений.

#Когда использовать

Отображение уведомлений в четырех углах системы. Часто используется в следующих случаях:

• Относительно сложное содержание уведомления.
• Уведомления с интерактивными элементами, предлагающие пользователю дальнейшие действия.
• Активные системные push-уведомления.

#Настройка

• Notification type: Тип уведомления
• Notification title: Заголовок уведомления
• Notification description: Описание уведомления
• Placement: Положение, варианты: сверху слева, сверху справа, снизу слева, снизу справа

#Выполнить JavaScript (Execute JavaScript)

Выполнение кода JavaScript.

#Примеры

#Форма: вызов стороннего API для заполнения полей

Сценарий: запуск потока событий в форме для запроса к стороннему API и автоматическое заполнение полей формы полученными данными.

Шаги настройки:

1. Откройте настройку потока событий в блоке формы и добавьте новый поток;
2. В поле «Триггерное событие» выберите «Перед рендерингом (Before render)»;
3. В поле «Время выполнения» выберите «После всех потоков (After all flows)»;
4. Добавьте шаг «Выполнить JavaScript (Execute JavaScript)», вставьте и отредактируйте следующий код:

const res = await ctx.api.request({
  method: 'get',
  url: 'https://jsonplaceholder.typicode.com/users/2',
  skipNotify: true,
  // Примечание: ctx.api по умолчанию включает текущие заголовки аутентификации NocoBase.
  // Здесь мы переопределяем Authorization пустым значением, чтобы не отправлять токен третьей стороне.
  headers: {
    Authorization: 'Bearer ',
  },
});

const username = res?.data?.username;

// замените на фактическое имя поля
ctx.form.setFieldsValue({ username });