Delen via

Hulpmiddelen voor on-object - helper voor subselectie (preview)

  • Artikel

Het HTMLSubSelectionHelper biedt een eenvoudige manier voor uw aangepaste Power BI-visual om subselecties naar Power BI te verzenden, overzichten op te halen en weer te geven.

HTMLSubSelectionHelper is een helperklasse die is bedoeld om het maken en daaropvolgende beheer van subselectieoverzichten te vergemakkelijken. Het bevat methoden voor het vinden van subselectiebare elementen.

Met de hulpprogramma's worden CSS-klassen en -kenmerken geëxporteerd, zodat de visual eenvoudiger subselecties kan definiëren en onderhouden.

Notitie

Gebruik versie 6.0.1 of hoger van de hulpprogramma's.

Als u subselectiebare elementen wilt definiëren, moeten we ook een klasse toevoegen aan elk gewenst element.

CSS-klasse Doel Vereist
subselectiebaar Biedt een selector voor het HTMLSubSelectionHelper vinden van mogelijke subselecties ja

Als u subselecties voor de visual wilt definiëren, zijn er enkele kenmerken die moeten worden toegevoegd aan de gewenste elementen.

Kenmerknaam Kenmerk Doel Vereist Type Opmerking
SubSelectableDisplayNameAttribute data-sub-selection-display-name Geef een gelokaliseerde tekenreeks op voor de weergavenaam van het subselected-element ja tekenreeks data-sub-selection-display-name="Visual Title"
SubSelectableObjectNameAttribute data-sub-selection-object-name Geef een objectnaam op die moet worden gekoppeld aan snelkoppelingen en stijl voor subselectie ja tekenreeks data-sub-selection-object-name="title"
SubSelectableTypeAttribute gegevens-subselectietype Geef het type van de geselecteerde stijl op ja SubSelectionStylesType data-sub-selection-type="1"
SubSelectableDirectEdit data-sub-selection-direct-edit Directe tekstbewerkingsverwijzingen opgeven, waaronder de CardUID, GroupUID en de afdrukstand van het tekstvak nee SubSelectableDirectEdit moet worden opgegeven als een tekenreeks data-sub-selection-direct-edit="{"reference":{"cardUid":"Visual-title","groupUid":"title-text","sliceUid":"title-text-text"},"style":0}"
SubSelectableHideOutlineAttribute data-sub-selection-hide-outline Geef een Booleaanse waarde op voor subselectiebare elementen waarvoor geen overzicht mag worden weergegeven nee boolean data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute data-sub-selection-restricting-element Wordt gebruikt om het element aan te geven dat wordt beperkt, de contouren en het type beperking (klem of klem) nee SubSelectionOutlineRestrictionType data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute gegevens-subselectie-sub geselecteerd Aangeven of het subselectiebaar is geselecteerd of niet Nee, de helper wijst deze indien nodig toe aan de elementen Booleaanse waarde data-subselection-sub-selected="true"

Opmaakmodus

Wanneer de visual de indelingsmodus opent, moet u interactiviteit voor de visual uitschakelen, zoals we verwachten dat de gebruiker het visuele element en het visuele element selecteert om opmaak te initiëren.

Openbare methoden van HTMLSubSelectionHelper

De HTMLSubSelectionHelper bevat enkele openbare methoden die u kunt gebruiken, maar er zijn twee hoofdmethoden en de helper doet de rest.

De twee methoden zijn setFormatMode en updateOutlinesFromSubSelections.

De openbare methoden van de helper zijn onder andere:

  • createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper - Dit is een statische methode die args van het type HtmlSubselectionHelperArgs gebruikt en een exemplaar retourneert van HTMLSubSelectionHelper.

  • setFormatMode(isFormatMode: booleaanse waarde): void - Met deze methode wordt de indelingsmodus voor de HTMLSubSelectionHelper ingesteld, als isFormatMode waar is, koppelt de helper relevante gebeurtenislisteners aan het hostelement om de functionaliteit van de indelingsmodus in te schakelen (subselectie, overzichten weergeven).

  • getSubSelectionSourceFromEvent(gebeurtenis: PointerEvent): HtmlSubSelectionSource of niet gedefinieerd - retourneert een HtmlSubSelectionSource object dat is gebouwd op basis van de gebeurtenisparameter.

  • onVisualScroll(): void - Geeft aan de HTMLSubSelectionHelper aan dat er momenteel scrollen plaatsvindt. Schuiven moet overzichten verwijderen totdat schuiven is voltooid.

  • updateElementOutlines(elementen: HTMLElement[], zichtbaarheid: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] - werk de overzichten bij (en verzendt deze naar Power BI om te worden weergegeven) van de elementen.

  • clearHoveredOutline(): void - Met deze methode worden zwevende overzichten gewist als deze bestaan.

  • updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void - update and emits the given outlines to get rendered.

  • getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] - gegeven subSelections, deze methode retourneert de relevante HTMLElements.

  • updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: boolean): void - updates en geeft de overzichten weer voor de opgegeven subSelectie met betrekking tot suppressRender en clearExistingOutlines.

  • hideAllOutlines(suppressRender: boolean = false): void - hide all the outlines with to suppressRender.

  • getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] - retourneert alle subSelectables volgens het filterType.

  • createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection - create CustomVisualSubSelection object from the createVisualSubSelectionArgs.

  • setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void - een statische methode waarmee gegevens voor de elementen worden ingesteld.

  • getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData- een statische methode waarmee de eerder toegewezen methode wordt opgehaald met behulp van setDataForElement.

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
        }

Als u beperkingsopties wilt toevoegen aan een specifiek element, gebruikt HTMLSubSelectionHelper setDataForElement de helper de gegevens om de overzichten bij te werken:

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

Opmerking

In dit voorbeeld implementeren customOutlineCallback en selectionIdCallback: De volgende code bevindt zich in Visual Code. We hebben een object in de visual met de naam arcElement. We willen het overzicht weergeven wanneer het element wordt aanwijzer of subselected.

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

Importeer de HtmlSubSelectionHelper:

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

Maak in de constructorcode de 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),
            });
    ….
}

Voeg in de updatemethode van de visual de volgende code toe om de overzichten van de subSeselection bij te werken, de status van de indelingsmodus bij te werken voor de HTMLSubSelectionHelper en schakel interacties uit die niet voor de indelingsmodus gelden als de indelingsmodus is ingeschakeld:

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

Gerelateerde inhoud