Freigeben über

On-object-utils - Subselection Helper (Preview)

  • Artikel

Die HTMLSubSelectionHelper bietet eine einfache Möglichkeit für Ihr benutzerdefiniertes visuelles Power BI-Element, um Unterauswahlen an Power BI zu senden, Konturen abzurufen und zu rendern.

HTMLSubSelectionHelper ist eine Hilfsklasse, welche die Erstellung und nachfolgende Verwaltung von Unterauswahlkonturen erleichtert. Sie enthält Methoden zum Suchen nach unterauswählbaren Elementen.

Die Utils exportiert CSS-Klassen und -Attribute, sodass das visuelle Element Unterauswahlen leichter definieren und verwalten werden kann.

Hinweis

Verwenden Sie Version 6.0.1 oder höher der Hilfprogramme.

Um unterauswählbare Elemente zu definieren, müssen wir jedem gewünschten Element auch eine Klasse hinzufügen.

CSS Klasse Zweck Erforderlich
unterauswählbar Stellt eine Auswahl für HTMLSubSelectionHelper bereit, um mögliche Unterauswahlen zu finden ja

Zum Definieren von Unterauswahlen für das visuelle Element gibt es ein paar Attribute, die den gewünschten Elementen hinzugefügt werden müssen.

Attributname attribute Zweck Erforderlich type Beispiel
SubSelectableDisplayNameAttribute data-sub-selection-display-name Bereitstellen einer lokalisierten Zeichenfolge für den Anzeigenamen des untergeordneten Elements ja Zeichenfolge data-sub-selection-display-name="Visual Title"
SubSelectableObjectNameAttribute data-sub-selection-object-name Geben Sie einen Objektnamen an, der Verknüpfungen und Formatvorlagen der Unterauswahl zugeordnet werden soll ja Zeichenfolge data-sub-selection-object-name="title"
SubSelectableTypeAttribute data-sub-selection-type Geben Sie den Typ der unterausgewählten Formatvorlage an ja SubSelectionStylesType data-sub-selection-type="1"
SubSelectableDirectEdit data-sub-selection-direct-edit Bereitstellen von Direkten Textbearbeitungsreferenzen, einschließlich CardUID, GroupUID und Ausrichtung des Textfelds Nein SubSelectableDirectEdit sollte als Zeichenfolge bereitgestellt werden data-sub-selection-direct-edit="{"reference":{"cardUid":"Visual-title","groupUid":"title-text","sliceUid":"title-text-text"},"style":0}"
SubSelectableHideOutlineAttribute data-sub-selection-hide-outline Bereitstellen eines booleschen Werts für unterauswählbare Elemente, die keine Kontur aufweisen sollen Nein boolean data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute data-sub-selection-restricting-element Wird verwendet, um das Element anzugeben, das eingeschränkt wird, die Konturen und die Art der Einschränkung (Klemme oder Clip) Nein SubSelectionOutlineRestrictionType data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute data-sub-selection-sub-selected Gibt an, ob die Unterauswahl ausgewählt ist oder nicht. Nein, das Hilfsprogramm weist es den Elementen bei Bedarf zu. Boolean data-subselection-sub-selected="true"

Formatmodus

Wenn das visuelle Element in den Formatmodus wechselt, müssen Sie die Interaktivität für das visuelle Element deaktivieren, da wir erwarten, dass der Benutzer das Visual und das visuelle Element zum Initiieren der Formatierung auswählt.

Öffentliche HTMLSubSelectionHelper-Methoden

Die HTMLSubSelectionHelper hat einige öffentliche Methoden, die Sie verwenden können, aber es gibt zwei Hauptmethoden, und das Hilfsprogramm erledigt den Rest.

Die beiden Methoden sind setFormatMode und updateOutlinesFromSubSelections.

