Alt Bölüm API'si (önizleme)

Nesne içi biçimlendirme , kullanıcıların değiştirmek istedikleri öğeleri doğrudan seçerek görsellerin biçimini hızlı ve kolay bir şekilde değiştirmesine olanak tanır. Bir öğe seçildiğinde, biçim bölmesi otomatik olarak gezinir ve seçili öğe için belirli biçimlendirme ayarını genişletir. Nesne içi biçimlendirmenin bir parçası olarak, alt bölüm hizmeti Power BI'a alt bölümler ve ana hatlar göndermek için kullanılır.

Alt Bölüm API'sini kullanma

Alt Bölüm Hizmeti iki yöntem sağlar:

Subselect

Kullanıcı alt bölümlere izin veren bir öğe seçtiğinde power BI'ın kullanması için alt bölümü gönderir.

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

Bu yöntem aşağıdaki parametrelere sahiptir:

  • customVisualObjects: öğesini içeren customVisualObjectsbir dizi, nesnenin objectName değeri capabilities.json bildirilen diziyle ve varsa seçili veri noktasının selectionId değeriyle aynı olmalıdır.
  • displayName: Görsel yerelleştirmeyi destekliyorsa görünen ad yerelleştirilmelidir.
  • subSelectionType: alt bölümün türü (şekil, metin veya Sayısal metin).
  • selectionOrigin: alt seçilen öğenin koordinatları.
  • showUI: Biçimlendirme bağlam menüleri ve araç çubuğu gibi bu alt bölüm için kullanıcı arabiriminin gösterilip gösterilmeyeceğini belirtir.
  • immediateDirectEdit: Hemen doğrudan düzenleme tetiklenmesi gerekiyorsa, düzenlenecek alt bölüm ana hattının kimliği.

kullanmazsanız HTMLSubSelectionHelper, alt dizileri yönetmeniz gerekir.

Alt bölüm örneği

Bu örnekte, sağ tıklama, bağlam menüsü olayları için konak öğesine bir olay dinleyicisi ekleyeceğiz.

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

Bu yöntem, işlenmek üzere Power BI'a ana hatlar gönderir. Power BI, görselin update daha önce gönderdiği alt bölümü burada gönderdiğinden görselin yönteminde kullanın. Vurgulanan bir öğe için ana hat oluşturmak istediğinizde de kullanabilirsiniz.

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

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

kullanmıyorsanız HTMLSubSelectionHelper, ana hatları ve durumlarını el ile yönetmeniz gerekir (etkinse, vurgulanmışsa veya görünmüyorsa).

Bölge ana hatlarını güncelleştirme örneği

Bu örnekte adlı myObjectbir nesnemiz olduğunu varsayarız ve ilgili öğe üzerine gelindiğinde dikdörtgen bir ana hat oluşturmak istiyoruz. Önceki örnekteki kodu subSelect için kullanırız.

Güncelleştirmede, olay için bir olay dinleyicisi pointerover de eklememiz gerekir.

Ana hatlarımızı bir Kayıt kullanarak yönetmek istiyoruz.

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

İlgili içerik

  • Last updated on