API การเลือกย่อย (ตัวอย่าง)

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

วิธีการใช้ API การเลือกย่อย

บริการการเลือกย่อยมีสองวิธี:

• เลือกย่อย
• updateRegionOutlines

เลือกย่อย

ส่งการเลือกย่อยสําหรับ Power BI เพื่อใช้เมื่อผู้ใช้เลือกองค์ประกอบที่อนุญาตให้มีการเลือกย่อย

subSelect(args: visuals.CustomVisualSubSelection | undefined): void

CustomVisualSubSelection
interface CustomVisualSubSelection {
            customVisualObjects: CustomVisualObject[];
            displayName: string;
            subSelectionType: SubSelectionStylesType;
            selectionOrigin: SubSelectionOrigin;
            /** Whether to show the UI for this sub-selection, like formatting context menus and toolbar */
            showUI: boolean;
            /** If immediate direct edit should be triggered, the ID of the sub-selection outline to edit */
            immediateDirectEdit?: string;
            metadata?: unknown;
        }


interface CustomVisualObject {
            objectName: string;
            selectionId: powerbi.visuals.ISelectionId | undefined;
        }

วิธีนี้มีพารามิเตอร์ต่อไปนี้:

• customVisualObjects: อาร์เรย์ที่มี customVisualObjectsobjectName ของวัตถุควรเหมือนกับที่ประกาศใน capabilities.json และ selectionId สําหรับจุดข้อมูลที่เลือก ถ้ามีอยู่
• displayName: ควรแปลชื่อที่แสดงเป็นภาษาท้องถิ่นถ้าวิชวลสนับสนุนการแปลเป็นภาษาท้องถิ่น
• subSelectionType: ชนิดของการเลือกย่อย (รูปร่าง ข้อความ หรือข้อความตัวเลข)
• selectionOrigin: พิกัดขององค์ประกอบที่เลือกย่อย
• showUI: ไม่ว่าจะแสดง UI สําหรับการเลือกย่อยนี้ หรือไม่ เช่น การจัดรูปแบบเมนูบริบทและแถบเครื่องมือ
• immediateDirectEdit: ถ้าการแก้ไขโดยตรงควรได้รับการทริกเกอร์ ID ของเค้าร่างการเลือกย่อยที่จะแก้ไข

ถ้าคุณไม่ใช้ HTMLSubSelectionHelperคุณจําเป็นต้องจัดการการเลือกย่อย

ตัวอย่างการเลือกย่อย

ในตัวอย่างนี้ เราเพิ่มตัวรอรับเหตุการณ์ไปยังองค์ประกอบโฮสต์สําหรับการคลิกขวา เหตุการณ์เมนูบริบท

constructor(options: VisualConstructorOptions) {
        this.hostElement = options.element;
        this.subSelectionService = options.host.subSelectionService;
        ….
}

public update(options: VisualUpdateOptions) {
 if (options.formatMode) {
             // remove event listeners which are irrelevant for format mode.
   …
             this.hostElement.addEventListener('click', this.handleFormatModeClick);
             this.hostElement.addEventListener('contextmenu',  this.handleFormatModeContextMenu);
         } else {
             this.hostElement.removeEventListener('click', this.handleFormatModeClick);
             this.hostElement.removeEventListener('contextmenu', this.handleFormatModeContextMenu);
   …
             // add event listeners which are irrelevant for format mode
         }
 }
 
private handleFormatModeClick(event: MouseEvent): void {
        this.subSelectFromEvent(event, true /**showUI */);
    }

 private handleFormatModeContextMenu(event: MouseEvent): void {
        this.subSelectFromEvent(event, false);
    }

private subSelectFromEvent(event: MouseEvent, showUI: boolean): void {
        //find the element which was selected and fill the needed fields
        const cVObject: powerbi.visuals.CustomVisualObject = {
            objectName: 'myObject',//the object name that is relevant to the clicked element
            selectionId: undefined
        };
        const subSelection: CustomVisualSubSelection = {
            customVisualObjects: [cVObject],
            displayName: 'myObject',
            selectionOrigin: {
                x: event.clientX,
                y: event.clientY
            },
            subSelectionType: SubSelectionStylesType.Shape,// choose the relevant type
            showUI
        };
        this.subSelectionService.subSelect(subSelection);
    }

