Sdílet prostřednictvím

Nástroje pro objekty – pomocné rutiny dílčího výběru (Preview)

  • Článek

Poskytuje HTMLSubSelectionHelper snadný způsob, jak vlastní vizuál Power BI generovat dílčí výběry do Power BI, získat a vykreslit osnovy.

HTMLSubSelectionHelper je pomocná třída určená k usnadnění vytváření a následné správy osnov dílčího výběru. Obsahuje metody pro vyhledání dílčích prvků, které lze vybrat.

Nástroje exportují třídy a atributy CSS, což vizuálu usnadňuje definování a údržbu dílčích výběrů.

Poznámka:

Použijte verzi 6.0.1 nebo vyšší nástroje.

K definování dílčích prvků, které lze vybrat, musíme také přidat třídu do každého požadovaného prvku.

Třída CSS Účel Požaduje se
subselectable Poskytuje selektor pro HTMLSubSelectionHelper vyhledání možných dílčích výběrů. ano

Pokud chcete definovat dílčí výběry vizuálu, je potřeba přidat do požadovaných prvků několik atributů.

Název atributu Atribut Účel Požaduje se Typ Příklad
SubSelectableDisplayNameAttribute data-sub-selection-display-name Zadejte lokalizovaný řetězec pro zobrazovaný název dílčího prvku. ano string data-sub-selection-display-name="Název vizuálu"
SubSelectableObjectNameAttribute data-sub-selection-object-name Zadejte název objektu, který chcete přidružit ke zkratkám a stylům dílčího výběru. ano string data-sub-selection-object-name="title"
SubSelectableTypeAttribute data-sub-selection-type Zadejte typ vybraného stylu. ano SubSelectionStylesType data-sub-selection-type="1"
SubSelectableDirectEdit přímé úpravy výběru dat Zadejte přímé odkazy na úpravy textu, včetně CardUID, GroupUID a orientace textového pole. ne Podadresář SubSelectableDirectEdit by se měl poskytnout jako řetězec. data-sub-selection-direct-edit="{"reference":{"cardUid":"Visual-title","groupUid":"title-text","sliceUid":"title-text-text"},"style":0}"
SubSelectableHideOutlineAttribute data-sub-selection-hide-outline Zadejte logickou hodnotu pro dílčí prvky, které by neměly mít zobrazenou osnovu. ne boolean data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute data-sub-selection-restricting-element Slouží k označení prvku, který bude omezen, obrysy a typ omezení (upínací nebo klipart) ne SubSelectionOutlineRestrictionType data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute vybraná dílčí výběr dat Určete, jestli je vybraný dílčí výběr, nebo ne. Ne, pomocník ho v případě potřeby přiřadí k prvkům. Logická hodnota data-subselection-sub-selected="true"

Režim formátování

Když vizuál přejde do režimu formátu, musíte zakázat interaktivitu vizuálu, protože očekáváme, že uživatel vybere vizuál a vizuální prvek, aby zahájil formátování.

Veřejné metody HTMLSubSelectionHelper

Obsahuje HTMLSubSelectionHelper některé veřejné metody, které můžete použít, ale existují dvě hlavní metody a pomocná rutina provede zbytek.

Dvě metody jsou setFormatMode a updateOutlinesFromSubSelections.

Mezi veřejné metody pomocné rutiny patří:

  • createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper – Jedná se o statickou metodu, která přebírá argumenty typu HtmlSubselectionHelperArgs a vrací instanci HTMLSubSelectionHelper.

  • setFormatMode(isFormatMode: boolean): void – Tato metoda nastaví režim formátu pro HTMLSubSelectionHelper, If isFormatMode je true, pomocník připojí relevantní naslouchací procesy událostí k prvku hostitele, aby povolil funkce režimu formátu (dílčí výběr, vykreslování osnov).

  • getSubSelectionSourceFromEvent(event: PointerEvent): HtmlSubSelectionSource nebo undefined – vrátí HtmlSubSelectionSource objekt vytvořený podle parametru události.

  • onVisualScroll(): void – označuje htmlSubSelectionHelper, ke kterému aktuálně dochází k posouvání. Posouvání by mělo odebrat obrysy, dokud se posouvání nedokončí.

  • updateElementOutlines(elements: HTMLElement[], visibility: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] – aktualizujte osnovy (a vygeneruje je do Power BI, aby se vykreslovaly) prvků.

  • clearHoveredOutline(): void – tato metoda vymaže najeté obrysy, pokud existují.

  • updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void – update a vygeneruje dané osnovy pro vykreslení.

  • getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] – daná subSelections, tato metoda vrátí relevantní hodnoty HTMLElements.

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

  • hideAllOutlines(suppressRender: boolean = false): void – skryje všechny osnovy s ohledem na suppressRender.

  • getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] – vrátí všechny dílčí možnostiSelectables podle filterType.

  • createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection – vytvoření objektu CustomVisualSubSelection z createVisualSubSelectionArgs.

  • setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void – statická metoda, která nastavuje data pro prvky.

  • getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData – statická metoda, která získá přidružené dříve přiřazené pomocí 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
        }

Chcete-li přidat možnosti omezení ke konkrétnímu HTMLSubSelectionHelper setDataForElement prvku, který používá tento datový typ, pomocník pomocí dat aktualizuje osnovy:

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

Příklad

V tomto příkladu implementujeme customOutlineCallback a selectionIdCallback: Následující kód je ve Visual Code. Ve vizuálu máme objekt s názvem arcElement. Chceme vykreslit osnovu, když je prvek najet myší nebo je vybrán.

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

Importujte HtmlSubSelectionHelper:

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

V kódu konstruktoru vytvořte 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),
            });
    ….
}

V metodě aktualizace vizuálu přidejte následující kód, který aktualizuje osnovy dílčího výběru, aktualizujte stav režimu formátu pro HTMLSubSelectionHelper režim formátování a zakažte interakce, které nejsou pro režim formátu, pokud je režim formátu zapnutý:

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

Související obsah