Dela via

API för undermarkering (förhandsversion)

Formatering på objekt gör det möjligt för användare att snabbt och enkelt ändra formatet för visuella objekt genom att välja de element som de vill ändra direkt. När ett element har valts navigerar formatfönstret automatiskt och expanderar den specifika formateringsinställningen för det markerade elementet. Som en del av formateringen på objektet används undermarkeringstjänsten för att skicka undermarkeringar och dispositioner till Power BI.

Så här använder du API:et för undermarkering

SubSelection-tjänsten innehåller två metoder:

Delmarkera

Skickar undermarkeringen för Power BI som ska användas när en användare väljer ett element som tillåter undermarkeringar.

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

Den här metoden har följande parametrar:

  • customVisualObjects: en matris som innehåller customVisualObjects, objektets objectName ska vara samma som det som deklareras i capabilities.json och selectionId för den valda datapunkten, om den finns.
  • displayName: Visningsnamnet ska lokaliseras om det visuella objektet stöder lokalisering.
  • subSelectionType: typen av undermarkering (form, text eller numerisk text).
  • selectionOrigin: koordinaterna för det undermarkerade elementet.
  • showUI: Om användargränssnittet ska visas för den här undermarkeringen, till exempel formatering av snabbmenyer och verktygsfält.
  • immediateDirectEdit: Om omedelbar direktredigering ska utlösas ska ID:t för undermarkeringsdispositionen som ska redigeras.

Om du inte använder HTMLSubSelectionHelpermåste du hantera undermarkeringarna.

Exempel på undermarkering

I det här exemplet lägger vi till en händelselyssnare i värdelementet för snabbmenyhändelserna med högerklicka.

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

Den här metoden skickar dispositioner till Power BI för återgivning. Använd den i update metoden för det visuella objektet eftersom det är där Power BI skickar undermarkeringen som det visuella objektet skickade tidigare. Du kan också använda den när du vill återge en disposition för ett hovrade element.

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

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

Om du inte använder HTMLSubSelectionHelpermåste du manuellt hantera konturerna och deras tillstånd (om de är aktiva, hovrade eller inte synliga).

Exempel på uppdateringsregiondispositioner

I det här exemplet förutsätter vi att vi har ett objekt med namnet myObject, och vi vill återge en rektangeldisposition när det relevanta elementet hovras. Vi använder koden i föregående exempel för subSelect.

I uppdateringen måste vi också lägga till en händelselyssnare pointerover för händelsen.

Vi vill hantera våra dispositioner med hjälp av 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);
     }

Relaterat innehåll