API απεικόνισηςVisual API

Όλες οι απεικονίσεις ξεκινούν με μια κλάση που υλοποιεί τη διασύνδεση IVisual.All visuals start with a class that implements the IVisual interface. Μπορείτε να ονομάσετε την κλάση οτιδήποτε, αρκεί να υπάρχει ακριβώς μία κλάση που υλοποιεί τη διασύνδεση IVisual.You can name the class anything as long as there's exactly one class that implements the IVisual interface.

Σημείωση

Το όνομα της κλάσης της απεικόνισης πρέπει να συμφωνεί με αυτό που ορίζεται στο αρχείο pbiviz.json.The visual class name must match what's defined in the pbiviz.json file.

Ανατρέξτε στο δείγμα κλάσης απεικόνισης με τις ακόλουθες μεθόδους που θα πρέπει να υλοποιηθούν:See the sample visual class with the following methods that should be implemented:

  • constructor, μια τυπική κατασκευή για την προετοιμασία της κατάστασης της απεικόνισηςconstructor, a standard constructor to initialize the visual's state
  • update, για ενημέρωση των δεδομένων της απεικόνισηςupdate, to update the visual's data
  • enumerateObjectInstances, για επιστροφή αντικειμένων για συμπλήρωση του παραθύρου ιδιοτήτων (επιλογές μορφοποίησης), όπου μπορείτε να τα τροποποιήσετε ανάλογα με τις ανάγκεςenumerateObjectInstances, to return objects to populate the property pane (formatting options) where you can modify them as needed
  • destroy, τυπική εφαρμογή καταστροφής για εκκαθάρισηdestroy, a standard destructor for cleanup
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 enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
        //returns objects to populate the property pane (called for each object defined in capabilities)
    }
    
    public destroy(): void {
        //one time cleanup code goes here (called once)
    }
}

κατασκευήconstructor

Η κατασκευή της κλάσης απεικόνισης καλείται κατά τη δημιουργία παρουσίας της απεικόνισης.The constructor of the visual class is called when the visual is instantiated. Μπορεί να χρησιμοποιηθεί για οποιεσδήποτε λειτουργίες ρύθμισης που απαιτούνται από την απεικόνιση.It can be used for any set up operations needed by the visual.

constructor(options: VisualConstructorOptions)

