Partager via

API de sous-sélection (préversion)

  • Article

La mise en forme sur objet permet aux utilisateurs de modifier rapidement et facilement la mise en forme de visuels en sélectionnant directement les éléments qu’ils souhaitent modifier. Lorsque vous sélectionnez un élément, le volet de mise en forme navigue automatiquement vers le paramètre de mise en forme spécifique de cet élément et le développe. Dans le cadre de la mise en forme sur objet, le service de sous-sélection permet d’envoyer des sous-sélections et des contours à Power BI.

Comment utiliser l’API de sous-sélection

Le service de sous-sélection fournit deux méthodes :

subSelect

Envoie la sous-sélection à Power BI lorsqu’un utilisateur sélectionne un élément autorisant les sous-sélections.

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

Cette méthode a les paramètres suivants :

  • customVisualObjects : tableau qui contient customVisualObjects, l’objectName de l’objet (qui doit être identique à celui déclaré dans le fichier capabilities.json) et, le cas échéant, le selectionId du point de données sélectionné.
  • displayName : le nom d’affichage doit être localisé si le visuel prend en charge la localisation.
  • subSelectionType : type de la sous-sélection (forme, texte ou texte numérique).
  • selectionOrigin : coordonnées de l’élément sous-sélectionné.
  • showUI : s’il faut afficher l’interface utilisateur pour cette sous-sélection, comme la mise en forme des menus contextuels et de la barre d’outils.
  • immediateDirectEdit : ID du contour de sous-sélection à modifier si la modification directe immédiate doit être déclenchée.

Si vous n’utilisez pas HTMLSubSelectionHelper, vous devez gérer les sous-sélections.

Exemple de sous-sélection

Dans cet exemple, nous ajoutons un écouteur d’événements à l’élément hôte pour les événements de menu contextuel avec le bouton droit.

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

Cette méthode envoie des contours à Power BI à afficher. Utilisez-la dans la méthode update du visuel puisque c’est là que Power BI envoie la sous-sélection que le visuel a envoyée précédemment. Vous pouvez également l’utiliser lorsque vous souhaitez afficher le contour d’un élément sélectionné par pointage.

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

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

Si vous n’utilisez pas HTMLSubSelectionHelper, vous devez gérer manuellement les contours et leur état (s’ils sont actifs, sélectionnés par pointage ou non visibles).

Exemple de mise à jour de contours de région

Dans cet exemple, nous partons du principe que nous avons un objet appelé myObject et que nous voulons afficher un contour rectangulaire lorsque l’élément approprié est sélectionné par pointage. Nous utilisons le code dans l’exemple précédent pour subSelect.

Dans la mise à jour, nous devons également ajouter un écouteur d’événement pour l’événement pointerover.

Nous voulons gérer nos contours à l’aide d’un enregistrement.

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

Contenu connexe