6.1. Типы данных для описания параметров

При написания виджетов важно определить природу поведения выводимых данных и их представление. Для этого используются две основные структуры данных enum PARAM_TYPE (тип параметра), ITEM_TYPE (тип элемента):

6.1.1. Тип параметра

В интерфейсах тип параметра представлен в виде enum PARAM_TYPE

export enum PARAM_TYPE {
  'signal' = 1,                // сигнальный параметр (например 0/1, true/false)
  'value' = 2,                 // мгновенное значение параметра
  'increment' = 3              // параметр, значение которого идет нарастающим итогом
}
Тип Применение Описание
signal Датчики включения, сигнализация Сигнальный тип параметра (включен, выключен) принимает значение 0 или 1
value Датчики значений Мгновенное значение параметра (температура, влажность, вольтаж)
increment Любые счетчики Параметр, значение которого идет нарастающим итогом (потребление воды, энергии, счетчик посетителей)

6.1.2. Тип элемента

Для описания типа элемента следует использовать enum ITEM_TYPE.

export enum ITEM_TYPE {
  'single' = 1,                // Одно значение
  'series' = 2,                // Ряд данных (например график)
  'events' = 3,                // Лента событий (структура с описанием события)
  'interval' = 5,              // Значение на заданном интервале (min, max, avg и т.д.)
  'table' = 6                  // Таблица значений параметров
}

В зависимости от типа элемента в виджет, в переменную values, будет передан разный набор данных, которые описываются как интерфейсы (см. таблицу).

Тип элементаОписание Интерфейс
single Единичные значения параметров ItemSingle
series Ряды данных ItemSeries
events Лента событий EventValues
interval Значения параметров на заданном интервале ItemInterval
table Таблица значений параметров ItemTable
custom Поле не требующее обработки сервера ItemCustom

Как мы видим в названиях есть различия между EventValues и другими типами. Это обусловлено тем, что events отличается по формату и способу получения данных от сервиса.

Интерфейсы ItemSingle, ItemSeries, ItemInterval, ItemCustom и ItemTable наследуются от одного интерфейса IWidgetParam и содержат в себе следующие поля:

Поле Тип Задается разработчиком Задается в конфигураторе Описание
id number - - Идентификатор параметра в сервисе
device IWidgetDeviceParam - + Информация об объекте, контроллере, параметре, зоне и состоянии параметра
widgetId number - + Идентификатор виджета
refName string + - Уникальный идентификатор параметра в пределах виджета
itemType ITEM_TYPE + - Тип элемента
title string + - Заголовок(назначение элемента)
config ParamConfig - + Настройки параметра
viewConfig IWidgetParamConfig - + Настройки отображения
borders Border[] - - Границы значений
dashboardLink { dashname?: string, id: number } - + Ссылка на дашборд
isEditing boolean - - Поле редактируется
canEditable boolean - - Значение можно изменить вручную
icons { falsevalue: string; none: string; success: string; warning: string; error: string; }; - - Сет иконок для параметра

6.1.3. Описание интерфейсов

Кроме общих полей, представленных выше, каждый интерфейс, в зависимости от типа элемента, содержит свои собственные данные. Ниже представлено их описание.

6.1.3.1. ITEM_TYPE.single

Единичные значения параметров

export interface ItemSingle extends IWidgetParam {
  value: any;
  data: SingleValue;
}

В поле data содержатся следующие данные:
Описание типа SingleValue

Поле Тип Описание
locked boolean
manually boolean
date number Время последнего изменения значения
value number string Значение параметра
state ParamState Состояние значения

Для быстро доступа к значению параметра в виджете в поле value копируется значение из data.value

6.1.3.2. ITEM_TYPE.interval

Значения параметров на заданном интервале Сам интерфейс выглядит так

export interface ItemInterval extends IWidgetParam {
  value: any;
  data: IntervalValue;
}

Описание типа IntervalValue

Поле Тип Описание
percent number Значение в процентах для relative и increment
min number Минимальное значение на интервале absolute
max number Максимальное значение на интервале absolute
date number Время последнего изменения значения
value number string Значение параметра
switchCount number Количество переключений за выбранный период
state ParamState Состояние значения
beginInterval number Дата начала интервала
endInterval number Дата окончания интервала

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

Тип Тип параметра Описание
absolute value, increment Вернет среднее значение на интервале
increment increment Вернет сумму всех значений на интервале
signal signal Вернет количество переключений
6.1.3.3. ITEM_TYPE.series

Ряды данных

export interface ItemSeries extends IWidgetParam {
  value: any;
  data: SeriesValue;
}

Описание типа SeriesValue

В зависимости от типа графика тип SeriesValue может быть SeriesCandleValue[] или SeriesLineValue[].

export type SeriesValue = Array<SeriesCandleValue | SeriesLineValue>;

Формат данных соответствует тому, что используется в http://krispo.github.io/angular-nvd3/

export interface SeriesCandleValue {
  close: number;
  high: number;
  low: number;
  open: number;
  timestmp: number;
}
// Все остальные графики
export interface SeriesLineValue {
  value: number;
  timestmp: number;
}
6.1.3.4. ITEM_TYPE.events