VisualConstructorOptionsVisualConstructorOptions

  • element: HTMLElement, μια αναφορά στο στοιχείο DOM που θα περιέχει την απεικόνισηelement: HTMLElement, a reference to the DOM element that will contain your visual

  • host: IVisualHost, μια συλλογή ιδιοτήτων και υπηρεσιών που μπορούν να χρησιμοποιηθούν για αλληλεπίδραση με τον κεντρικό υπολογιστή απεικόνισης (Power BI)host: IVisualHost, a collection of properties and services that can be used to interact with the visual host (Power BI)

    Η IVisualHost περιλαμβάνει τις ακόλουθες υπηρεσίες:IVisualHost contains the following services:

    export interface IVisualHost extends extensibility.IVisualHost {
         createSelectionIdBuilder: () => visuals.ISelectionIdBuilder;
         : () => ISelectionManager;
         colorPalette: ISandboxExtendedColorPalette;
         persistProperties: (changes: VisualObjectInstancesToPersist) => void;
         applyJsonFilter: (filter: IFilter[] | IFilter, objectName: string, propertyName: string, action: FilterAction) => void;
         tooltipService: ITooltipService;
         telemetry: ITelemetryService;
         authenticationService: IAuthenticationService;
         locale: string;
         allowInteractions: boolean;
         launchUrl: (url: string) => void;
         fetchMoreData: () => boolean;
         instanceId: string;
         refreshHostData: () => void;
         createLocalizationManager: () => ILocalizationManager;
         storageService: ILocalVisualStorageService;
         eventService: IVisualEventService;
         switchFocusModeState: (on: boolean) => void;
    }
    
    • createSelectionIdBuilder, δημιουργεί και αποθηκεύει μετα-δεδομένα για επιλέξιμα στοιχεία στην απεικόνισηcreateSelectionIdBuilder, generates and stores metadata for selectable items in your visual
    • createSelectionManager, δημιουργεί τη γέφυρα επικοινωνίας που χρησιμοποιείται για την ειδοποίηση του κεντρικού υπολογιστή της απεικόνισης σχετικά με τις αλλαγές στην κατάσταση επιλογής, ανατρέξτε στο θέμα API επιλογής.createSelectionManager, creates the communication bridge used to notify the visual's host on changes in the selection state, see Selection API.
    • createLocalizationManager, δημιουργεί ένα πρόγραμμα διαχείρισης που θα σας βοηθήσει με την Τοπική προσαρμογήcreateLocalizationManager, generates a manager to help with Localization
    • allowInteractions: boolean, μια δυαδική σημαία που υποδεικνύει αν η απεικόνιση πρέπει να είναι αλληλεπιδραστικήallowInteractions: boolean, a boolean flag which hints whether or not the visual should be interactive
    • applyJsonFilter, εφαρμόζει συγκεκριμένους τύπους φίλτρων, ανατρέξτε στο API φίλτρουapplyJsonFilter, applies specific filter types, see Filter API
    • persistProperties, επιτρέπει στους χρήστες να διατηρούν ιδιότητες και να τις αποθηκεύουν μαζί με τον ορισμό της απεικόνισης, ώστε να είναι διαθέσιμες στην επόμενη επαναφόρτωσηpersistProperties, allows users to persist properties and save them along with the visual definition, so they're available on the next reload
    • eventService, επιστρέφει μια υπηρεσία συμβάντων για την υποστήριξη συμβάντων RendereventService, returns an event service to support Render events
    • storageService, επιστρέφει μια υπηρεσία που σας βοηθά να χρησιμοποιήσετε τοπικό χώρο αποθήκευσης στην απεικόνισηstorageService, returns a service to help use local storage in the visual
    • authenticationService, δημιουργεί μια υπηρεσία για να σας βοηθήσει με τον έλεγχο ταυτότητας χρήστηauthenticationService, generates a service to help with user authentication
    • tooltipService, επιστρέφει μια υπηρεσία συμβολών εργαλείων, για να σας βοηθήσει να χρησιμοποιήσετε συμβουλές εργαλείων στην απεικόνισηtooltipService, returns a tooltip service to help use tooltips in the visual
    • launchUrl, βοηθά στην την εκκίνηση της διεύθυνσης URL στην επόμενη καρτέλαlaunchUrl, helps to launch URL in next tab
    • locale, επιστρέφει μια συμβολοσειρά τοπικών ρυθμίσεων, ανατρέξτε στο θέμα Τοπική προσαρμογήlocale, returns a locale string, see Localization
    • instanceId, επιστρέφει μια συμβολοσειρά για τον προσδιορισμό της τρέχουσας παρουσίας απεικόνισηςinstanceId, returns a string to identify the current visual instance
    • colorPalette, επιστρέφει την colorPalette που απαιτείται για την εφαρμογή χρωμάτων στα δεδομένα σαςcolorPalette, returns the colorPalette required to apply colors to your data
    • fetchMoreData, υποστηρίζει τη χρήση περισσότερων δεδομένων από το τυπικό όριο (σειρές 1K)fetchMoreData, supports using more data than the standard limit (1K rows)
    • switchFocusModeState, βοηθά στην αλλαγή της κατάστασης λειτουργίας εστίασηςswitchFocusModeState, helps to change the focus mode state

updateupdate

Όλες οι απεικονίσεις πρέπει να υλοποιούν μια δημόσια μέθοδο ενημέρωσης που καλείται κάθε φορά που υπάρχει μια αλλαγή στο περιβάλλον δεδομένων ή κεντρικού υπολογιστή.All visuals must implement a public update method that's called whenever there's a change in the data or host environment.

public update(options: VisualUpdateOptions): void