Zu den öffentlichen Methoden des Hilfsprogramms gehören:

  • createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper - Dies ist eine statische Methode, die Argumente vom Typ HtmlSubselectionHelperArgs annimmt und eine Instanz von HTMLSubSelectionHelper zurückgibt.

  • setFormatMode(isFormatMode: boolean): void - Diese Methode legt den Formatmodus für die HTMLSubSelectionHelper fest, wenn isFormatMode true ist, fügt das Hilfsprogramm relevante Ereignis-Listener an das Hostelement an, um die Formatmodusfunktionalität zu aktivieren (Unterauswahl, Renderkonturen).

  • getSubSelectionSourceFromEvent(event: PointerEvent): HtmlSubSelectionSource oder undefined - gibt ein HtmlSubSelectionSource-Objekt zurück, das gemäß der Ereignisparameter aufgebaut ist.

  • onVisualScroll(): void - Zeigt dem HTMLSubSelectionHelper an, dass zurzeit ein Bildlauf ausgeführt wird. Beim Scrollen sollten Konturen entfernt werden, bis der Bildlauf abgeschlossen ist.

  • updateElementOutlines(elements: HTMLElement[], visibility: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] – Aktualisieren der Konturen (und Ausgeben an Power BI aus, um gerendert zu werden) der Elemente.

  • clearHoveredOutline(): void - Diese Methode löscht, wenn vorhanden, schwebende Konturen.

  • updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void - aktualisiert und gibt die angegebenen Konturen zum Rendern aus.

  • getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] - angegebene subSelections; diese Methode gibt die relevanten HTMLElements zurück.

  • updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: void - aktualisiert und rendert die Konturen für die angegebene subSelection hinsichtlich suppressRender und clearExistingOutlines.

  • hideAllOutlines(suppressRender: boolean = false): void - blendet alle Konturen in Bezug auf suppressRender aus.

  • getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] - gibt alle subSelectables gemäß dem filterType zurück.

  • createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection - erstellt ein CustomVisualSubSelection-Objekt aus dem createVisualSubSelectionArgs.

  • setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void - eine statische Methode, die Daten für die Elemente festlegt.

  • getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData - eine statische Methode, welche die zuvor mithilfe von setDataForElement zugewiesene zugeordnete Methode abruft.

HtmlSubselectionHelperArgs

interface HtmlSubselectionHelperArgs {
    /** Element which contains the items that can be sub-selected */
    hostElement: HTMLElement; // The host element, the helper will attach the listeners to this element
    subSelectionService: powerbi.extensibility.IVisualSubSelectionService;// subSelectionService which is provided in powerbi-visuals-api
    selectionIdCallback?: ((e: HTMLElement) => ISelectionId);// a callback that gets the selectionId for the specific element
    customOutlineCallback?: ((subSelection: CustomVisualSubSelection) => SubSelectionRegionOutlineFragment[]);// a callback to get custom outline for the specific subSelection
    customElementCallback?: ((subSelection: CustomVisualSubSelection) => HTMLElement[]);
    subSelectionMetadataCallback?: ((subSelectionElement: HTMLElement) => unknown);// a callback to attatch any meta data to the subSelection.
}

SubSelectionStylesType

const enum SubSelectionStylesType {
            None = 0,
            Text = 1,
            NumericText = 2,
            Shape = 3,
}

SubSelectableDirectEdit

interface SubSelectableDirectEdit {
            reference: SliceFormattingModelReference;
            style: SubSelectableDirectEditStyle;
            displayValue?: string;
}

SubSelectionOutlineRestrictionType

const enum SubSelectionOutlineRestrictionType {
            /**
             * A clamping element will adjust the outline to prevent it from extending beyond
             * the restricting element.
             */
            Clamp,
            /**
             * A clipping element will make parts of the outline not visible if the outline extends beyond the
             * restricting element's bounds. 
             */
            Clip
        }

Zum Hinzufügen von Einschränkungsoptionen zu einem bestimmten Element, das HTMLSubSelectionHelper setDataForElement diesen Datentyp verwendet, verwendet das Hilfsprogramm die Daten, um die Gliederungen zu aktualisieren:

