Κοινή χρήση μέσω

API δευτερεύουσας επιλογής (προεπισκόπηση)

  • Άρθρο

Η μορφοποίηση στο αντικείμενο επιτρέπει στους χρήστες να τροποποιούν γρήγορα και εύκολα τη μορφή των απεικονίσεων επιλέγοντας απευθείας τα στοιχεία που θέλουν να τροποποιήσουν. Όταν επιλέγεται ένα στοιχείο, το τμήμα παραθύρου μορφοποίησης μεταβαίνει αυτόματα και αναπτύσσει τη συγκεκριμένη ρύθμιση μορφοποίησης για το επιλεγμένο στοιχείο. Ως μέρος της μορφοποίησης εντός αντικειμένου, η υπηρεσία δευτερεύουσας ενότητας χρησιμοποιείται για την αποστολή υποεπιλογών και περιγραμμάτων στο Power BI.

Τρόπος χρήσης του API δευτερεύουσας επιλογής

Η υπηρεσία SubSelection παρέχει δύο μεθόδους:

Επιλέξτε

Αποστέλλει την υποεπιλογή για το Power BI για χρήση όταν ένας χρήστης επιλέγει ένα στοιχείο που επιτρέπει δευτερεύουσες επιλογές.

subSelect(args: visuals.CustomVisualSubSelection | undefined): void

CustomVisualSubSelection
interface CustomVisualSubSelection {
            customVisualObjects: CustomVisualObject[];
            displayName: string;
            subSelectionType: SubSelectionStylesType;
            selectionOrigin: SubSelectionOrigin;
            /** Whether to show the UI for this sub-selection, like formatting context menus and toolbar */
            showUI: boolean;
            /** If immediate direct edit should be triggered, the ID of the sub-selection outline to edit */
            immediateDirectEdit?: string;
            metadata?: unknown;
        }


interface CustomVisualObject {
            objectName: string;
            selectionId: powerbi.visuals.ISelectionId | undefined;
        }

Αυτή η μέθοδος έχει τις ακόλουθες παραμέτρους:

  • customVisualObjects: ένας πίνακας που περιέχει customVisualObjects, το objectName του αντικειμένου θα πρέπει να είναι ίδιο με εκείνο που δηλώνεται στην capabilities.json και το selectionId για το επιλεγμένο σημείο δεδομένων, εάν υπάρχει.
  • displayName: το εμφανιζόμενο όνομα θα πρέπει να μεταφραστεί εάν η απεικόνιση υποστηρίζει τοπική προσαρμογή.
  • subSelectionType: ο τύπος της δευτερεύουσας επιλογής (σχήμα, κείμενο ή αριθμητικό κείμενο).
  • selectionOrigin: οι συντεταγμένες του στοιχείου της δευτερεύουσας επιλογής.
  • showUI: Ορίζει εάν θα εμφανίζεται το περιβάλλον εργασίας χρήστη για αυτήν την δευτερεύουσα επιλογή, όπως τα μενού περιβάλλοντος μορφοποίησης και η γραμμή εργαλείων.
  • immediateDirectEdit: Εάν πρέπει να ενεργοποιηθεί η άμεση άμεση επεξεργασία, το αναγνωριστικό της διάρθρωσης δευτερεύουσας ενότητας προς επεξεργασία.

Εάν δεν χρησιμοποιείτε το HTMLSubSelectionHelper, πρέπει να διαχειριστείτε τις υποεπιλογές.

Παράδειγμα δευτερεύουσας ενότητας

Σε αυτό το παράδειγμα, προσθέτουμε μια υπηρεσία ακρόασης συμβάντων στο κεντρικό στοιχείο, για τα συμβάντα μενού περιβάλλοντος με δεξί κλικ.

constructor(options: VisualConstructorOptions) {
        this.hostElement = options.element;
        this.subSelectionService = options.host.subSelectionService;
        ….
}

public update(options: VisualUpdateOptions) {
 if (options.formatMode) {
             // remove event listeners which are irrelevant for format mode.
   …
             this.hostElement.addEventListener('click', this.handleFormatModeClick);
             this.hostElement.addEventListener('contextmenu',  this.handleFormatModeContextMenu);
         } else {
             this.hostElement.removeEventListener('click', this.handleFormatModeClick);
             this.hostElement.removeEventListener('contextmenu', this.handleFormatModeContextMenu);
   …
             // add event listeners which are irrelevant for format mode
         }
 }
 
private handleFormatModeClick(event: MouseEvent): void {
        this.subSelectFromEvent(event, true /**showUI */);
    }

 private handleFormatModeContextMenu(event: MouseEvent): void {
        this.subSelectFromEvent(event, false);
    }