VisualUpdateOptionsVisualUpdateOptions

  • viewport: IViewport, οι διαστάσεις της οπτικής γωνίας μέσα στις οποίες πρέπει να αποδοθεί η απεικόνισηviewport: IViewport, dimensions of the viewport that the visual should be rendered within
  • dataViews: DataView[], το αντικείμενο προβολής δεδομένων που περιέχει όλα τα δεδομένα που είναι απαραίτητα για την απόδοση της απεικόνισης (η απεικόνιση θα χρησιμοποιεί συνήθως την κατηγορική ιδιότητα στην κλάση DataView)dataViews: DataView[], the dataview object which contains all data needed to render your visual (your visual will typically use the categorical property under DataView)
  • type: VisualUpdateType, σημαίες για υπόδειξη των τύπων αυτής της ενημέρωσης (Data | Resize | ViewMode | Style | ResizeEnd)type: VisualUpdateType, flags to indicate the type(s) of this update (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode, σημαίες για υπόδειξη της λειτουργίας προβολής της απεικόνισης (View | Edit | InFocusEdit)viewMode: ViewMode, flags to indicate the view mode of the visual (View | Edit | InFocusEdit)
  • editMode: EditMode, σημαία για υπόδειξη της λειτουργίας επεξεργασίας της απεικόνισης (Default | Advanced) (εάν η απεικόνιση υποστηρίζει AdvancedEditMode, πρέπει να αποδίδει τα προηγμένα στοιχεία ελέγχου UI μόνο όταν η editMode έχει οριστεί σε Advanced, βλ. AdvancedEditMode)editMode: EditMode, flag to indicate the edit mode of the visual (Default | Advanced) (if the visual supports AdvancedEditMode, it should render its advanced UI controls only when editMode is set to Advanced, see AdvancedEditMode)
  • operationKind?: VisualDataChangeOperationKind, σημαία για υπόδειξη του τύπου αλλαγής δεδομένων που υποδεικνύει τον τύπο αλλαγής δεδομένων (Create | Append)operationKind?: VisualDataChangeOperationKind, flag to indicate type of data change (Create | Append)
  • jsonFilters?: IFilter[], συλλογή εφαρμοσμένων φίλτρων jsonjsonFilters?: IFilter[], collection of applied json filters
  • isInFocus?: boolean, σημαία για υπόδειξη αν η απεικόνιση είναι σε λειτουργία εστίασης ή όχιisInFocus?: boolean, flag to indicate if the visual is in focus mode or not

enumerateObjectInstances optionalenumerateObjectInstances optional

Αυτή η μέθοδος καλείται για κάθε αντικείμενο που αναφέρεται στις δυνατότητες.This method is called for every object listed in the capabilities. Με τη χρήση των επιλογών (προς το παρόν μόνο το όνομα) επιστρέφετε μια VisualObjectInstanceEnumeration με πληροφορίες σχετικά με τον τρόπο εμφάνισης αυτής της ιδιότητας.Using the options (currently just the name) you return a VisualObjectInstanceEnumeration with information about how to display this property.

enumerateObjectInstances(options:EnumerateVisualObjectInstancesOptions):VisualObjectInstanceEnumeration

EnumerateVisualObjectInstancesOptionsEnumerateVisualObjectInstancesOptions

  • objectName: string, όνομα του αντικειμένουobjectName: string, name of the object

destroy optionaldestroy optional

Η συνάρτηση destroy καλείται όταν καταργηθεί η φόρτωση της απεικόνισης και μπορεί να χρησιμοποιηθεί για εργασίες εκκαθάρισης, όπως η κατάργηση υπηρεσιών ακρόασης συμβάντων.The destroy function is called when your visual is unloaded and can be used for clean up tasks such as removing event listeners.

public destroy(): void

Σημείωση

Το Power BI συνήθως δεν καλεί την destroy καθώς είναι ταχύτερη η κατάργηση ολόκληρου του IFrame που περιέχει την απεικόνιση.Power BI generally doesn't call destroy since it's faster to remove the entire IFrame that contains the visual.