Del via

Objektverktøy – hjelpeverktøy for undermerking (forhåndsvisning)

Det HTMLSubSelectionHelper gir en enkel måte for power bi-egendefinerte visualobjekter å avgi undervalg til Power BI, hente og gjengi disposisjoner.

HTMLSubSelectionHelper er en hjelpeklasse som er ment å legge til rette for oppretting og etterfølgende administrasjon av undervalgsdisposisjoner. Den inneholder metoder for å finne elementer som kan velges.

Verktøyet eksporterer CSS-klasser og attributter som gjør det enklere for visualobjektet å definere og vedlikeholde undervalg.

Merk

Bruk versjon 6.0.1 eller nyere av utilene.

Hvis du vil definere elementer som kan velges, må vi også legge til en klasse i hvert ønskede element.

CSS-klasse Formål Kreves
kan velges Gir en velger for HTMLSubSelectionHelper å finne mulige undervalg ja

Hvis du vil definere undervalg for visualobjektet, er det noen attributter som må legges til de ønskede elementene.

Attributtnavn Attributt Formål Kreves Type Eksempel
SubSelectableDisplayNameAttribute visningsnavn for data-sub-selection-display Angi en lokalisert streng for visningsnavnet for det merkede elementet ja streng data-sub-selection-display-name="Visual Title"
SubSelectableObjectNameAttribute data-sub-selection-object-name Angi et objektnavn som skal knyttes til snarveier og stiler for undervalg ja streng data-sub-selection-object-name="title"
SubSelectableTypeAttribute data-sub-selection-type Angi typen av den merkede stilen ja SubSelectionStylesType data-sub-selection-type="1"
SubSelectableDirectEdit data-sub-selection-direct-edit Gi direkte tekstredigeringsreferanser, inkludert CardUID, GroupUID og retningen på tekstboksen nei SubSelectableDirectEdit bør angis som en streng data-sub-selection-direct-edit="{"reference":{"cardUid":"Visual-title","groupUid":"title-text","sliceUid":"title-text-text"},"style":0}"
SubSelectableHideOutlineAttribute skjul disposisjon for data-sub-selection-hide-outline Angi en boolsk verdi for elementer som ikke kan velges, som ikke skal vises i en disposisjon nei boolean data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute data-sub-selection-restricting-element Brukes til å angi elementet som skal begrenses, disposisjonene og typen begrensning (klemme eller klipp) nei SubSelectionOutlineRestrictionType data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute data-sub-selection-sub-selected Angi om det kan velges undervalg eller ikke Nei, hjelperen tilordner den til elementene ved behov Boolean data-subselection-sub-selected="true"

Formatmodus

Når visualobjektet går inn i formatmodus, må du deaktivere interaktivitet for visualobjektet, da vi forventer at brukeren velger visualobjektet og visualobjektelementet for å starte formatering.

HTMLSubSelectionHelper offentlige metoder

Den HTMLSubSelectionHelper har noen offentlige metoder som du kan bruke, men det finnes to hovedmetoder og hjelperen gjør resten.

De to metodene er setFormatMode og updateOutlinesFromSubSelections.

De offentlige metodene til hjelperen inkluderer:

  • createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper – Dette er en statisk metode som tar args av typen HtmlSubselectionHelperArgs og returnerer en forekomst av HTMLSubSelectionHelper.

  • setFormatMode(isFormatMode: boolean): void - Denne metoden angir formatmodus for HTMLSubSelectionHelper, Hvis isFormatMode er sann, legger hjelperen relevante hendelseslyttere til vertselementet for å aktivere formatmodusfunksjonalitet (undervalg, gjengivelsesdisposisjoner).

  • getSubSelectionSourceFromEvent(hendelse: PointerEvent): HtmlSubSelectionSource eller udefinert – returnerer et HtmlSubSelectionSource objekt som er bygget i henhold til hendelsesparameteren.

  • onVisualScroll(): void - Angir for HTMLSubSelectionHelper at rulling for øyeblikket forekommer. Rulling bør fjerne disposisjoner til rullingen er fullført.

  • updateElementOutlines(elements: HTMLElement[], visibility: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] – oppdater disposisjonene (og sender dem til Power BI som skal gjengis) av elementene.

  • clearHoveredOutline(): void - Denne metoden fjerner pekerfølsomme disposisjoner hvis de finnes.

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

  • getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] – gitt undervalg, returnerer denne metoden de relevante HTML-elementene.

  • updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: boolean): void - updates and renders the outlines for the given subSelection with respect to suppressRender and clearExistingOutlines.

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

  • getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] – returnerer alle undervalgene i henhold til filtertypen.

  • createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection – opprett CustomVisualSubSelection-objektet fra createVisualSubSelectionArgs.

  • setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void – en statisk metode som angir data for elementene.

  • getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData – en statisk metode som får tilknyttet tidligere tilordnet ved hjelp av 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
        }

Hvis du vil legge til begrensningsalternativer i et bestemt element, bruker HTMLSubSelectionHelper setDataForElement du med denne datatypen, hjelperen bruker dataene til å oppdatere disposisjonene:

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

Eksempel

I dette eksemplet implementerer customOutlineCallback vi og selectionIdCallback: Følgende kode er i visualobjektkode. Vi har et objekt i visualobjektet kalt arcElement. Vi ønsker å gjengi disposisjonen når elementet holdes over eller er merket.

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

Importer HtmlSubSelectionHelper:

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

Opprett HTMLSubSelectionHelper i konstruktørkoden:

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

I oppdateringsmetoden for visualobjektet legger du til følgende kode for å oppdatere disposisjonene for delvalget, oppdaterer du statusen for formatmodusen for HTMLSubSelectionHelper og deaktiverer samhandlinger som ikke er for formatmodus hvis formatmodus er aktivert:

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

Relatert innhold

  • Last updated on