Βοηθητικά προγράμματα on-object - βοηθητική εφαρμογή δευτερεύουσας ενότητας (προεπισκόπηση)

Παρέχει HTMLSubSelectionHelper έναν εύκολο τρόπο για την προσαρμοσμένη απεικόνισή σας Power BI να εκπέμπει υποεπιλογές στο Power BI, να λαμβάνει και να αποδίδει περιγράμματα.

HTMLSubSelectionHelper Το είναι μια κλάση βοηθητικής εφαρμογής που προορίζεται για να διευκολύνει τη δημιουργία και την επακόλουθη διαχείριση των περιγραμμάτων δευτερεύουσας ενότητας. Περιέχει μεθόδους για την εύρεση στοιχείων με δυνατότητα δευτερεύουσας επιλογής.

Τα βοηθητικά προγράμματα εξάγουν κλάσεις και χαρακτηριστικά CSS, διευκολύνοντας τον ορισμό και τη διατήρηση δευτερευουσών επιλογών για την απεικόνιση.

Σημείωμα

Χρησιμοποιήστε την έκδοση 6.0.1 ή νεότερη των βοηθητικών προγραμμάτων.

Για να ορίσουμε στοιχεία με δυνατότητα δευτερεύουσας επιλογής, πρέπει επίσης να προσθέσουμε μια κλάση σε κάθε επιθυμητό στοιχείο.

CSS Κλάση	Σκοπός	Απαραίτητο
με δυνατότητα δευτερεύουσας επιλογής	Παρέχει έναν επιλογέα για την HTMLSubSelectionHelper εύρεση πιθανών δευτερευουσών επιλογών	Ναι

Για να ορίσετε υποεπιλογές για την απεικόνιση, υπάρχουν μερικά χαρακτηριστικά που πρέπει να προστεθούν στα επιθυμητά στοιχεία.

Όνομα χαρακτηριστικού	Χαρακτηριστικό	Σκοπός	Απαραίτητο	Τύπος	Παράδειγμα
SubSelectableDisplayNameAttribute	data-sub-selection-display-name	Εισαγάγετε μια μεταφραζόμενη συμβολοσειρά για το εμφανιζόμενο όνομα του στοιχείου της δευτερεύουσας επιλογής	Ναι	συμβολοσειρά	data-sub-selection-display-name="Visual Title"
SubSelectableObjectNameAttribute	data-sub-selection-object-name	Καταχωρήστε ένα όνομα αντικειμένου για συσχέτιση με συντομεύσεις και στυλ δευτερεύουσας επιλογής	Ναι	συμβολοσειρά	data-sub-selection-object-name="title"
SubSelectableTypeAttribute	τύπος-δευτερεύουσας-επιλογής δεδομένων	Εισαγάγετε τον τύπο του στυλ της δευτερεύουσας επιλογής	Ναι	SubSelectionStylesType	data-sub-selection-type="1"
SubSelectableDirectEdit	data-sub-selection-direct-edit	Παροχή αναφορών επεξεργασίας άμεσου κειμένου, συμπεριλαμβανομένων των CardUID, GroupUID και του προσανατολισμού του πλαισίου κειμένου	Όχι	Το SubSelectableDirectEdit θα πρέπει να παρέχεται ως συμβολοσειρά	data-sub-selection-direct-edit="{"reference":{"cardUid":"Visual-title","groupUid":"title-text","sliceUid":"title-text-text"},"style":0}"
SubSelectableHideOutlineAttribute	data-sub-selection-hide-outline	Παροχή μιας δυαδικής τιμής για στοιχεία με δυνατότητα δευτερεύουσας επιλογής, στα οποία δεν θα πρέπει να εμφανίζεται ένα περίγραμμα	Όχι	boolean	data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute	data-sub-selection-restricting-element	Χρησιμοποιείται για να υποδείξει το στοιχείο που θα είναι περιορισμένο, τα περιγράμματα και τον τύπο περιορισμού (σφιγκτήρας ή κλιπ)	Όχι	SubSelectionOutlineRestrictionType	data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute	data-sub-selection-sub-selected	Υποδεικνύει εάν επιλέγεται ή όχι η δευτερεύουσα επιλογή	Όχι, η βοηθητική εφαρμογή την εκχωρεί στα στοιχεία όταν χρειάζεται	Boolean	data-subselection-sub-selected="true"

Λειτουργία μορφοποίησης

Όταν η απεικόνιση μορφοποιηθεί, πρέπει να απενεργοποιήσετε την αλληλεπίδραση για την απεικόνιση, καθώς αναμένουμε από τον χρήστη να επιλέξει την απεικόνιση και το οπτικό στοιχείο για να ξεκινήσει τη μορφοποίηση.

Δημόσιες μέθοδοι HTMLSubSelectionHelper