updateRegionOutlines

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

updateRegionOutlines(outlines: visuals.SubSelectionRegionOutline[]): void

SubSelectionRegionOutline
interface SubSelectionRegionOutline {
            id: string;
            visibility: SubSelectionOutlineVisibility; // controls visibility for outlines
            outline: SubSelectionOutline;
        }

ถ้าคุณไม่ได้ใช้ HTMLSubSelectionHelperคุณจะต้องจัดการเค้าร่างและสถานะด้วยตนเอง (ถ้าเค้าโครงกําลังใช้งานอยู่ โฮเวอร์หรือมองไม่เห็น)

อัปเดตตัวอย่างเค้าร่างภูมิภาค

ในตัวอย่างนี้ เราสมมติว่าเรามีวัตถุที่เรียกว่า myObjectและเราต้องการแสดงเค้าร่างสี่เหลี่ยมผืนผ้าเมื่อวางองค์ประกอบที่เกี่ยวข้องไว้เหนือวัตถุนั้น เราใช้รหัสในตัวอย่างก่อนหน้านี้สําหรับการเลือกย่อย

ในการอัปเดต เราจําเป็นต้องเพิ่มตัวรอรับเหตุการณ์สําหรับ pointerover เหตุการณ์

เราต้องการจัดการเค้าร่างของเราโดยใช้ระเบียน

private subSelectionRegionOutlines: Record<string, SubSelectionRegionOutline > = {};


public update(options: VisualUpdateOptions) {
 if (options.formatMode) {
             // remove event listeners which are irrelevant for format mode.
   …
             this.hostElement.addEventListener('click', this.handleFormatModeClick);
             this.hostElement.addEventListener('contextmenu',  this.handleFormatModeContextMenu);
   this.hostElement.addEventListener('pointerover', this.handleFormatModePointerOver);
         } else {
             this.hostElement.removeEventListener('click', this.handleFormatModeClick);
             this.hostElement.removeEventListener('contextmenu', this.handleFormatModeContextMenu);
   this.hostElement.removeEventListener('pointerover', this.handleFormatModePointerOver);
   …
             // add event listeners which are irrelevant for format mode
         }
 }
 
 private handleFormatModePointerOver(event: MouseEvent): void {
         // use the event to extract the element that was hovered.
         // in this example we assume that we found the element and it is related to object called myObject.
         // we need to clear previously hovered outlines before rendering
         const regionOutlines = getValues(this.subSelectionRegionOutlines);
         const hoveredOutline = regionOutlines.find(outline => outline.visibility === SubSelectionOutlineVisibility.Hover);
         if (hoveredOutline) {
             this.subSelectionRegionOutlines[hoveredOutline.id] = {
                 ...this.subSelectionRegionOutlines[hoveredOutline.id],
                 visibility: powerbi.visuals.SubSelectionOutlineVisibility.None
             };
         }
         // now we will build the outline for myObject relevant element.
         let element: HTMLElement;// assume we found the relevant element.
         const domRect = element.getBoundingClientRect();
         const { x, y, width, height } = domRect;
         const outline: powerbi.visuals.RectangleSubSelectionOutline = {
             height,
             width,
             x,
             y,
             type: powerbi.visuals.SubSelectionOutlineType.Rectangle,
         };
     
         const regionOutline: powerbi.visuals.SubSelectionRegionOutline = {
             id: 'myObject',
             visibility: powerbi.visuals.SubSelectionOutlineVisibility.Hover,
             outline
         };
         this.subSelectionRegionOutlines[regionOutline.id] = regionOutline;
         this.renderOutlines();
         // you need to remove the hovered outline when the element is not hovered anymore
     }
     private renderOutlines(): void {
         const regionOutlines = getValues(this.subSelectionRegionOutlines);
         this.subSelectionService.updateRegionOutlines(regionOutlines);
     }

เนื้อหาที่เกี่ยวข้อง

• บนยูทิลิตี้วัตถุ
• API การจัดรูปแบบบนวัตถุ