Sdílet prostřednictvím

Rozhraní API pro dílčí výběr (Preview)

  • Článek

Formátování objektu umožňuje uživatelům rychle a snadno upravit formát vizuálů tak, že přímo vybere prvky, které chtějí upravit. Když je vybraný prvek, podokno formátu automaticky přejde a rozbalí konkrétní nastavení formátování pro vybraný prvek. V rámci formátování objektů se služba dílčího výběru používá k odesílání dílčích výběrů a osnov do Power BI.

Jak používat rozhraní API pro dílčí výběr

Služba SubSelection poskytuje dvě metody:

Vyberte

Odešle dílčí výběr pro Power BI, který se použije, když uživatel vybere prvek, který umožňuje dílčí výběry.

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

Tato metoda má následující parametry:

  • customVisualObjects: pole, které obsahuje customVisualObjects, objektName objektu by měl být stejný jako objekt deklarovaný v capabilities.json a selectionId pro vybraný datový bod, pokud existuje.
  • displayName: Zobrazovaný název by měl být lokalizován, pokud vizuál podporuje lokalizaci.
  • subSelectionType: typ dílčího výběru (obrazec, text nebo číselný text).
  • selectionOrigin: souřadnice dílčího prvku.
  • showUI: Určuje, jestli se má uživatelské rozhraní pro tento dílčí výběr zobrazit, například kontextové nabídky formátování a panel nástrojů.
  • immediateDirectEdit: Pokud by se měla aktivovat okamžitá přímá úprava, ID dílčího výběru osnovy, která se má upravit.

Pokud tuto možnost nepoužíváte HTMLSubSelectionHelper, musíte spravovat dílčí výběry.

Příklad dílčího výběru

V tomto příkladu přidáme do elementu hostitele naslouchací proces události pro události místní nabídky po kliknutí pravým tlačítkem myši.

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

Tato metoda odesílá osnovy do Power BI k vykreslení. Použijte ho v update metodě vizuálu, protože power BI odesílá dílčí výběr, který vizuál odeslal dříve. Můžete ho také použít, když chcete vykreslit osnovu pro najetý prvek.

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

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

Pokud tyto osnovy a jejich stav nepoužíváte HTMLSubSelectionHelper, musíte je spravovat ručně (pokud jsou aktivní, najeté myší nebo nejsou viditelné).

Příklad osnov aktualizace oblastí

V tomto příkladu předpokládáme, že máme volána myObjectobjekt a chceme vykreslit obrys obdélníku, když je příslušný prvek najet myší. Pro dílčí výběr použijeme kód v předchozím příkladu.

V aktualizaci musíme také přidat naslouchací proces událostí události pointerover .

Osnovy chceme spravovat pomocí záznamu.

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

Související obsah