Το HTMLSubSelectionHelper έχει ορισμένες δημόσιες μεθόδους που μπορείτε να χρησιμοποιήσετε, αλλά υπάρχουν δύο κύριες μέθοδοι και ο βοηθητικός χρήστης κάνει τα υπόλοιπα.

Οι δύο μέθοδοι είναι setFormatMode και updateOutlinesFromSubSelections.

Οι δημόσιες μέθοδοι της βοηθητικής εφαρμογής περιλαμβάνουν τα εξής:

• createHtmlSubselectionHelper(οργές: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper - Αυτή είναι μια στατική μέθοδος που λαμβάνει οργώσεις τύπου HtmlSubselectionHelperArgs και επιστρέφει μια παρουσία του HTMLSubSelectionHelper.

• setFormatMode(isFormatMode: boolean): void - Αυτή η μέθοδος ορίζει τη λειτουργία μορφοποίησης για το HTMLSubSelectionHelper, If isFormatMode είναι true, η βοηθητική υπηρεσία επισυνάπτει σχετικές ακροατές συμβάντων στο στοιχείο κεντρικού υπολογιστή για να ενεργοποιήσει τη λειτουργία μορφοποίησης (δευτερεύουσα επιλογή, απόδοση περιγραμμάτων).

• getSubSelectionSourceFromEvent(event: PointerEvent): HtmlSubSelectionSource ή μη καθορισμένο - επιστρέφει ένα HtmlSubSelectionSource αντικείμενο που έχει δημιουργηθεί σύμφωνα με την παράμετρο συμβάντος.

• onVisualScroll(): void - Υποδεικνύει στην HTMLSubSelectionHelper ότι αυτή τη στιγμή πραγματοποιείται κύλιση. Η κύλιση θα πρέπει να καταργήσει τα περιγράμματα μέχρι να ολοκληρωθεί η κύλιση.

• updateElementOutlines(elements: HTMLElement[], visibility: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] - ενημερώστε τα περιγράμματα (και τα εκπέμπετε στο Power BI για να αποδοθούν) των στοιχείων.

• clearHoveredOutline(): void - Αυτή η μέθοδος απαλείφει τα περιγράμματα που αιωρούνται εάν υπάρχουν.

• updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void - ενημερώστε και εκπέμπετε τα δεδομένα περιγράμματα για να αποδοθούν.

• getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] - δεδομένου του subSelections, αυτή η μέθοδος επιστρέφει τις σχετικές HTMLElements.

• updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: boolean): void - ενημερώνει και αποδίδει τα περιγράμματα για τη δεδομένη υποεπιλογή σε σχέση με την καταστολή τουRender και της εκκαθάρισηςExistingOutlines.

• hideAllOutlines(suppressRender: boolean = false): void - αποκρύψτε όλες τις περιγράμματα σε σχέση με την suppressRender.

• getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] - επιστρέφει όλα τα υποεπιλεγόμενα σύμφωνα με το filterType.

• createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection - δημιουργήστε το αντικείμενο CustomVisualSubSelection από το createVisualSubSelectionArgs.

• setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void - μια στατική μέθοδος που ορίζει δεδομένα για τα στοιχεία.

• getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData - μια στατική μέθοδος που λαμβάνει τη συσχετισμένη μέθοδο που αντιστοιχίστηκε προηγουμένως με τη συνάρτηση 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
        }

Για να προσθέσετε επιλογές περιορισμού σε ένα συγκεκριμένο στοιχείο, χρησιμοποιήστε το HTMLSubSelectionHelpersetDataForElement με αυτόν τον τύπο δεδομένων, η βοηθητική εφαρμογή χρησιμοποιεί τα δεδομένα για να ενημερώσει τις περιγράμματα:

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

Παράδειγμα

Σε αυτό το παράδειγμα, υλοποιούμε customOutlineCallback τα και selectionIdCallback: Ο ακόλουθος κώδικας βρίσκεται στον Κώδικα απεικόνισης. Έχουμε ένα αντικείμενο στην απεικόνιση που ονομάζεται arcElement. Θέλουμε να αποδώσετε το περίγραμμα όταν κατάδειξη ή δευτερεύουσα επιλογή του στοιχείου.

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

Εισαγάγετε το HtmlSubSelectionHelper:

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

Στον κώδικα κατασκευής, δημιουργήστε το 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),
            });
    ….
}

Στη μέθοδο ενημέρωσης της απεικόνισης, προσθέστε τον παρακάτω κώδικα για να ενημερώσετε τις περιγράμματα της δευτερεύουσαςεπιλογής, ενημερώστε την κατάσταση της λειτουργίας μορφοποίησης για το HTMLSubSelectionHelper και απενεργοποιήστε τις αλληλεπιδράσεις που δεν αφορούν τη λειτουργία μορφοποίησης εάν η λειτουργία μορφοποίησης είναι ενεργοποιημένη:

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

Σχετικό περιεχόμενο

• API δευτερεύουσας επιλογής
• API μορφοποίησης αντικειμένου