private subSelectFromEvent(event: MouseEvent, showUI: boolean): void {
        //find the element which was selected and fill the needed fields
        const cVObject: powerbi.visuals.CustomVisualObject = {
            objectName: 'myObject',//the object name that is relevant to the clicked element
            selectionId: undefined
        };
        const subSelection: CustomVisualSubSelection = {
            customVisualObjects: [cVObject],
            displayName: 'myObject',
            selectionOrigin: {
                x: event.clientX,
                y: event.clientY
            },
            subSelectionType: SubSelectionStylesType.Shape,// choose the relevant type
            showUI
        };
        this.subSelectionService.subSelect(subSelection);
    }

updateRegionOutlines

Αυτή η μέθοδος στέλνει περιγράμματα στο Power BI για απόδοση. Χρησιμοποιήστε το update στη μέθοδο της απεικόνισης, δεδομένου ότι σε αυτό το σημείο το Power BI στέλνει την υποεπιλογή που είχε στείλει προηγουμένως η απεικόνιση. Μπορείτε επίσης να το χρησιμοποιήσετε όταν θέλετε να αποδώσετε ένα περίγραμμα για ένα στοιχείο με κατάδειξη.

updateRegionOutlines(outlines: visuals.SubSelectionRegionOutline[]): void

SubSelectionRegionOutline
interface SubSelectionRegionOutline {
            id: string;
            visibility: SubSelectionOutlineVisibility; // controls visibility for outlines
            outline: SubSelectionOutline;
        }

Εάν δεν χρησιμοποιείτε το HTMLSubSelectionHelper, πρέπει να διαχειριστείτε με μη αυτόματο τρόπο τις περιγράμματα και την κατάστασή τους (εάν είναι ενεργές, με κατάδειξη ή μη ορατές).

Παράδειγμα περιγράμματος ενημέρωσης περιοχής

Σε αυτό το παράδειγμα υποθέτουμε ότι έχουμε ένα αντικείμενο που ονομάζεται myObjectκαι θέλουμε να αποδώσετε ένα ορθογώνιο περίγραμμα όταν γίνεται κατάδειξη του σχετικού στοιχείου. Χρησιμοποιούμε τον κώδικα στο προηγούμενο παράδειγμα για τη δευτερεύουσα επιλογή.

Στην ενημέρωση, πρέπει επίσης να προσθέσουμε μια υπηρεσία ακρόασης συμβάντων για το pointerover συμβάν.

Θέλουμε να διαχειριστούμε τις περιγράμματά μας χρησιμοποιώντας μια Εγγραφή.

private subSelectionRegionOutlines: Record<string, SubSelectionRegionOutline > = {};


public update(options: VisualUpdateOptions) {
 if (options.formatMode) {
             // remove event listeners which are irrelevant for format mode.
   …
             this.hostElement.addEventListener('click', this.handleFormatModeClick);
             this.hostElement.addEventListener('contextmenu',  this.handleFormatModeContextMenu);
   this.hostElement.addEventListener('pointerover', this.handleFormatModePointerOver);
         } else {
             this.hostElement.removeEventListener('click', this.handleFormatModeClick);
             this.hostElement.removeEventListener('contextmenu', this.handleFormatModeContextMenu);
   this.hostElement.removeEventListener('pointerover', this.handleFormatModePointerOver);
   …
             // add event listeners which are irrelevant for format mode
         }
 }
 
 private handleFormatModePointerOver(event: MouseEvent): void {
         // use the event to extract the element that was hovered.
         // in this example we assume that we found the element and it is related to object called myObject.
         // we need to clear previously hovered outlines before rendering
         const regionOutlines = getValues(this.subSelectionRegionOutlines);
         const hoveredOutline = regionOutlines.find(outline => outline.visibility === SubSelectionOutlineVisibility.Hover);
         if (hoveredOutline) {
             this.subSelectionRegionOutlines[hoveredOutline.id] = {
                 ...this.subSelectionRegionOutlines[hoveredOutline.id],
                 visibility: powerbi.visuals.SubSelectionOutlineVisibility.None
             };
         }
         // now we will build the outline for myObject relevant element.
         let element: HTMLElement;// assume we found the relevant element.
         const domRect = element.getBoundingClientRect();
         const { x, y, width, height } = domRect;
         const outline: powerbi.visuals.RectangleSubSelectionOutline = {
             height,
             width,
             x,
             y,
             type: powerbi.visuals.SubSelectionOutlineType.Rectangle,
         };
     
         const regionOutline: powerbi.visuals.SubSelectionRegionOutline = {
             id: 'myObject',
             visibility: powerbi.visuals.SubSelectionOutlineVisibility.Hover,
             outline
         };
         this.subSelectionRegionOutlines[regionOutline.id] = regionOutline;
         this.renderOutlines();
         // you need to remove the hovered outline when the element is not hovered anymore
     }
     private renderOutlines(): void {
         const regionOutlines = getValues(this.subSelectionRegionOutlines);
         this.subSelectionService.updateRegionOutlines(regionOutlines);
     }

Σχετικό περιεχόμενο