Jaa

Alivalinta-ohjelmointirajapinta (esikatselu)

  • Artikkeli

Objektien muotoilun avulla käyttäjät voivat nopeasti ja helposti muokata visualisointien muotoa valitsemalla suoraan elementit, joita he haluavat muokata. Kun elementti on valittu, muotoiluruudussa siirrytään automaattisesti ja laajennetaan valitun elementin muotoiluasetusta. Alivalintapalvelun avulla lähetetään alivalinta ja ääriviivat Power BI:hin osana objektin automaattista muotoilua.

Alivalinta-ohjelmointirajapinnan käyttäminen

Alivalintapalvelu tarjoaa kaksi menetelmää:

aliValinta

Lähettää Alivalinnan Power BI:lle käytettäväksi, kun käyttäjä valitsee alivalinnat sallivan elementin.

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

Tällä menetelmällä on seuraavat parametrit:

  • customVisualObjects: matriisin, joka sisältää customVisualObjectskohteen , objectName-objektin on oltava sama kuin capabilities.json määritetty matriisi ja valitun arvopisteen selectionId, jos se on olemassa.
  • displayName: Näyttönimi on lokalisoitava, jos visualisointi tukee lokalisointia.
  • subSelectionType: alivalinnan tyyppi (muoto, teksti tai numeerinen teksti).
  • selectionOrigin: alivalitun elementin koordinaatit.
  • showUI: Näyttääkö käyttöliittymän tälle alivalinnalle, kuten pikavalikot ja työkalurivin muotoilun.
  • immediateDirectEdit: Jos välitön suora muokkaus tulisi käynnistää, alivalinta-jäsennyksen tunnus, jota muokataan.

Jos et käytä -parametria HTMLSubSelectionHelper, sinun on hallittava alivalintoja.

Alivalintaesimerkki

Tässä esimerkissä lisäämme tapahtuman kuuntelutoiminnon isäntäelementtiin hiiren kakkospainikkeella valikon tapahtumia varten.

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

Tämä menetelmä lähettää ääriviivat Power BI:hin hahmonnettavaksi. Käytä sitä visualisoinnin -menetelmässä update , koska tässä Power BI lähettää visualisoinnin aiemmin lähettämän alivalinnan. Voit käyttää sitä myös silloin, kun haluat hahmontaa ääriviivan osoittimen viedylle elementille.

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

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

Jos et käytä - HTMLSubSelectionHelpertiliä, sinun on hallittava manuaalisesti ääriviivoja ja niiden tilaa (jos ne ovat aktiivisia, vie hiiren osoitin tai ei näkyvissä).

Päivitä alueen jäsennykset -esimerkki

Tässä esimerkissä oletamme, että meillä on objekti nimeltä myObject, ja haluamme hahmontaa suorakulmion ääriviivan, kun asianomainen elementti viedään osoittimen kojeeseen. Käytämme edellisessä esimerkissä alivalinnan koodia.

Päivityksessä on myös lisättävä tapahtuman kuuntelutoiminto pointerover .

Haluamme hallita jäsennyksiämme tietueen avulla.

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

Liittyvä sisältö