ยูทิลิตี้บนวัตถุ - ตัวช่วยการเลือกย่อย (ตัวอย่าง)

มี HTMLSubSelectionHelper วิธีง่าย ๆ สําหรับวิชวลแบบกําหนดเองของ Power BI ของคุณเพื่อปล่อยการเลือกย่อยไปยัง Power BI รับ และแสดงเค้าร่าง

HTMLSubSelectionHelper เป็นคลาสผู้ช่วยเหลือที่มีวัตถุประสงค์เพื่ออํานวยความสะดวกในการสร้างและการจัดการโครงร่างการเลือกย่อยที่ตามมา ซึ่งประกอบด้วยวิธีการสําหรับการค้นหาองค์ประกอบที่สามารถเลือกได้ย่อย

ยูทิลิตี้จะส่งออกคลาสและแอตทริบิวต์ CSS ทําให้วิชวลกําหนดและรักษาการเลือกย่อยได้ง่ายขึ้น

หากต้องการกําหนดองค์ประกอบที่สามารถเลือกได้ย่อย เรายังจําเป็นต้องเพิ่มคลาสไปยังแต่ละองค์ประกอบที่ต้องการ

หากต้องการกําหนดการเลือกย่อยสําหรับวิชวล มีแอตทริบิวต์บางอย่างที่จําเป็นต้องเพิ่มลงในองค์ประกอบที่ต้องการ

โหมดรูปแบบ

เมื่อวิชวลเข้าสู่โหมดรูปแบบ คุณจําเป็นต้องปิดใช้งานการโต้ตอบสําหรับวิชวล ดังที่เราคาดหวังให้ผู้ใช้เลือกองค์ประกอบวิชวลและวิชวลเพื่อเริ่มการจัดรูปแบบ

วิธีสาธารณะของ HTMLSubSelectionHelper

HTMLSubSelectionHelperมีวิธีการสาธารณะบางอย่างที่คุณสามารถใช้ได้ แต่มีสองวิธีหลักและผู้ช่วยเหลือจะจัดการส่วนที่เหลือ

สองวิธีคือ setFormatMode และupdateOutlinesFromSubSelections

วิธีการสาธารณะของผู้ช่วยเหลือประกอบด้วย:

• createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper - นี่คือเมธอดแบบคงที่ที่ใช้ args ชนิดHtmlSubselectionHelperArgsและส่งกลับตัวอย่างของHTMLSubSelectionHelper

• setFormatMode(isFormatMode: boolean): void - วิธีนี้ตั้งค่าโหมดรูปแบบสําหรับ HTMLSubSelectionHelper ถ้า isFormatMode เป็นจริง ผู้ช่วยเหลือจะแนบตัวรอรับการติดต่อเหตุการณ์ที่เกี่ยวข้องเข้ากับองค์ประกอบโฮสต์เพื่อเปิดใช้งานฟังก์ชันโหมดรูปแบบ (การเลือกย่อย ที่แสดงเค้าร่าง)

• getSubSelectionSourceFromEvent(เหตุการณ์: PointerEvent): HtmlSubSelectionSource หรือ ไม่ได้ระบุ - ส่งกลับ HtmlSubSelectionSource ออบเจ็กต์ที่สร้างขึ้นตามพารามิเตอร์เหตุการณ์

• onVisualScroll(): void - ระบุถึง HTMLSubSelectionHelper ที่กําลังเลื่อนเกิดขึ้นในขณะนี้ การเลื่อนควรเอาเค้าร่างออกจนกว่าการเลื่อนจะเสร็จสิ้น

• updateElementOutlines(elements: HTMLElement[], การมองเห็น: SubSelectionOutlineVisibility, suppressRender: บูลีน = เท็จ): SubSelectionRegionOutlineId[] - อัปเดตเค้าร่าง (และปล่อยพารามิเตอร์ดังกล่าวไปยัง Power BI เพื่อแสดง) ขององค์ประกอบ

• clearHoveredOutline(): void - วิธีนี้จะล้างเค้าร่างที่โฮเวอร์ถ้ามีอยู่

• updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: บูลีน = เท็จ): โมฆะ - อัปเดตและปล่อยเค้าร่างที่กําหนดเพื่อแสดง

• getElementsFromSubSelections(การเลือกย่อย: CustomVisualSubSelection []): HTMLElement[] - กําหนดการเลือกย่อย วิธีนี้จะส่งกลับ HTMLElements ที่เกี่ยวข้อง

• updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: บูลีน, suppressRender?: บูลีน): โมฆะ - อัปเดตและแสดงเค้าร่างสําหรับส่วนย่อยที่กําหนดตาม suppressRender และล้าง ExistingOutlines

• hideAllOutlines(suppressRender: boolean = false): void - ซ่อนเค้าร่างทั้งหมดตาม suppressRender

• getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] - ส่งกลับ subSelectables ทั้งหมดตาม 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
        }

หากต้องการเพิ่มตัวเลือกข้อจํากัดให้กับองค์ประกอบเฉพาะ ให้ใช้ HTMLSubSelectionHelper setDataForElement กับชนิดข้อมูลนี้ ผู้ช่วยเหลือจะใช้ข้อมูลเพื่ออัปเดตเค้าร่าง:

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 การจัดรูปแบบบนวัตถุ