Interfejs API wizualizacji

  • Artykuł

Wszystkie wizualizacje zaczynają się od klasy, która implementuje IVisual interfejs. Możesz nazwać klasę tak długo, jak tylko istnieje dokładnie jedna klasa, która implementuje IVisual interfejs.

Uwaga

Nazwa klasy wizualizacji musi być taka sama jak visualClassName w pbiviz.json pliku .

Klasa wizualizacji powinna zaimplementować następujące metody, jak pokazano w poniższym przykładzie:

  • constructor — standardowy konstruktor, który inicjuje stan wizualizacji
  • update — aktualizuje dane wizualizacji
  • getFormattingModel, zwraca model formatowania, który wypełnia okienko właściwości (opcje formatowania), w którym można modyfikować właściwości zgodnie z potrzebami
  • destroy - standardowy destruktor do oczyszczania
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)
    }
}

— konstruktor

Klasa constructor wizualizacji jest wywoływana po utworzeniu wystąpienia wizualizacji. Można go używać w przypadku dowolnych operacji konfiguracji, których potrzebuje wizualizacja.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

Te interfejsy są aktualizowane przy użyciu każdej nowej wersji interfejsu API. Aby uzyskać najbardziej zaktualizowany format interfejsu, przejdź do naszego repozytorium GitHub.

Poniższa lista zawiera opis niektórych właściwości interfejsu VisualConstructorOptions :

  • element: HTMLElement — odwołanie do elementu DOM zawierającego wizualizację

  • host: IVisualHost — kolekcja właściwości i usług, których można użyć do interakcji z hostem wizualizacji (Power BI)

    IVisualHost zawiera następujące usługi:

    • createSelectionIdBuilder — generuje i przechowuje metadane dla wybranych elementów w wizualizacji
    • createSelectionManager — tworzy mostek komunikacyjny używany do powiadamiania hosta wizualizacji o zmianach w stanie wyboru, zobacz Interfejs API wyboru.
    • hostCapabilities
    • refreshHostData
    • downloadService— zwraca rozszerzone informacje o wynikach pobierania.
    • eventService — zwraca informacje o zdarzeniach renderowania.
    • hostEnv
    • displayWarningIcon — zwraca komunikat o błędzie lub ostrzeżeniu.
    • licenseManager — zwraca informacje o licencji.
    • createLocalizationManager — generuje menedżera, aby pomóc w lokalizacji
    • applyJsonFilter — stosuje określone typy filtrów. Zobacz interfejs API filtrowania
    • applyCustomSort — umożliwia niestandardowe opcje sortowania.
    • acquireAADTokenService— zwraca informacje o uwierzytelnianiu identyfikatora Entra firmy Microsoft.
    • webAccessService — zwraca stan uprawnień na potrzeby uzyskiwania dostępu do zasobów zdalnych.
    • openModalDialog — zwraca okno dialogowe.
    • persistProperties — umożliwia użytkownikom tworzenie ustawień trwałych i zapisywanie ich wraz z definicją wizualizacji, dzięki czemu są one dostępne podczas następnego ponownego ładowania
    • eventService— zwraca usługę zdarzeń do obsługi zdarzeń renderowania
    • storageService — zwraca usługę, aby ułatwić korzystanie z magazynu lokalnego w wizualizacji
    • storageV2Service — zwraca usługę, aby ułatwić korzystanie z magazynu lokalnego w wersji 2 w wizualizacji
    • tooltipService— zwraca usługę etykietki narzędzi, aby ułatwić korzystanie z etykietek narzędzi w wizualizacji
    • telemetry
    • drill
    • launchUrl — ułatwia uruchamianie adresu URL na następnej karcie
    • authenticationService — zwraca token identyfikatora Entra firmy Microsoft.
    • locale - zwraca ciąg ustawień regionalnych, zobacz Lokalizacja
    • instanceId — zwraca ciąg w celu zidentyfikowania bieżącego wystąpienia wizualizacji
    • colorPalette — zwraca kolorPalette wymagany do zastosowania kolorów do danych
    • fetchMoreData — obsługuje używanie większej ilości danych niż limit standardowy (1000 wierszy). Zobacz Pobieranie większej ilości danych
    • switchFocusModeState - pomaga zmienić stan trybu koncentracji uwagi

update

Wszystkie wizualizacje muszą zaimplementować publiczną metodę aktualizacji, która jest wywoływana za każdym razem, gdy nastąpi zmiana w środowisku danych lub hosta.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport - wymiary widoku, w których wizualizacja powinna być renderowana w obrębie
  • dataViews: DataView[] — obiekt widoku danych zawierający wszystkie dane potrzebne do renderowania wizualizacji (wizualizacja zazwyczaj używa właściwości kategorii w widoku DataView)
  • type: VisualUpdateType— flagi wskazujące typ aktualizowanych danych (Zmiana rozmiaru widokuMode | | danych— Zmiana | rozmiaru styluEnd) |
  • viewMode: ViewMode— flagi wskazujące tryb wyświetlania wizualizacji (Wyświetl | edycję | inFocusEdit)
  • editMode: EditMode— flaga wskazująca tryb edycji wizualizacji (ustawienie domyślne | zaawansowane) (jeśli wizualizacja obsługuje tryb AdvancedEditMode, powinna renderować zaawansowane kontrolki interfejsu użytkownika tylko wtedy, gdy tryb editMode jest ustawiony na wartość Zaawansowane, zobacz AdvancedEditMode)
  • operationKind?: VisualDataChangeOperationKind— flaga wskazująca typ zmiany danych (Utwórz | dołączanie)
  • jsonFilters?: IFilter[] - kolekcja zastosowanych filtrów json
  • isInFocus?: boolean — flaga wskazująca, czy wizualizacja jest w trybie koncentracji uwagi, czy nie

getFormattingModel (opcjonalnie)

Ta metoda jest wywoływana za każdym razem, gdy otworzymy okienko właściwości lub użytkownik edytuje dowolne właściwości w okienku. Zwraca FormattingModel wszystkie informacje dotyczące projektowania, hierarchii, właściwości i najnowszych wartości formatowania okienka właściwości.

getFormattingModel(): visuals.FormattingModel;

destroy (opcjonalnie)

Funkcja destroy jest wywoływana, gdy wizualizacja zostanie zwolniona i może służyć do wykonywania zadań oczyszczania, takich jak usuwanie odbiorników zdarzeń.

public destroy(): void

Napiwek

Usługa Power BI zwykle nie wywołuje wywołania destroy , ponieważ szybciej usuwa cały element IFrame zawierający wizualizację.

Powiązana zawartość