Лента событий Лента событий это особый тип данных, так как в отличии от остальных типов не использует конкретные параметры на конкретных объектах. Значение содержит только два поля config - и da

Поле Тип Описание
config ParamConfigEvents Настройки, заданные при конфигурировании виджета
data {rowList: Array<EventValue>;} Массив данных

Сам интерфейс выглядит так

export interface EventValues {
  data: {
    rowList: Array<EventValue>;
  };
  config: ParamConfigEvents;
}

Ниже в таблице описаны значения для EventValue

Поле Тип Описание
shortname string Тип возвращаемых событий
serialnumber string Список и относительное расположение выдаваемых атрибутов
eventid number Список и относительное расположение заголовков выдаваемых атрибутов
name string Максимальное количество выдаваемых строк в ленте
timestmp number Идентификаторы объектов
msg string Идентификаторы объектов
export interface EventValue {
  shortname: string;
  serialnumber: string;
  eventid: number;
  name: string;
  timestmp: number;
  msg: string;
}

Настройки ленты событий ParamConfigEvents

Поле Тип Описание
lineType number Тип возвращаемых событий
attrList string[] Список и относительное расположение выдаваемых атрибутов
titleList string[] Список и относительное расположение заголовков выдаваемых атрибутов
size number Максимальное количество выдаваемых строк в ленте
objectIds string[] Идентификаторы объектов
eventIds string[] Идентификаторы событий
commands string[] Идентификаторы команд
6.1.3.5. ITEM_TYPE.table

Таблица значений параметров

export interface ItemTable extends IWidgetParam {
  values: TableValues;
}
 
export type TableValues = Array<Array<ItemSingle>>;

Важная часть данных, необходимых для рендеринга табличных данных находится во viewConfig, который является полем интерфейса IWidgetParam. viewConfig является типом IWidgetParamConfig

export interface IWidgetParamConfig {
    formatValue?: string;
    view?: string;
    rows?: number;
    cols?: number;
    rowsName?: string[];
    colsName?: string[];
    visibleRow?: boolean;
    visibleCol?: boolean;
}

Описание полей

Поле Тип Описание
formatValue string Форматирование строки по правилам функции sprintf + возможно указать hh:mm:ss для отображения времени
view number Выбранный тип отображения поля (массив вариантов указывается при описании WidgetParam)
rows number Количество строк в таблице
cols number Количество столбцов в таблице
rowsName string[] Заголовки строк в таблице
colsName string[] Заголовки столбцов в таблице
visibleRow boolean Отображаются ли заголовки строк в таблице
visibleCol boolean Отображаются ли заголовки столбцов в таблице
6.1.3.6 ITEM_TYPE.custom

Произвольный тип параметра

export interface ItemCustom extends IWidgetParam {
  value: string;
}

6.2. Типы данных для описания входных параметров в виджете

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

export interface WidgetParam {
    title: string; // Название, которое будет отображено при конфигурировании виджета. Можно локализовать при использовании внутри _('') 
    item_type: ITEM_TYPE; // Тип данных (Описаны выше)
    param_type?: PARAM_TYPE; // Тип параметра (Описаны выше)
    items?: WidgetParamsChildren | WidgetArrayParam[]; // Дочерние элементы
    views?: string[];  // Варианты представлений параметра
    available?: any[]; // Ограничение для генератора случайных чисел
}

Описание полей параметра

Параметр Описание
title Заголовок, который будет использован в конфигураторе виджета, для пояснения блока данных
item_type Тип данных ITEM_TYPE
param_type Тип параметра PARAM_TYPE
items Дочерние элементы входного параметра. Может быть либо массивом входных параметров, либо объектом
available Массив ограничений значений. Используется только в среде разработки. Позволяет задать допустимые значения, например при массиве [0,1] значения параметра будут только 0 или 1
max Максимальное количество элементов массива (только если текущий объект массив)

Рекомендуется, для описания набора параметров, участвующих в виджете использовать интерфейс InputParameters. Интерфейс InputParameters тесно связана с описание интерфейса WidgetParams. Фактически InputParameters показывает в каком виде данные будут переданы виджету, а WidgetParams говорит сервису, какие данные и в каком виде требуются.

Пример использования:

interface InputParameters {
  signal: {
    config: ParamConfigSingle,
    items: Array<ItemSingle>
  };
}
 
const PARAMS: WidgetParams = {
  signal: {
    title: _('Список сигнальных значений'),
    item_type: ITEM_TYPE.single,
    items: [{
      param_type: PARAM_TYPE.signal,
      max: 8,
    }]
  }
};

В InputParameters используются структуры данных ParamConfigSingle, ParamConfigInterval, ParamConfigSeries, ParamConfigEvents, ParamConfigCustom, которые описывают атрибуты, при конфигурировании виджета пользователем. Их описание см. по ссылке.

Параметры можно описать как массивом так и объектом. Отличия между ними в описании параметра items. При указании item_type и param_type только в родительском объекте все дочерние элементы его наследуют.
Описание дочернего параметр как массива

