Del via

Api til undervalg (prøveversion)

Formatering i objektet gør det muligt for brugerne hurtigt og nemt at ændre formatet af visualiseringer ved direkte at vælge de elementer, de vil ændre. Når et element vælges, navigerer og udvider formatruden automatisk den specifikke formateringsindstilling for det valgte element. Som en del af formateringen i objektet bruges undersektionstjenesten til at sende undermarkeringer og dispositioner til Power BI.

Sådan bruger du API'en til undervalg

Undervalgstjenesten indeholder to metoder:

Marker

Sender underafsnittet til Power BI, der skal bruges, når en bruger vælger et element, der tillader undermarkeringer.

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;
        }

Denne metode har følgende parametre:

  • customVisualObjects: en matrix, der indeholder customVisualObjects, objektets objectName skal være den samme som den, der er erklæret i capabilities.json, og selectionId for det valgte datapunkt, hvis det findes.
  • displayName: Det viste navn skal lokaliseres, hvis visualiseringen understøtter lokalisering.
  • subSelectionType: underafsnittets type (figur, tekst eller numerisk tekst).
  • selectionOrigin: koordinaterne for det undermarkerede element.
  • showUI: Om brugergrænsefladen for denne undersektion skal vises, f.eks. formatering af genvejsmenuer og værktøjslinjer.
  • immediateDirectEdit: Hvis øjeblikkelig direkte redigering skal udløses, skal id'et for den undersektionsdisposition, der skal redigeres.

Hvis du ikke bruger HTMLSubSelectionHelper, skal du administrere undermarkeringer.

Eksempel på undervalg

I dette eksempel føjer vi en hændelseslyttefunktion til værtselementet for genvejsmenuhændelser.

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

Denne metode sender dispositioner til Power BI for at gengive. Brug den i metoden for update visualiseringen, da det er her, Power BI sender den undersektion, som visualiseringen sendte tidligere. Du kan også bruge den, når du vil gengive en disposition for et pegefølsomt element.

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

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

Hvis du ikke bruger HTMLSubSelectionHelper, skal du manuelt administrere dispositionerne og deres tilstand (hvis de er aktive, pegede eller ikke synlige).

Eksempel på opdatering af områdedispositioner

I dette eksempel antager vi, at vi har et objekt kaldet myObject, og vi vil gengive en rektangelkontur, når der holdes over det relevante element. Vi bruger koden i det forrige eksempel til subSelect.

I opdateringen skal vi også tilføje en lyttefunktion til pointerover begivenheden.

Vi vil gerne administrere dispositionerne ved hjælp af en post.

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);
     }

Relateret indhold

  • Last updated on