Определение виджета

В проекте используется библиотека @infomaximum/widget-sdk. Она содержит вспомогательные функции и основные интерфейсы, которые являются контрактами между разрабатываемыми виджетами и системой, в которой они будут использоваться. Также в библиотеке содержатся некоторые утилитные функции для удобства разработки.

Программный код виджета:

import {
  type IWidget,
  IGroupSettings,
  type ICustomWidgetProps,
} from "@infomaximum/widget-sdk";
import { type WidgetSettings } from "definition/settings";

declare class CustomWidget implements IWidget<WidgetSettings> {
  public static definition: IDefinition<WidgetSettings, IGroupSettings>

  public initialize(container: HTMLElement): void

  public update(
    container: HTMLElement,
    props: ICustomWidgetProps<WidgetSettings>
  ): void

  public mount(
    container: HTMLElement,
    props: ICustomWidgetProps<WidgetSettings>
  ): void

  public unmount(): void
}

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

interface IWidget<WidgetSettings extends IBaseWidgetSettings> {
    initialize(container: HTMLElement): void;
    mount(container: HTMLElement, props: ICustomWidgetProps<WidgetSettings>): void;
    update(container: HTMLElement, props: ICustomWidgetProps<WidgetSettings>): void;
    unmount(container: HTMLElement): void;
}

Методы жизненного цикла виджета:

• initialize(container) — метод вызывается при добавлении виджета в дашборд и после загрузки исходного кода виджета. В методе можно инициализировать библиотеку отображения, создать дополнительные DOM-элементы и подготовить виджет перед вызовом метода mount
• mount(container, props) — метод вызывается после добавления виджета в дашборд в тот момент, когда система будет готова отобразить виджет. В методе можно начать отображать виджет
• update(container, props) — метод вызывается каждый раз при обновлении props и появлении необходимости выполнить перерисовку виджета
• unmount(container) — метод вызывается, когда происходит размонтирование виджета, например, пользователь удаляет виджет со страницы дашборда

Параметры методов жизненного цикла:

• container: HTMLElement — DOM-элемент, в котором будет отображаться виджет
• props: ICustomWidgetProps<WidgetSettings> — объект props, содержит информацию, которую система передаёт виджетам, например, используемый системой язык, информация о дашборде, настройки, фабрику вычислителей и др. Подробнее о содержании объекта можно узнать из интерфеса ICustomWidgetProps
  • widget/manidest.json — содержимое манифеста виджета (manifest.json), из которого можно получить дополнительную информацию о виджете
  • bodyElement — DOM-элемент body родительского приложения
  • formatting — содержит инструменты для выполнения форматирования данных в виджетах
    • getFormattedValue — функция, выполняющая форматирование для различных типов данных
• getWidgetAsset — с помощью функции можно запросить дополнительные ресурсы, которые может содержать виджет (файлы должны находиться в директории указанной в конфигурации виджета assetsDir)
• guid — уникальный идентификатор виджета
• settings — содержит значения настроек виджета, которые были сконфигурированы в методе createPanelDescription
• filtration — фильтрация данных (добавление, удаление фильтров)
• subscribeOnFocusOut — функция для подписки на расфокусировку виджета (например, фокусировка на другом виджете)
• captureFocus — функция, позволяющая захватить фокус, остальные виджеты будут оповещены о расфокусировке
• calculatorFactory — фабрика вычислителей, содержит следующие типы вычислителей:
  • general — общий вычислитель или вычислитель с одним лимитом
  • pie — вычислитель круговой диаграммы с одним разрезом
  • processGraph — вычислитель для компонента «Карта процесса»
  • histogram — вычислитель компонента «Гистограмма»
  • twoLimits — вычислитель для компонента с двумя лимитами
  • type — вычислитель типа
• rootViewContainer — корневой контейнер дашборда (DOM-элемент)
• placeholder — объект для управления плейсхолдером виджета (отображение ошибки и др.)
• widgetsContext — объект контекста виджета, содержит дополнительную информацию для виджета
  • language — текущий язык системы
  • processes — настроенные процессы дашборда
  • reportMeasures — общие меры дашборда
  • workspaceMeasures — общие меры пространства
  • variables — переменные дашборда
  • setVariableValue — функция для установки переменной дашборда
  • statesGuids — коллекция уникальных идентификаторов (guid) состояний
  • reportName — имя дашборда
  • displayMode — режим отображения виджета (full в режиме просмотра отчета)
  • scripts — доступные скрипты
  • tables — доступные таблицы
• launchAction — вызывает модальное окно для запуска действия

Кроме методов жизненного цикла у класса виджета есть статические поля.

Статические поля

definition — экземпляр класса, реализующего интерфейс IDefinition. Класс содержит методы для конфигурирования виджета (панель настроек, заполнение настроек, разрезы, меры и др.).

import type {
  IDefinition,
  IGroupSettings,
  IPanelDescription,
  IWidgetDimension,
  IWidgetDimensionHierarchy,
  IWidgetMeasure,
  IWidgetsContext,
} from "@infomaximum/widget-sdk";

declare class Definition implements IDefinition<WidgetSettings, IGroupSettings> {
  public createPanelDescription(
    context: IWidgetsContext,
    settings: WidgetSettings
  ): IPanelDescription<WidgetSettings>;

  public fillSettings(settings: Partial<WidgetSettings>, context: IWidgetsContext): void;

  public getDimensions(settings: WidgetSettings): (IWidgetDimension | IWidgetDimensionHierarchy)[];

  public getMeasures(settings: WidgetSettings): IWidgetMeasure[];
}

Методы описания виджета:

• settings — объект настроек виджета, содержит в себе значения настроек виджета которые были сконфигурированы для панели настроек
• context — объект контекста виджета, содержит в себе информацию о процессах, переменных отчета, языке системы и др. Подробнее можно узнать из интерфейса IWidgetsContext

Методы:

• createPanelDescription(context, settings) — возвращает конфигурацию панели настроек. Метод обязательно должен присутствовать в классе виджета
• fillSettings(settings, context) — служит для заполнения настроек значениями по умолчанию. Метод обязательно должен присутствовать в классе виджета
• getDimensions(settings) — возвращает список разрезов из настроек
• getMeasures(settings) — возвращает список мер из настроек

После создания виджета его необходимо зарегистрировать в системе. Используйте для этого функцию defineWidget:

import manifest from "../manifest.json";
...
...
...
window.im.defineWidget(manifest.uuid, CustomWidget);

Регистрация виджета в системе происходит по уникальному идентификатору uuid (v4), который был сгенерирован в момент создания проекта и указан в манифесте виджета.