Partager via

Utilitaires sur objet - assistance de sous-sélection (préversion)

  • Article

La classe HTMLSubSelectionHelper offre un moyen simple pour votre visuel personnalisé Power BI d’émettre des sous-sélections dans Power BI, ainsi que d’avoir et d’afficher des contours.

HTMLSubSelectionHelper est une classe d’assistance destinée à faciliter la création et la gestion de contours de sous-sélection. Elle contient des méthodes pour rechercher des éléments sous-sélectionnables.

Les utilitaires exportent des classes et attributs CSS pour faciliter la définition et la maintenance des sous-sélections du visuel.

Remarque

Utilisez la version 6.0.1 ou ultérieure des utilitaires.

Pour définir des éléments sous-sélectionnables, nous devons également ajouter une classe à chaque élément souhaité.

Classe CSS Objectif Requis
subselectable Fournir un sélecteur pour que le HTMLSubSelectionHelper trouve des sous-sélections possibles Oui

Pour définir des sous-sélections pour le visuel, quelques attributs doivent être ajoutés aux éléments souhaités.

Nom de l’attribut Attribut Objectif Requis Type Exemple
SubSelectableDisplayNameAttribute data-sub-selection-display-name Fournir une chaîne localisée pour le nom d’affichage de l’élément sous-sélectionné Oui string data-sub-selection-display-name="Nom du visuel"
SubSelectableObjectNameAttribute data-sub-selection-object-name Fournir un nom d’objet à associer aux raccourcis et au style des sous-sélections Oui string data-sub-selection-object-name="nom"
SubSelectableTypeAttribute data-sub-selection-type Fournir le type du style sous-sélectionné Oui SubSelectionStylesType data-sub-selection-type="1"
SubSelectableDirectEdit data-sub-selection-direct-edit Fournir des références directes de modification de texte, notamment CardUID, GroupUID et l’orientation de la zone de texte non SubSelectableDirectEdit doit être fourni sous forme de chaîne data-sub-selection-direct-edit="{"reference":{"cardUid":"Visual-title","groupUid":"title-text","sliceUid":"title-text-text"},"style":0}"
SubSelectableHideOutlineAttribute data-sub-selection-hide-outline Fournir une valeur booléenne pour les éléments sous-sélectionnables qui ne doivent pas avoir de contour visible non booléen data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute data-sub-selection-restricting-element Utilisé pour indiquer l’élément qui sera restreint, les contours et le type de restriction (ajustement ou masquage) non SubSelectionOutlineRestrictionType data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute data-sub-selection-sub-selected Indiquer si l’élément sous-sélectionnable est sélectionné ou pas Non, la classe d’assistance l’affecte aux éléments si nécessaire Boolean data-subselection-sub-selected="true"

Mode Mise en forme

Lorsque le visuel entre en mode Mise en forme, vous devez désactiver l’interactivité pour le visuel, car l’utilisateur doit normalement sélectionner le visuel et l’élément visuel pour commencer la mise en forme.

Méthodes publiques HTMLSubSelectionHelper

La classe HTMLSubSelectionHelper a quelques méthodes publiques que vous pouvez utiliser, mais il y en a deux principales et la classe d’assistance s’occupe du reste.

Les deux méthodes sont setFormatMode et updateOutlinesFromSubSelections.

Les méthodes publiques de la classe d’assistance sont les suivantes :

  • createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper - Il s’agit d’une méthode statique qui prend les arguments de type HtmlSubselectionHelperArgs et retourne une instance de HTMLSubSelectionHelper.

  • setFormatMode(isFormatMode: boolean): void - Cette méthode définit le mode Mise en forme pour HTMLSubSelectionHelper. Si isFormatMode a la valeur true, la classe d’assistance attache les écouteurs d’événements appropriés à l’élément hôte pour activer le mode Mise en forme (sous-sélection, rendu des contours).

  • getSubSelectionSourceFromEvent(event: PointerEvent): HtmlSubSelectionSource ou undefined - Retourne un objet HtmlSubSelectionSource qui est généré en fonction du paramètre d’événement.

  • onVisualScroll(): void - Indique à la classe HTMLSubSelectionHelper que le défilement est en cours. Le défilement doit supprimer les contours jusqu’à ce qu’il se termine.

  • updateElementOutlines(elements: HTMLElement[], visibility: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] - Met à jour les contours (et les émet pour leur rendu dans Power BI) des éléments.

  • clearHoveredOutline(): void - Cette méthode efface les contours survolés, le cas échéant.

  • updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void - Met à jour et émet les contours donnés pour leur rendu.

  • getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] - subSelections donnés, cette méthode retourne les HTMLElements appropriés.

  • updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: boolean): void - Met à jour et affiche les contours de la subSelection donnée conformément à suppressRender et clearExistingOutlines.

  • hideAllOutlines(suppressRender: boolean = false): void - Masque tous les contours conformément à suppressRender.

  • getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] - Retourne tous les éléments subSelectables en fonction du filterType.

  • createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection - Crée l’objet CustomVisualSubSelection à partir des createVisualSubSelectionArgs.

  • setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void - Méthode statique qui définit les données pour les éléments.

  • getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData - Méthode statique qui obtient les éléments précédemment attribués associés en utilisant 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
        }

Pour ajouter des options de restriction à un élément spécifique, utilisez le HTMLSubSelectionHelper setDataForElement type de données avec ce type de données, l’assistance utilise les données pour mettre à jour les contours :

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

Exemple

Dans cet exemple, nous implémentons customOutlineCallback et selectionIdCallback. Le code suivant est dans Visual Code. Nous avons un objet dans le visuel appelé arcElement. Nous voulons afficher le contour lorsque l’élément est survolé ou sous-sélectionné.

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

Importez htmlSubSelectionHelper :

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

Dans le code du constructeur, créez 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),
            });
    ….
}

Dans la méthode de mise à jour du visuel, ajoutez le code suivant pour mettre à jour les contours de la subSelection, mettez à jour l’état du mode Mise à jour de la classe HTMLSubSelectionHelper et désactivez les interactions qui ne sont pas pour le mode Mise en forme si celui-ci est activé :

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

Contenu connexe