Delen via

Subselectie-API (preview)

  • Artikel

Met objectopmaak kunnen gebruikers de opmaak van visuals snel en eenvoudig wijzigen door rechtstreeks de elementen te selecteren die ze willen wijzigen. Wanneer een element is geselecteerd, navigeert het opmaakvenster automatisch en wordt de specifieke opmaakinstelling voor het geselecteerde element uitgebreid. Als onderdeel van objectopmaak wordt de subselectieservice gebruikt om subselecties en overzichten naar Power BI te verzenden.

De Subselectie-API gebruiken

De SubSelection-service biedt twee methoden:

subSelect

Hiermee wordt de subselectie voor Power BI verzonden die moet worden gebruikt wanneer een gebruiker een element selecteert dat subselecties toestaat.

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

Deze methode heeft de volgende parameters:

  • customVisualObjects: een matrix die de objectnaam van het object bevat customVisualObjects, moet hetzelfde zijn als de matrix die is gedeclareerd in de capabilities.json en de selectionId voor het geselecteerde gegevenspunt, indien aanwezig.
  • displayName: de weergavenaam moet worden gelokaliseerd als de visual lokalisatie ondersteunt.
  • subSelectionType: het type subselectie (vorm, tekst of numerieke tekst).
  • selectionOrigin: de coördinaten van het subselected-element.
  • showUI: Of de gebruikersinterface voor deze subselectie moet worden weergegeven, zoals contextmenu's en werkbalk opmaken.
  • immediateDirectEdit: Als direct bewerken moet worden geactiveerd, moet de id van het overzicht van de subselectie worden bewerkt.

Als u de HTMLSubSelectionHelperoptie niet gebruikt, moet u de subselecties beheren.

Voorbeeld van subselectie

In dit voorbeeld voegen we een gebeurtenislistener toe aan het hostelement, voor contextmenugebeurtenissen met de rechtermuisknop.

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

Met deze methode worden overzichten naar Power BI verzonden om weer te geven. Gebruik deze in de update methode van de visual, omdat power BI de subselectie verzendt die eerder door de visual is verzonden. U kunt deze ook gebruiken als u een overzicht wilt weergeven voor een aanwijselement.

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

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

Als u de HTMLSubSelectionHelperlijst niet gebruikt, moet u de overzichten en de status ervan handmatig beheren (als ze actief zijn, zwevend of niet zichtbaar zijn).

Voorbeeld van overzichten van regio's bijwerken

In dit voorbeeld gaan we ervan uit dat we een object hebben met de naam myObjecten dat we een rechthoekoverzicht willen weergeven wanneer het relevante element wordt aangeroepen. We gebruiken de code in het vorige voorbeeld voor subSelect.

In de update moeten we ook een gebeurtenislistener voor de pointerover gebeurtenis toevoegen.

We willen onze overzichten beheren met behulp van een record.

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

Gerelateerde inhoud