Freigeben über

Unterauswahl-API (Vorschau)

  • Artikel

Die Objektformatierung ermöglicht es Benutzern, das Format von Visuals schnell und einfach zu ändern, indem sie die Elemente direkt auswählen, die sie ändern möchten. Wenn ein Element ausgewählt ist, führt der Formatbereich die Navigation automatisch aus und erweitert die spezifische Formatierungseinstellung für das ausgewählte Element. Bei der Objektformatierung wird der Unterauswahldienst verwendet, um Unterauswahlen und Konturen an Power BI zu senden.

Verwenden der Unterauswahl-API

Der SubSelection-Dienst stellt zwei Methoden bereit:

subSelect

Sendet die Unterauswahl, die von Power BI verwendet werden soll, wenn ein Benutzer ein Element auswählt, das Unterauswahlen zulässt

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

Diese Methode hat die folgenden Parameter:

  • customVisualObjects: Ein Array, das customVisualObjects enthält, wobei der objectName-Parameter des Objekts mit dem in der Datei capabilities.json und dem selectionId-Parameter für den ausgewählten Datenpunkt übereinstimmen sollte, sofern dieser vorhanden ist
  • displayName: Der Anzeigename sollte lokalisiert werden, wenn das Visual die Lokalisierung unterstützt.
  • subSelectionType: Der Unterauswahltyp (Form, Text oder numerischer Text)
  • selectionOrigin: Die Koordinaten des Elements, das über die Unterauswahl ausgewählt wurde
  • showUI: Gibt an, ob die Benutzeroberfläche für diese Unterauswahl angezeigt werden soll, z. B. Kontextmenüs und die Symbolleiste für die Formatierung
  • immediateDirectEdit: Wenn die sofortige direkte Bearbeitung ausgelöst werden soll, muss die ID der zu bearbeitenden Unterauswahlkontur angegeben werden.

Wenn Sie die HTMLSubSelectionHelper-Klasse nicht verwenden, müssen Sie die Unterauswahlen verwalten.

Beispiel für die Unterauswahl

In diesem Beispiel wird dem Hostelement ein Ereignislistener für Rechtsklick- bzw. Kontextmenüereignisse hinzugefügt.

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

Diese Methode sendet die Konturen an Power BI, die gerendert werden sollen. Verwenden Sie sie in der update-Methode des Visuals, da Power BI die zuvor durch das Visual gesendete Unterauswahl dorthin sendet. Sie können sie ebenfalls verwenden, wenn Sie eine Kontur für Elemente rendern möchten, auf die mit der Maus gezeigt wird.

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

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

Wenn Sie die HTMLSubSelectionHelper-Klasse nicht verwenden, müssen Sie die Konturen und ihren Status manuell verwalten (wenn diese aktiv oder nicht sichtbar sind oder mit der Maus auf sie gezeigt wird).

Beispiel für updateRegionOutlines

In diesem Beispiel wird davon ausgegangen, dass ein Objekt namens myObject vorhanden ist. Zudem soll eine Rechteckkontur gerendert werden, wenn mit der Maus auf das relevante Element gezeigt wird. Der Code aus dem vorherigen Beispiel wird für die subSelect-Methode verwendet.

Im Update muss außerdem ein Ereignislistener für das pointerover-Ereignis hinzufügen werden.

Die Kontur soll mithilfe eines Datensatzes verwaltet werden.

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

Zugehöriger Inhalt