Настройка виджетов с помощью JavaScript API

Owned by Эдуард Столяр, created
Last updated: янв. 26, 2024
5 min read

Вы можете настраивать существующие виджеты с помощью JavaScript API. Для этой цели вы можете использовать функции, описанные ниже.

API доступен в редакторе кода виджета в Visiology Designer.

Методы

visApi().setFilterSelectedValues(widgetGuid, values, handler) void

Устанавливает фильтр в виджете.

widgetGuid: string - guid виджета, на котором хотим установить фильтр.

values: string[][] - массив массивов значений, которые нужно установить, как фильтр. Пример: [["Москва"], ["Казань"]]. Для сброса фильтра необходимо передать пустой массив: [].

handler: Function() => void - Функция обратной связи, которая вызывается после того, как фильтр был установлен.

visApi().setDateFilterSelectedValues(widgetGuid, values) void

Устанавливает выбранные даты в виджете Фильтр по датам.

widgetGuid: string - guid виджета, на котором хотим установить фильтр.

values: Date[][] - массив дат, которые нужно установить в фильтр по датам. Пример для множественного выбора (от и до): [new Date(), new Date()]. Пример для единичного выбора: [new Date()]. Для сброса фильтра необходимо передать пустой массив: [].

visApi().getWidgetDataByGuid(widgetGuid) Promise<{ data: DataFrame, selected : string[][] }>

Возвращает данные виджета. Асинхронная функция. На данный момент не работает для Сводной таблицы и Таблицы.

widgetGuid: string - guid виджета, данные которого необходимо получить.

Возвращаемый ответ: data: DataFrame - данные виджета. selected: string[][] - массив выбранных значений (фильтров).

visApi().getSelectedValues(widgetGuid) string[][] = [[" Москва ", " 2020 "], [" Казань ", "2021"]]

Возвращает выбранные значения (фильтры) на виджете.

visApi().getFilterIsOpen(widgetGuid) boolean

Возвращает состояние выпадающего списка в виджете «Фильтр».

visApi().getDrillLevel(widgetGuid) number

Возвращает текущий уровень drilldown в виджете (гистограмма, круговая, график).

widgetGuid: string - guid виджета, уровень drilldown которого нужно получить.

visApi().getDrillPath(widgetGuid) string[][]

Возвращает путь к текущему уровню drilldown в виджете (гистограмма, круговая, график).

widgetGuid: string - guid виджета, путь к текущему уровню drilldown которого нужно получить.

visApi().drillDown(widgetGuid, values) void

Производит drilldown (проваливание на следующий уровень) в виджете.

widgetGuid: string - guid виджета, в котором нужно произвести drilldown.

values: string[] - значение, по которому нужно произвести drilldown. Передается массив, так как на одном уровне может быть разбиение по нескольким измерениям. Если передать null, то drilldown произойдет по выбранным значениям на виджете.

visApi().exportWidgetData("xxx")

Экспортирует данные виджета в Excel-файл.

xxx – идентификатор виджета.

visApi().drillUp(widgetGuid) void

Производит drillup (возвращает на один уровень вверхе после drilldown) в виджете.

widgetGuid: string - guid виджета, в котором нужно произвести drillup.

visApi().setExcludeFilterSelectedValues(widgetGuid, values, handler) void

Устанавливает исключающий фильтр в виджете.

widgetGuid: string - guid виджета, на котором вы хотие установить фильтр.

values: string[][] - массив массивов значений, которые нужно установить как фильтр. Пример: [["Москва"], ["Казань"]]. Для сброса фильтра необходимо передать пустой массив: [].

handler: Function() => void - Функция обратной связи, которая вызывается после того, как фильтр был установлен.

Функции, структуры ответов которых могут часто изменяться

В данном разделе приводятся функции, структуры ответов которых могут часто изменяться. Поэтому данные функции не рекомендуется использовать.

visApi().getWidgets() object[]

Возвращает объекты всех виджетов на выбранном листе. Имеет сложную структуру для каждого типа виджета.

visApi().getSelectedWidgets() object[]

Возвращает объекты выделенных виджетов на выбранном листе. Имеет сложную структуру для каждого типа виджета.

visApi().getWidgetByGuid(widgetGuid) object

Возвращает объект виджета на выбранном лист. Имеет сложную структуру для каждого типа виджета.

widgetGuid: string - guid виджета, который нужно получить.

 

События

visApi().onSelectedValuesChangedListener({ guid, widgetGuid }, handler) void

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

guid: string - произвольный  guid подписываемого события. Используется, чтобы в памяти не накапливались подписки. Если повторно использовать эту же функцию с таким же guid, то старая подписка отпишется.

widgetGuid: string - guid виджета, на изменение выбранных значений (фильтров) которого нужно подписаться.

