API de visuel

  • Article

Tous les éléments visuels commencent par une classe qui implémente l’interface IVisual. Vous pouvez nommer la classe comme vous le souhaitez, tant qu’il existe exactement une classe qui implémente l’interface IVisual.

Notes

Le nom de la classe de visuel doit être identique au visualClassName dans le fichier pbiviz.json.

La classe de visuel doit implémenter les méthodes suivantes, comme indiqué dans l’exemple ci-dessous :

  • constructor - constructeur standard pour initialiser l’état du visuel
  • update - met à jour les données du visuel
  • getFormattingModel retourne un modèle de mise en forme qui remplit le volet de propriétés (options de mise en forme) où vous pouvez les modifier en fonction de vos besoins.
  • destroy - destructeur standard pour le nettoyage
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

Le constructor de la classe de visuel est appelé quand le visuel est instancié. Il peut être utilisé pour toutes les opérations de configuration dont le visuel a besoin.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

Ces interfaces sont mises à jour avec chaque nouvelle version de l’API. Pour le format d’interface le plus mis à jour, accédez à notre dépôt GitHub.

La liste suivante décrit certaines des propriétés de l’interface VisualConstructorOptions :

  • element: HTMLElement - référence à l’élément DOM qui contient votre visuel

  • host: IVisualHost - collection de propriétés et de services qui peuvent être utilisés pour interagir avec l’hôte visuel (Power BI)

    IVisualHost contient les services suivants :

    • createSelectionIdBuilder - génère et stocke des métadonnées pour les éléments sélectionnables dans votre visuel
    • createSelectionManager - crée le pont de communication utilisé pour notifier l’hôte du visuel des modifications de l’état de sélection ; consultez API de sélection.
    • hostCapabilities
    • refreshHostData
    • downloadService - retourne les informations de résultat développées du téléchargement.
    • eventService - retourne des informations sur le rendu des événements.
    • hostEnv
    • displayWarningIcon - retourne un message d’erreur ou d’avertissement.
    • licenseManager - retourne les informations de licence.
    • createLocalizationManager - génère un gestionnaire pour faciliter la Localisation
    • applyJsonFilter - applique des types de filtre spécifiques. Voir Filtre API
    • applyCustomSort - autorise les options de tri personnalisées.
    • acquireAADTokenService - retourne les informations d’authentification de Microsoft Entra ID.
    • webAccessService - retourne l’état de l’autorisation pour accéder aux ressources distantes.
    • openModalDialog - retourne une boîte de dialogue.
    • persistProperties - permet aux utilisateurs de créer des paramètres persistants et de les enregistrer avec la définition du visuel, afin qu’ils soient disponibles lors du rechargement suivant
    • eventService - retourne un service d’événements pour prendre en charge les événements de Rendu
    • storageService - retourne un service pour utiliser le stockage local dans le visuel
    • storageV2Service - retourne un service pour utiliser la version 2 du stockage local dans le visuel
    • tooltipService - retourne un service d’info-bulles pour aider à utiliser des info-bulles dans le visuel
    • telemetry
    • drill
    • launchUrl - permet d’ouvrir une URL dans l’onglet suivant
    • authenticationService - retourne un jeton de Microsoft Entra ID.
    • locale - retourne une chaîne de paramètres régionaux, voir Localisation
    • instanceId - retourne une chaîne pour identifier l’instance de visuel en cours
    • colorPalette - retourne la colorPalette requise pour appliquer des couleurs à vos données
    • fetchMoreData - prend en charge plus de données que la limite standard (1 000 lignes). Voir Extraire plus de données
    • switchFocusModeState - permet de modifier l’état du mode focus

mise à jour

Tous les visuels doivent implémenter une méthode de mise à jour publique qui est appelée chaque fois qu’une modification est apportée à l’environnement de données ou d’hôte.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport - dimensions de la fenêtre d’affichage dans laquelle le visuel doit être rendu
  • dataViews: DataView[] - l’objet de Data View qui contient toutes les données nécessaires pour afficher votre visuel (un visuel utilise généralement la propriété catégorique sous DataView)
  • type: VisualUpdateType - indicateurs spécifiant le type des données mises à jour (Données | Redimensionner | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode - indicateurs spécifiant le mode d’affichage du visuel (Affichage | Modifier | InFocusEdit)
  • editMode: EditMode - indicateur spécifiant le mode d’édition du visuel (Par défaut | Avancé) (si le visuel prend en charge AdvancedEditMode, il ne doit restituer ses contrôles d’interface utilisateur avancés que quand editMode est défini sur Avancé ; voir AdvancedEditMode)
  • operationKind?: VisualDataChangeOperationKind - indicateur spécifiant le type de modification de données (Créer | Ajouter)
  • jsonFilters?: IFilter[] - collection de filtres JSON appliqués
  • isInFocus?: boolean - indicateur pour indiquer si le visuel est en mode focus ou non

getFormattingModel (optional)

Cette méthode est appelée une fois quand nous ouvrons le volet des propriétés ou quand l’utilisateur modifie une propriété dans le volet. Elle retourne FormattingModel avec toutes les informations sur la conception, la hiérarchie, les propriétés et les dernières valeurs de mise en forme du volet de propriétés.

getFormattingModel(): visuals.FormattingModel;

destroy (facultatif)

La fonction de destruction est appelée quand votre visuel est déchargé et peut être utilisée pour les tâches de nettoyage, comme la suppression d’écouteurs d’événements.

public destroy(): void

Conseil

Power BI n’appelle généralement pas destroy, car il est plus rapide de supprimer l’IFrame entier qui contient le visuel.

Contenu connexe