Следующие две записи равны

const PARAMS: WidgetParams = {
  signal: {
    item_type: ITEM_TYPE.single,
    param_type: PARAM_TYPE.signal,
    items: [{
      max: 8,
    }]
  }
};
 
const PARAMS: WidgetParams = {
  signal: {
    items: [{
      item_type: ITEM_TYPE.single,
      param_type: PARAM_TYPE.signal,
      max: 8,
    }]
  }
};

Описание InputParameters должно выглядеть так

interface InputParameters {
  signal: {
    config: ParamConfigSingle,
    items: Array<ItemSingle>
  };
}

В данном случае данные, которые получит виджет будут такими:

values.signal = [ItemSingle, ItemSingle, ItemSingle]
Описание дочернего параметра как объекта
interface InputParameters {
battery: {
    charge: ItemSingle
    temperature: ItemSingle
    status: ItemSingle
  };
}
 
const PARAMS: WidgetParams = {
  battery: {
    title: _('Battery'),
    item_type: ITEM_TYPE.single,
    param_type: PARAM_TYPE.value,
    items: {
      charge: {title: _('Charge')},
      temperature: {title: _('Temperature')},
      status: {title: _('Status'), available: [1, 2, 3, 7, 9]},
    }
  },
}

Виджет получит:

values.battery = { charge: ItemSingle, temperature: ItemSingle, status:temperature: ItemSingle};

6.3. Тип данных WidgetPackage для описания выходных данных в виджете

Для сборки и правильного функционирования виджета в системе, файл виджета должен вернуть структуру WidgetPackage

const component: WidgetPackage = {
  template: require('./widget.html'),
  component: new Widget(),
  params: PARAMS,
  size: {'sm': {'x': 0, 'y': 0, 'w': 3, 'h': 6}, 'lg': {'x': 0, 'y': 0, 'w': 5, 'h': 7}, 'mobile': {'x': 0, 'y': 0, 'w': 2, 'h': 7}},
  styles: require('./widget.scss'),
  locales: [{code: 'en', file: require('./i18n/en.json')}, {code: 'ru', file: require('./i18n/ru.json')}]
};
 
export default component;
Свойства Назначение
template Содержимое шаблона виджета. Можно использовать функцию require(<путь к файлу шаблона>), либо строку
component Экземпляр класса виджета
size Размеры виджета по умолчанию для разных размеров экранов
styles Стили виджета. Можно использовать функцию require(<путь к файлу стилей>), либо строку
locales Массив с файлами для локализации виджета
needPicture Использует ли виджет изображение

6.4. Описание классов виджета

6.4.1. Класс WidgetComponentContainer

Для правильной подсветки кода в среде разработки используется конструкция WidgetComponentContainer Шаблон виджета будет передан именно классу-контейнеру.

Описание параметров и методов WidgetComponentContainer, которые можно использовать в шаблоне виджета

Параметр Назначение
values Данные от сервиса, представленные согласно описаным параметрам
component Объект, которые содержит функции и данные вашего виджета, описанного в классе Widget
theme Текущая тема SiteTheme.dark, SiteTheme.light
pictureId Идентификатор изображения. Можно использовать в шаблоне через pipe
<img [src]="pictureId | makePictureUrl"/>
CHART_TYPES Enum Типы графиков
VALUE_TYPE Enum Типы значений

Методы, которые можно использовать в виджете

Методы Назначение
openWindow(url) Открывает модальное окно
urlExport() Возвращает ссылку на экспорт данных виджета
paramCancel(par:WidgetItem) Отменяет редактирование параметра
paramEdit(par:WidgetItem) Переводит параметр в редактируемое состояние
paramSave(par:WidgetItem) Сохраняет новое значение

6.4.2. Класс Widget extends WidgetComponent

В этот класс можно разместить любую логику вашего виджета. Ниже представлены методы, которые вызываются контейнером виджета

Методы Назначение
onInit() Вызывается при инициализации компонента
onDestroy() Вызывается при уничтожении компонента
onUpdate(values) Вызывается при обновлении данных
onResize(width, height) Вызывается при любом изменении размеров виджета

Параметры, доступные в компоненте виджета

Параметр
width Ширина виджета в пикселях
height Высота виджета в пикселях

Все переменные, методы из этого класса доступны в виджете через переменную component

widget.my.ts

class Widget extends WidgetComponent {
 
  isCompact: boolean = false;
 
  toggleCompact() {
    this.isCompact = !this.isCompact; 
  }
}

widget.my.html

<div *ngIf="component.isCompact">Compact</div>
 
<button (click)="component.toggleCompact()">Toggle compact</button>

6.4.3. Класс WidgetComponentContainer

Для удобства разработки и сокращения количества ошибок в среде разработки все структуры соответствуют реальным. Для правильной работы IDE используется функция-декоратор Component, эмулирующая работу функции Component из Angular, а также специальный класс-контейнер class WidgetContainer extends WidgetComponentContainer.

@Component({
  templateUrl: './widget.my.html',
})
class WidgetContainer extends WidgetComponentContainer {
  values: InputParameters;
  component = new Widget();
}