Narzędzia obiektu lokalnego — pomocnik podwybierz (wersja zapoznawcza)

Zapewnia HTMLSubSelectionHelper łatwy sposób na wizualizację niestandardową usługi Power BI w celu emitowania wyborów podrzędnych do usługi Power BI, pobierania i renderowania konspektów.

HTMLSubSelectionHelper jest klasą pomocnika przeznaczoną do ułatwienia tworzenia i późniejszego zarządzania konspektami podwybierz. Zawiera metody znajdowania elementów do wyboru podrzędnego.

Narzędzia eksportują klasy CSS i atrybuty, co ułatwia wizualizacji definiowanie i konserwację wyborów podrzędnych.

Aby zdefiniować elementy do wyboru podrzędnego, musimy również dodać klasę do każdego żądanego elementu.

Aby zdefiniować wybory podrzędne dla wizualizacji, istnieje kilka atrybutów, które należy dodać do żądanych elementów.

Tryb formatowania

Gdy wizualizacja przechodzi w tryb formatowania, musisz wyłączyć interakcyjność dla wizualizacji, ponieważ oczekujemy, że użytkownik wybierze wizualizację i element wizualizacji w celu zainicjowania formatowania.

Metody publiczne HTMLSubSelectionHelper

Zawiera HTMLSubSelectionHelper kilka metod publicznych, których można użyć, ale istnieją dwie główne metody, a pomocnik wykonuje resztę.

Dwie metody to setFormatMode i updateOutlinesFromSubSelections.

Publiczne metody pomocnika obejmują:

• createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper — jest to statyczna metoda, która przyjmuje args typu HtmlSubselectionHelperArgs i zwraca wystąpienie klasy HTMLSubSelectionHelper.

• setFormatMode(isFormatMode: wartość logiczna): void — ta metoda ustawia tryb formatowania htmlSubSelectionHelper, Jeśli isFormatMode ma wartość true, pomocnik dołącza odpowiednie odbiorniki zdarzeń do elementu hosta w celu włączenia funkcji trybu formatowania (podwybór, renderowanie konspektów).

• getSubSelectionSourceFromEvent(zdarzenie: PointerEvent): HtmlSubSelectionSource lub undefined — zwraca HtmlSubSelectionSource obiekt zbudowany zgodnie z parametrem zdarzenia.

• onVisualScroll(): void — wskazuje na element HTMLSubSelectionHelper, który trwa przewijanie. Przewijanie powinno usuwać kontury do momentu zakończenia przewijania.

• updateElementOutlines(elementy: HTMLElement[], widoczność: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] — zaktualizuj konspekty (i emituje je do usługi Power BI do renderowania) elementów.

• clearHoveredOutline(): void — ta metoda czyści zatrzymane kontury, jeśli istnieją.

• updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void — aktualizacja i emituje podane konspekty w celu renderowania.

• getElementsFromSubSelections(wybory podsieci: CustomVisualSubSelection[]): HTMLElement[] — biorąc podsieci, ta metoda zwraca odpowiednie elementy HTMLElements.

• updateOutlinesFromSubSelections(wybory podrzędne: CustomVisualSubSelection[], clearExistingOutlines?: wartość logiczna, suppressRender?: wartość logiczna): void — aktualizuje i renderuje konspekty dla danego podwybornika w odniesieniu do elementu suppressRender i clearExistingOutlines.

• hideAllOutlines(suppressRender: boolean = false): void — ukrywa wszystkie kontury w odniesieniu do elementu suppressRender.

• getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] — zwraca wszystkie podwybierzables zgodnie z filterType.

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

• setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void — metoda statyczna, która ustawia dane dla elementów.

• getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData — metoda statyczna, która pobiera skojarzona wcześniej z elementem 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
        }

Aby dodać opcje ograniczeń do określonego elementu z HTMLSubSelectionHelper setDataForElement tym typem danych, pomocnik używa danych do aktualizowania konspektów:

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

Przykład

W tym przykładzie zaimplementujemy customOutlineCallback i selectionIdCallback: Następujący kod znajduje się w programie Visual Code. Mamy obiekt w wizualizacji o nazwie arcElement. Chcemy renderować konspekt po umieszczeniu wskaźnika myszy lub wybraniu podsektu.

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

Zaimportuj element HtmlSubSelectionHelper:

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

W kodzie konstruktora utwórz element 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),
            });
    ….
}

W metodzie aktualizacji wizualizacji dodaj następujący kod, aby zaktualizować konspektu podwybierz, zaktualizuj stan trybu formatu dla HTMLSubSelectionHelper i wyłącz interakcje, które nie są dla trybu formatowania, jeśli jest włączony tryb formatowania:

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

Powiązana zawartość

• Interfejs API podwybierz
• Interfejs API formatowania obiektów