handler: Function({ widgetGuid: string, filter: WidgetDataFilter, selectedValues: string[][]) => void - Функция обратной связи, которая вызывается при изменении выбранных значений (фильтров) на виджете. filter: WidgetDataFilter - информация о фильтре. widgetGuid: string - guid виджета, в котором изменили выбранные значения. selectedValues: string[][] - выбранные значения.

visApi().onWidgetLoadedListener({ guid, widgetGuid }, handler) void

Подписка на загрузку виджета.

guid: string - произвольный guid подписываемого события. Используется, чтобы в памяти не накапливались подписки. Если повторно использовать эту же функцию с таким же guid, то старая подписка отпишется.

widgetGuid: string - guid виджета, на загрузку которого нужно подписаться.

handler: Function({ widgetGuid: string }) => void  - функция обратной связи, которая вызывается после загрузки виджета. Если виджет уже загрузился, то функция сработает сразу. widgetGuid: string - guid виджета, который загрузился. Примечание: функция вызывается сразу после выполнения js кода виджета, не дожидаясь его отрисовки.

visApi().onAllWidgetsLoadedListener({ guid }, handler) void

Подписка на загрузку виджета.

guid: string - произвольный guid подписываемого события. Используется, чтобы в памяти не накапливались подписки. Если повторно использовать эту же функцию с таким же guid, то старая подписка отпишется.

handler: Function() => void - функция обратной связи, которая вызывается после загрузки всех виджетов. Примечание: функция вызывается сразу после выполнения js кода последнего виджета, не дожидаясь его отрисовки.

visApi().onFilterIsOpenChangedListener({ guid, widgetGuid }, handler) void

Подписка на загрузку виджета.

guid: string - произвольный guid подписываемого события. Используется, чтобы в памяти не накапливались подписки. Если повторно использовать эту же функцию с таким же guid, то старая подписка отпишется.

widgetGuid: string - guid виджета «Фильтр», на открытие выпадающего списка которого нужно подписаться.

handler: Function({ widgetGuid: string, isOpen: boolean }) => void  - Функция обратной связи, которая вызывается после открытия/закрытия выпадающего списка в виджете «Фильтр». widgetGuid: string - guid виджета «Фильтр», выпадающий список которого открыли/закрыли. isOpen: boolean - true, если выпадающий список открыт.

visApi().onDrillDownListener({ guid, widgetGuid }, handler) void

Подписка на drilldown в виджете (гистограмма, круговая, график).

guid: string - произвольный guid подписываемого события. Используется, чтобы в памяти не накапливались подписки. Если повторно использовать эту же функцию с таким же guid, то старая подписка отпишется.

widgetGuid: string - guid виджета, на drilldown которого нужно подписаться.

handler: Function({ widgetGuid: string, widgetDataContainer: WidgetDataContainer, hierarchyPath: string[][], selectedValues: string[][] }) => void  - Функция обратной связи, которая вызывается после того, как произошел drilldown в виджете. widgetGuid: string - guid виджета, у которого происходит drilldown. widgetDataContainer: WidgetDataContainer - данные виджета после drilldown. hierarchyPath: string[][] - путь к текущему уровню. selectedValues: string[][] - выбранное значение при drilldown.

visApi().onDrillUpListener({ guid, widgetGuid }, handler) void

Подписка на drillup в виджете (гистограмма, круговая, график).

guid: string - произвольный guid подписываемого события. Используется, чтобы в памяти не накапливались подписки. Если повторно использовать эту же функцию с таким же guid, то старая подписка отпишется.

widgetGuid: string - guid виджета, на drillup которого нужно подписаться.

handler: Function({ widgetGuid: string, hierarchyPath: string[][] }) => void  - Функция обратной связи, которая вызывается после того, как произошел drillup в виджете. widgetGuid: string - guid виджета, у которого происходит drilldown. hierarchyPath: string[][] - путь к текущему уровню.

visApi().onBeforeDrillDownListener({ guid, widgetGuid }, handler) void

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

guid: string - произвольный guid подписываемого события. Используется, чтобы в памяти не накапливались подписки. Если повторно использовать эту же функцию с таким же guid, то старая подписка отпишется.

widgetGuid: string - guid виджета, на который нужно подписаться.

handler: Function({ widgetGuid: string, hierarchyPath: string[][], selectedValues: string[][] }) => void  - Функция обратной связи, которая вызывается перед загрузкой данных для drilldown в виджете. widgetGuid: string - guid виджета, у которого происходит drilldown. hierarchyPath: string[][] - путь к текущему уровню. selectedValues: string[][] - выбранное значение при drilldown.

 

Описание объектов

DataFrame

primaryData: DataFrameItem - объект, который хранит данные, сгруппированные по первому измерению (гистограмма, график и т.д.).

secondaryData: DataFrameItem - объект, который хранит данные, сгруппированные по второму измерению (сводная таблица). Может быть пустым, если группируется только по одному измерению.

DataFrameItem

key: object - значение, по которому, сгруппированы Items.

values: List<object> - значения показателей по сгруппированному элементу.

items: List<DataFrameItem> - объект, который хранит данные, сгруппированные по одному измерению. Если группируем по нескольким измерениям, будет вложенный Items внутри каждого отдельно взятого item.

metadata: List<ValueMetadata> - метаданные показателей.

ValueMetadata

displayName: string - отображаемое название столбца.

columnName: string - оригинальное название столбца.

dataType: string - тип данных столбца.

WidgetDataFilter

type: FilterType - тип фильтра.

values: string[][] - выбранные значения в случае, когда type равен In.

columns: Column[] - список колонок, по которым идет фильтрация.

from: Date | null - выбранная дата "от" в случае, когда type равен Between.

to: Date | null - выбранная дата "до" в случае, когда type равен Between.