Разработка расширения с обработчиками событий

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

Одно клиентское расширение может содержать несколько функций-обработчиков.

  1. Создайте проект клиентского расширения без публикации.

  2. Добавьте код функции-обработчика в существующий файл src/EventHandlers.tsx или в новый файл TypeScript (.ts, .tsx) в папке src.

    Следующий код демонстрирует пример функции-обработчика.

    import { Employee } from "@docsvision/webclient/BackOffice/Employee";
    import { IEventArgs } from "@docsvision/webclient/System/IEventArgs";
    import { MessageBox } from "@docsvision/webclient/Helpers/MessageBox/MessageBox";
    
    export function someHandler(sender: Employee, e: IEventArgs) { (1)
    
     MessageBox.ShowInfo(sender.params.value.displayName); (2)
    
    }
    1 Пример обработчика.
    2 Отображает сообщение с именем сотрудника.

    В первых строчках кода выполняется импорт внешних сущностей, типы которых используются в коде, из JS-модулей Web-клиента. При использовании Visual Studio Code[1] редактор автоматически подключит необходимые модули. При использовании другого редактора — обратитесь к справочнику по JS API, в котором указаны названия JS-модулей.

    Функция someHandler — реализация обработчика
    • В определении функции должно быть указано ключевое слово export.

    • Тип аргумента sender должен соответствовать типу элемента управления, событие которого обрабатывается. В примере, sender с типом Employee обрабатывается событие элемента управления Сотрудник.

    • Тип аргумента e зависит от обрабатываемого события:

      • IEventArgs — если событие вызывается после выполнения действия, т.е. не может его прервать.

      • ICancelableEventArgs — если событие вызывается при выполнении действия, т.е. может его прервать. Работа с прерываемыми действиями рассмотрена в пункте Прерывание выполнения операции.

  3. Если на шаге 2 был создан новый tsx файл, добавьте в файле src/Index.ts строку импорта его сущностей.

    import * as Handlers from "./FileWithHandlers"; (1)
    import { extensionManager } from "@docsvision/webclient/System/ExtensionManager";
    
    extensionManager.registerExtension({
     name: "My web Extension",
     version: "1.0",
     globalEventHandlers: [Handlers] (2)
    })
    1 Импорт сущностей из файла FileWithHandlers (расширение файла не указывается).
    2 В массив globalEventHandlers нужно передать ссылку на импорт сущностей из файла FileWithHandlers.
  4. Соберите проект клиентского расширения командой npm run build.

  5. Скопируйте полученный файл %BuildDir%/extension.js на сервер Web-клиента в папку /lib/docsvision/webclient/Content/Modules/%Каталог Решения%.

    Обратитесь к разделу Создание и публикация клиентского расширения, чтобы получить больше информации, связанной со сборкой проекта.
  6. Настройте обработчик в программе Конструктор Web-разметок.

  7. Откройте в программе Конструктор Web-разметок разметку, событие которой обрабатывается.

  8. Выберите элемент управления, для которого настраивается обработчик события.

  9. Укажите название функции-обработчика, реализованной в клиентском расширении, в значении события.

    Настройка обработчика для события "При смене данных" в программе Конструктор Web-разметок
    Рисунок 1. Настройка обработчика для события "При смене данных" в программе Конструктор Web-разметок
  10. Сохраните настройки разметки.

    Инструкция по работе в программе Конструктор Web-разметок приведена в документации по работе с программной Конструктор Web-разметок.
  11. Откройте локацию с настроенной разметкой (например, карточку) и выполните действие, вызывающее реализованный обработчик.

  12. После завершения отладки скрипта, соберите и опубликуйте на сервере Web-клиента "релизную версию" клиентского расширения. "Релизная версия" собирается командой npm run build:prod.

Получить все обработчики событий

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

(function getHandlers(sender) {
    let controlsVisitor = new WebClient.ControlsRecursiveVisitor();
    controlsVisitor.visitDeep(sender.layout, (control) => {
        const paramsKey = Object.keys(control.params);
        const eventsKey = paramsKey.filter(key => control.params[key] instanceof WebClient.BasicEvent);
        const handlers = eventsKey.reduce((handlers, key) =>
            control.props[key] && !handlers.includes(control.props[key])
                ? `${control.props[key]}${handlers.length ? ', ' : ''}${handlers}`
                : handlers
            , "");
        if (handlers !== "") {
            console.info(`${control.props.name}: ${handlers}`);
        }
    });
})(layoutManager.cardLayout);

1. Рекомендуется использовать Visual Studio Code 2022.