Visual-API

  • Artikel

Alle visuellen Elemente beginnen mit einer Klasse, mit der die IVisual-Schnittstelle implementiert wird. Sie können der Klasse einen beliebigen Namen geben. Es muss nur genau eine Klasse für die Implementierung der IVisual-Schnittstelle vorhanden sein.

Hinweis

Der Name der Visualklasse muss mit dem Namen von visualClassName in der Datei pbiviz.json übereinstimmen.

Die Visualklasse sollte die folgenden Methoden wie im folgenden Beispiel gezeigt implementieren:

  • constructor: Ein Standardkonstruktor, der den Zustand des Visuals initialisiert
  • update: Aktualisiert die Daten des Visuals
  • getFormattingModel, gibt ein Formatierungsmodell zurück, das den Eigenschaftsbereich (Formatierungsoptionen) füllt, wo Sie Eigenschaften nach Bedarf ändern können
  • destroy: Ein Standarddestruktor für Bereinigungen
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

Der constructor der visuellen Klasse wird beim Instanziieren des Visuals aufgerufen. Er kann für alle vom Visual benötigten Setupvorgänge verwendet werden.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

Diese Schnittstellen werden bei jeder neuen API-Version aktualisiert. Das aktuelle Schnittstellenformat finden Sie in unserem GitHub-Repository.

In der folgenden Liste werden einige der Eigenschaften der VisualConstructorOptions-Schnittstelle beschrieben:

  • element: HTMLElement: Ein Verweis auf das DOM-Element, das das Visual enthält

  • host: IVisualHost: Eine Reihe von Eigenschaften und Diensten, die für die Interaktion mit dem Visualhost (Power BI) verwendet werden können

    IVisualHost enthält die folgenden Dienste:

    • createSelectionIdBuilder: Generiert und speichert Metadaten für auswählbare Elemente im Visual
    • createSelectionManager: Erstellt die Kommunikationsbrücke, die verwendet wird, um den Host des Visuals über Änderungen beim Auswahlzustand zu benachrichtigen. Weitere Informationen finden Sie unter Selection-API.
    • hostCapabilities
    • refreshHostData
    • downloadService: Gibt erweiterte Ergebnisinformationen des Downloads zurück.
    • eventService: Gibt Informationen zu Renderingereignissen zurück.
    • hostEnv
    • displayWarningIcon: Gibt eine Fehler- oder Warnmeldung zurück.
    • licenseManager: Gibt Lizenzinformationen zurück.
    • createLocalizationManager: Generiert einen Manager zur Unterstützung bei der Lokalisierung.
    • applyJsonFilter: Wendet bestimmte Filtertypen an. Siehe Filter-API.
    • applyCustomSort: Ermöglicht benutzerdefinierte Sortieroptionen.
    • acquireAADTokenService: Gibt die Microsoft Entra ID-Authentifizierungsinformationenzurück.
    • webAccessService: Gibt den Berechtigungsstatus für den Zugriff auf Remoteressourcen zurück.
    • openModalDialog: Gibt ein Dialogfeld zurück.
    • persistProperties: Ermöglicht Benutzer*innen, beständige Einstellungen zu erstellen und zusammen mit der Definition des Visuals zu speichern, sodass sie beim nächsten erneuten Laden verfügbar sind.
    • eventService: Gibt einen Ereignisdienst zur Unterstützung von Renderingereignissen zurück.
    • storageService: Gibt einen Dienst zur Unterstützung der Verwendung von lokalem Speicher im Visual zurück.
    • storageV2Service: Gibt einen Dienst zur Unterstützung der Verwendung von Version 2 des lokalen Speichers im Visual zurück.
    • tooltipService: Gibt einen QuickInfo-Dienst zur Unterstützung der Verwendung von QuickInfos im Visual zurück.
    • telemetry
    • drill
    • launchUrl: Unterstützt das Starten der URL auf der nächsten Registerkarte.
    • authenticationService: Gibt ein Microsoft Entra ID-Token zurück.
    • locale: Gibt eine Zeichenfolge des Gebietsschemas zurück. Siehe hierzu Lokalisierung.
    • instanceId: Gibt eine Zeichenfolge zum Identifizieren der aktuellen Visualinstanz zurück.
    • colorPalette: Gibt die Farbpalette (colorPalette) zurück, die zum Anwenden von Farben auf Ihre Daten benötigt wird.
    • fetchMoreData: Unterstützt die Verwendung einer größeren Datenmenge als dies das Standardlimit (1.000 Zeilen) vorsieht. Siehe Abrufen zusätzlicher Daten.
    • switchFocusModeState: Unterstützt die Änderung des Fokusmoduszustands.

Aktualisierung

Alle visuellen Elemente müssen eine Methode zum öffentlichen Aktualisieren implementieren, die immer dann aufgerufen wird, wenn eine Änderung in der Daten -oder Hostumgebung vorgenommen wird.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport: Dimensionen des Viewports, in dem das Visual gerendert werden soll
  • dataViews: DataView[]: Das DataView-Objekt, das alle zum Rendern des Visuals benötigten Daten enthält (normalerweise wird die kategorische Eigenschaft unter DataView verwendet)
  • type: VisualUpdateType: Flags, um den Datentyp anzugeben, der aktualisiert wird (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode: Flags, die den Ansichtsmodus des Visuals angeben (View | Edit | InFocusEdit)
  • editMode: EditMode: Flag, das den Bearbeitungsmodus des Visuals angibt (Default | Advanced) (Wenn das Visual AdvancedEditMode unterstützt, werden dessen erweiterte Steuerelemente auf der Benutzeroberfläche nur dann gerendert, wenn editMode auf Advanced festgelegt ist. Weitere Informationen finden Sie unter AdvancedEditMode.)
  • operationKind?: VisualDataChangeOperationKind: Flag, das den Typ der Datenänderung angibt (Create | Append)
  • jsonFilters?: IFilter[]: Sammlung von angewendeten JSON-Filtern
  • isInFocus?: boolean: Flag, das angibt, ob sich das Visual im Fokusmodus befindet

getFormattingModel (optional)

Diese Methode wird einmal aufgerufen, wenn der Eigenschaftenbereich geöffnet wird oder der Benutzer eine der Eigenschaften im Bereich bearbeitet. Sie gibt FormattingModel mit allen Informationen zum Eigenschaftenbereichsentwurf, der Hierarchie, den Eigenschaften und den neuesten Formatierungswerten zurück.

getFormattingModel(): visuals.FormattingModel;

destroy (optional)

Die Funktion „destroy“ (Löschen) wird aufgerufen, wenn das Visual entladen ist, und dient zu Bereinigungsaufgaben, z. B. zum Entfernen von Ereignislistenern.

public destroy(): void

Tipp

Power BI ruft die Funktion destroy in der Regel nicht auf, da es schneller ist, den gesamten IFRAME mit dem visuellen Element zu entfernen.

Zugehöriger Inhalt