Jaa

Objektinkohtaiset apuohjelmat – alivalinnan aputoiminto (esikatselu)

  • Artikkeli

HTMLSubSelectionHelper tarjoaa helpon tavan power BI:n mukautetulle visualisoinnille, jonka avulla voit lähettää alivalinnat Power BI:hin sekä saada ja hahmontaa ääriviivoja.

HTMLSubSelectionHelper on apuluokka, jonka tarkoituksena on helpottaa alivalintamääritysten luomista ja myöhempää hallintaa. Se sisältää menetelmiä, joilla voidaan etsiä alivalittavia elementtejä.

Apuohjelmat vie CSS-luokat ja -määritteet, mikä helpottaa visualisoinnin alivalintaen määrittämistä ja ylläpitämistä.

Muistiinpano

Käytä apuohjelmien versiota 6.0.1 tai uudempaa versiota.

Jos haluat määrittää alivalittavia elementtejä, meidän on myös lisättävä luokka jokaiseen haluttuun elementtiin.

CSS Luokka Tarkoitus Pakollinen
alivalinta Tarjoaa valitsimen mahdollisten alivalintaa varten HTMLSubSelectionHelper Kyllä

Jos haluat määrittää visualisoinnin alivalinnat, sinun täytyy lisätä muutama määrite haluttuihin elementteihin.

Määritteen nimi Määrite Tarkoitus Pakollinen Tyyppi Esimerkki
SubSelectableDisplayNameAttribute data-sub-selection-display-name Anna lokalisoitu merkkijono alivalitun elementin näyttönimeä varten. Kyllä merkkijono data-sub-selection-display-name="Visual Title"
SubSelectableObjectNameAttribute data-sub-selection-object-name Liitä alivalinnan pikakuvakkeisiin ja tyyliin objektin nimi Kyllä merkkijono data-sub-selection-object-name="title"
SubSelectableTypeAttribute data-sub-selection-type Anna alivalitun tyylin tyyppi Kyllä SubSelectionStylesType data-sub-selection-type="1"
SubSelectableDirectEdit data-sub-selection-direct-edit Anna suoran tekstin muokkausviittauksia, kuten CardUID, GroupUID ja tekstiruudun suunta Ei SubSelectableDirectEdit tulee antaa merkkijonona data-sub-selection-direct-edit="{"reference":{"cardUid":"Visual-title","groupUid":"title-text","sliceUid":"title-text"},"style":0}"
SubSelectableHideOutlineAttribute data-sub-selection-hide-outline Anna totuusarvo alivalitseville elementeille, joissa ei tule olla ääriviivaa näkyvissä Ei boolean data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute data-sub-selection-restricting-element Käytetään ilmaisemaan rajoitettu elementti, ääriviivat ja rajoituksen tyyppi (kiinnitys tai leike) Ei SubSelectionOutlineRestrictionType data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute data-sub-selection-sub-selected Ilmaise, onko alivalinta valittuna vai ei Ei, aputoiminto määrittää sen elementeille tarvittaessa Boolean data-subselection-sub-selected="true"

Muotoilutila

Kun visualisointi siirtyy muotoilutilaan, sinun on poistettava visualisoinnin vuorovaikutteisuus käytöstä, koska odotamme käyttäjän valitsevan visualisoinnin ja visualisoinnin elementin aloittaaksesi muotoilun.

HTMLSubSelectionHelperin julkiset menetelmät

sisältää HTMLSubSelectionHelper joitakin julkisia menetelmiä, joita voit käyttää, mutta on olemassa kaksi päämenetelmää ja aputoiminto hoitaa loput.

Kaksi menetelmää ovat setFormatMode ja updateOutlinesFromSubSelections.

Aputoiminnon julkisia menetelmiä ovat seuraavat:

  • createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper – Staattinen menetelmä, joka ottaa tyypin HtmlSubselectionHelperArgs args-tiedot ja palauttaa -esiintymän HTMLSubSelectionHelper.

  • setFormatMode(isFormatMode: boolean): void – Tämä menetelmä määrittää HTMLSubSelectionHelper-kohteen muotoilutilan. Jos isFormatMode on tosi, aputoiminto liittää isäntäelementin olennaiset tapahtuman kuuntelutoiminnot muotoilutilan toiminnon käyttöönottamiseksi (alivalinta, ääriviivoiden hahmontaminen).

  • getSubSelectionSourceFromEvent(event: PointerEvent): HtmlSubSelectionSource tai undefined – palauttaa -objektin HtmlSubSelectionSource , joka on luotu tapahtumaparametrin mukaisesti.

  • onVisualScroll(): void – Ilmaisee HTMLSubSelectionHelper-sivulle, että vierittäminen on parhaillaan käynnissä. Vierittämisen pitäisi poistaa ääriviivat, kunnes vieritys on valmis.

  • updateElementOutlines(elements: HTMLElement[], näkyvyys: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] – päivitä elementtien ääriviivat (ja lähetä ne Power BI:hin hahmonnettavaksi).

  • clearHoveredOutline(): void: Tämä menetelmä tyhjentää hiiren osoittimen ääriviivat, jos ne ovat olemassa.

  • updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void - päivitä ja lähetä annetut ääriviivat hahmonnustamiseksi.

  • getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] - annettu alivalinnat, tämä menetelmä palauttaa olennaiset HTMLElements-elementit.

  • updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: boolean): void - päivittää ja hahmontaa annetun alivalinnan ääriviivat. Tämä estääRender- ja clearExistingOutline-rivit.

  • hideAllOutlines(suppressRender: boolean = false): void – piilota kaikki ääriviivat poissuljettuina.

  • getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] – palauttaa kaikki alivalinnat filterType-sarakkeen mukaan.

  • createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection – luo CustomVisualSubSelection-objekti createVisualSubSelectionArgs-kohteesta.

  • setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void – staattinen menetelmä, joka määrittää elementtien tiedot.

  • getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData – staattinen menetelmä, joka hakee liittyvän aiemmin määritetyn kohteen setDataForElement avulla.

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
        }

Jos haluat lisätä rajoitusasetuksia tiettyyn elementtiin käyttämällä HTMLSubSelectionHelper setDataForElement -tietotyyppiä, aputoiminto käyttää tietoja ääriviivoiden päivittämiseen:

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

Esimerkki

Tässä esimerkissä toteutamme customOutlineCallback ja selectionIdCallback: Seuraava koodi on Visual Codessa. Meillä on visualisoinnissa objekti nimeltä arcElement. Haluat hahmontaa ääriviivan, kun elementti on vietäessä hiiren osoitinta sen päällä tai kun se on alivalittu.

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

Tuo HtmlSubSelectionHelper:

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

Luo konstruktorikoodissa 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),
            });
    ….
}

Lisää visualisoinnin päivitysmenetelmässä seuraava koodi, joka päivittää alikyselyn ääriviivat, päivitä muotoilutilan tila toiminnoille HTMLSubSelectionHelper ja poista käytöstä vuorovaikutukset, jotka eivät ole muototilassa, jos muotoilutila on käytössä:

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

Liittyvä sisältö