Baca dalam bahasa Inggris

Bagikan melalui

API Sub-pemilihan (pratinjau)

  • Artikel

Pemformatan pada objek memungkinkan pengguna untuk dengan cepat dan mudah memodifikasi format visual dengan langsung memilih elemen yang ingin mereka ubah. Saat elemen dipilih, panel format secara otomatis menavigasi dan memperluas pengaturan pemformatan tertentu untuk elemen yang dipilih. Sebagai bagian dari pemformatan pada objek, layanan subbagian digunakan untuk mengirim subbagian dan kerangka ke Power BI.

Cara menggunakan API Sub-Pemilihan

SubSelection Service menyediakan dua metode:

subPilih

Mengirim sub-pemilihan untuk digunakan Power BI saat pengguna memilih elemen yang memungkinkan sub-pemilihan.

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

Metode ini memiliki parameter berikut:

  • customVisualObjects: array yang berisi customVisualObjects, objectName objek harus sama dengan yang dideklarasikan dalam capabilities.json, dan selectionId untuk titik data yang dipilih, jika ada.
  • displayName: nama tampilan harus dilokalkan jika visual mendukung pelokalan.
  • subSelectionType: jenis sub-pemilihan (bentuk, teks, atau teks Numerik).
  • selectionOrigin: koordinat elemen subpilih.
  • showUI: Apakah akan menampilkan UI untuk sub-pemilihan ini, seperti memformat menu konteks dan toolbar.
  • immediateDirectEdit: Jika pengeditan langsung langsung harus dipicu, ID kerangka subbagian untuk diedit.

Jika Anda tidak menggunakan HTMLSubSelectionHelper, Anda perlu mengelola sub-pemilihan.

Contoh sub-pemilihan

Dalam contoh ini, kami menambahkan pendengar peristiwa ke elemen host, untuk klik kanan, peristiwa menu konteks.

TypeScript 
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

Metode ini mengirimkan kerangka ke Power BI untuk dirender. Gunakan dalam update metode visual karena di situlah Power BI mengirim sub-pemilihan yang dikirim visual sebelumnya. Anda juga dapat menggunakannya saat ingin merender kerangka untuk elemen yang diarahkan.

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

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

Jika Anda tidak menggunakan HTMLSubSelectionHelper, Anda harus mengelola kerangka dan statusnya secara manual (jika aktif, diarahkan atau tidak terlihat).

Contoh kerangka wilayah pembaruan

Dalam contoh ini kita berasumsi bahwa kita memiliki objek yang disebut myObject, dan kita ingin merender kerangka persegi ketika elemen yang relevan diarahkan. Kami menggunakan kode dalam contoh sebelumnya untuk subPilih.

Dalam pembaruan, kita juga perlu menambahkan pendengar peristiwa untuk peristiwa tersebut pointerover .

Kami ingin mengelola kerangka kami menggunakan Rekaman.

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

Konten terkait