Share via

Визуальный API

  • Статья

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

Примечание.

Имя визуального visualClassNamepbiviz.json класса должно совпадать с именем в файле.

Визуальный класс должен реализовать следующие методы, как показано в следующем примере:

  • constructor — стандартный конструктор, который инициализирует состояние визуального элемента
  • update — обновляет данные визуального элемента
  • getFormattingModel, возвращает модель форматирования, которая заполняет область свойств (параметры форматирования), где можно изменять свойства по мере необходимости.
  • destroy — стандартный деструктор для очистки
class MyVisual implements IVisual {
    
    constructor(options: VisualConstructorOptions) {
        //one time setup code goes here (called once)
    }
    
    public update(options: VisualUpdateOptions): void {
        //code to update your visual goes here (called on all view or data changes)
    }

    public getFormattingModel(): FormattingModel {
        // returns modern format pane formatting model that contain all format pane components and properties (called on opening format and analytics pane or on editing format properties)
    }
    
    public destroy(): void {
        //one time cleanup code goes here (called once)
    }
}

конструктор

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

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

Эти интерфейсы обновляются с каждой новой версией API. Чтобы получить самый обновленный формат интерфейса, перейдите в репозиторий GitHub.

В следующем списке описаны некоторые свойства VisualConstructorOptions интерфейса:

  • element: HTMLElement — ссылка на элемент DOM, содержащий визуальный элемент.

  • host: IVisualHost — коллекция свойств и служб, которые можно использовать для взаимодействия с визуальным узлом (Power BI)

    IVisualHost содержит следующие службы:

    • createSelectionIdBuilder — создает и сохраняет метаданные для выбранных элементов в визуальном элементе
    • createSelectionManager — создает мост связи, используемый для уведомления узла визуального элемента об изменениях в состоянии выделения, см. в разделе API выбора.
    • hostCapabilities
    • refreshHostData
    • downloadService — возвращает развернутые сведения о результатах скачивания.
    • eventService — возвращает сведения о событиях отрисовки.
    • hostEnv
    • displayWarningIcon — возвращает сообщение об ошибке или предупреждении.
    • licenseManager — возвращает сведения о лицензии.
    • createLocalizationManager — создает диспетчер для поддержки локализации
    • applyJsonFilter — применяет определенные типы фильтров. См. API фильтрации
    • applyCustomSort — разрешает настраиваемые параметры сортировки.
    • acquireAADTokenService— возвращает сведения о проверке подлинности идентификатора Microsoft Entra.
    • webAccessService — возвращает состояние разрешения для доступа к удаленным ресурсам.
    • openModalDialog — возвращает диалоговое окно.
    • persistProperties — позволяет пользователям создавать постоянные параметры и сохранять их вместе с визуальным определением, чтобы они были доступны при следующей перезагрузке.
    • eventService— возвращает службу событий для поддержки событий отрисовки
    • storageService — возвращает службу для использования локального хранилища в визуальном элементе
    • storageV2Service — возвращает службу для использования локального хранилища версии 2 в визуальном элементе
    • tooltipService— возвращает службу подсказки для использования подсказок в визуальном элементе.
    • telemetry
    • drill
    • launchUrl — помогает запустить URL-адрес на следующей вкладке
    • authenticationService — возвращает маркер идентификатора Microsoft Entra.
    • locale — возвращает строку языкового стандарта, см. раздел "Локализация"
    • instanceId — возвращает строку для идентификации текущего визуального экземпляра.
    • colorPalette — возвращает colorPalette, необходимый для применения цветов к данным.
    • fetchMoreData — поддерживает использование большего числа данных, чем стандартное ограничение (1000 строк). Дополнительные сведения см. в разделе " Получение дополнительных данных"
    • switchFocusModeState — помогает изменить состояние режима фокусировки

обновить

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

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport — измерения окна просмотра, в который должен отображаться визуальный элемент.
  • dataViews: DataView[] — объект представления данных, содержащий все данные, необходимые для отрисовки визуального элемента (визуальный элемент обычно использует категориальное свойство в DataView)
  • type: VisualUpdateType— флаги, указывающие тип обновляемых данных ( | Data Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode— флаги, указывающие режим представления визуального элемента (просмотр | правки | InFocusEdit)
  • editMode: EditMode— флаг, указывающий режим редактирования визуального элемента (дополнительно по умолчанию | ) (если визуальный элемент поддерживает AdvancedEditMode, он должен отображать расширенные элементы управления пользовательского интерфейса только в том случае, если параметр editMode имеет значение Advanced, см. раздел AdvancedEditMode).
  • operationKind?: VisualDataChangeOperationKind — флаг, указывающий тип изменения данных (создание | добавления)
  • jsonFilters?: IFilter[] — коллекция примененных фильтров JSON
  • isInFocus?: boolean — флаг, указывающий, находится ли визуальный элемент в режиме фокусировки или нет

getFormattingModel (необязательно)

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

getFormattingModel(): visuals.FormattingModel;

destroy (необязательно)

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

public destroy(): void

Совет

Power BI обычно не вызывается destroy , так как это быстрее, чтобы удалить весь IFrame, содержащий визуальный элемент.

Связанный контент