interface SubSelectionElementData {
    outlineRestrictionOptions?: SubSelectionOutlineRestrictionOptions;
}

/** Options used to indicate if a restricting element should allow outlines more space to
  * generate by adding padding or if the restricting element should constrict the outline more
  * by adding a margin.
  */
export interface SubSelectionOutlineRestrictionOptions {
        padding?: IOffset;
        margin?: IOffset;
  }

Beispiel

In diesem Beispiel implementieren wir customOutlineCallback und selectionIdCallback: Der folgende Code befindet sich in Visual Code. Wir haben ein Objekt im Visual namens arcElement. Wir möchten die Kontur rendern, wenn der Mauszeiger über dem Element schwebt, oder es unterausgewählt ist.

import ISelectionId = powerbi.visuals.ISelectionId;

const enum BarChartObjectNames {
    ArcElement = 'arcElement',
    ColorSelector = 'colorSelector',
    …..
}

private ArcOutlines(subSelection: CustomVisualSubSelection): powerbi.visuals.SubSelectionRegionOutlineFragment[] {
        const outlines: powerbi.visuals.SubSelectionRegionOutlineFragment[] = []
        if (subSelection?.customVisualObjects[0].objectName === BarChartObjectNames.ArcElement) {
            const outline: powerbi.visuals.ArcSubSelectionOutline = {
                type: powerbi.visuals.SubSelectionOutlineType.Arc,
                center: { x: this.arcCenterX, y: this.arcCenterY },
                startAngle: this.arcStartAngle,
                endAngle: this.arcEndAngle,
                innerRadius: this.arcInnerRadius,
                outerRadius: this.arcOuterRadius
            };
            outlines.push({
                id: BarChartObjectNames.ArcElement,
                outline
            });
            return outlines;
        }
    }

public selectionIdCallback(e: Element): ISelectionId {
        const elementType: string = d3.select(e).attr(SubSelectableObjectNameAttribute);
        switch (elementType) {
            case BarChartObjectNames.ColorSelector:
                const datum = d3.select<Element, BarChartDataPoint>(e).datum();
                return datum.selectionId;
            default:
                return undefined;
        }
    }

HtmlSubSelectionHelper importieren:

import { HtmlSubSelectionHelper } from 'powerbi-visuals-utils-onobjectutils';

Erstellen Sie im Konstruktorcode den HTMLSubSelectionHelper:

constructor(options: VisualConstructorOptions) {
    …….
    this.subSelectionHelper = HtmlSubSelectionHelper.createHtmlSubselectionHelper({
                hostElement: options.element,
                subSelectionService: options.host.subSelectionService,
                selectionIdCallback: (e) => this.selectionIdCallback(e),
                customOutlineCallback: (e) => this.ArcOutlines(e),
            });
    ….
}

Fügen Sie in der Updatemethode des Visuals den folgenden Code hinzu, um die Konturen der SubSeselection zu aktualisieren, aktualisieren Sie den Status des Formatmodus für die HTMLSubSelectionHelper und deaktivieren Sie Interaktionen, die nicht für den Formatmodus sind, wenn der Formatmodus aktiviert ist:

public update(options: VisualUpdateOptions) {
 …
 
 if (this.formatMode) {// disabling interaction with the visual data in format mode
             barSelectionMerged.on('click', null);
             this.svg.on('click', null);
             this.svg.on('contextmenu', null);
         } else {
             this.handleBarClick(barSelectionMerged);
             this.handleClick(barSelectionMerged);
             this.handleContextMenu();
         }
         this.subSelectionHelper.setFormatMode(options.formatMode);
         const shouldUpdateSubSelection = options.type & powerbi.VisualUpdateType.Data
             || options.type & powerbi.VisualUpdateType.Resize
             || options.type & powerbi.VisualUpdateType.FormattingSubSelectionChange;
         if (this.formatMode && shouldUpdateSubSelection) {
             this.subSelectionHelper.updateOutlinesFromSubSelections(options.subSelections, true);
         }
 …
}

Zugehöriger Inhalt