API ของวิชวล

วิชวลทั้งหมดเริ่มต้นด้วยคลาสที่ใช้ IVisual อินเทอร์เฟซ คุณสามารถตั้งชื่อ class เป็นอะไรก็ได้ตราบใดที่มีหนึ่งคลาสที่ใช้ IVisual อินเทอร์เฟซ

หมายเหตุ

ชื่อคลาสวิชวลต้องเหมือนกับ visualClassName ใน pbiviz.json ไฟล์

คลาสวิชวลควรใช้วิธีการต่อไปนี้ดังที่แสดงในตัวอย่างต่อไปนี้:

• constructor - คอนสตรักเตอร์มาตรฐานที่จะเริ่มต้นสถานะของวิชวล
• update - อัปเดตข้อมูลของวิชวล
• getFormattingModelส่งกลับแบบจําลองการจัดรูปแบบที่เติมบานหน้าต่างคุณสมบัติ (ตัวเลือกการจัดรูปแบบ) ซึ่งคุณสามารถปรับเปลี่ยนคุณสมบัติได้ตามต้องการ
• destroy - ดีสตรัคเตอร์มาตรฐานสําหรับการล้างข้อมูล

class MyVisual implements IVisual {
    
    constructor(options: VisualConstructorOptions) {
        //one time setup code goes here (called once)
    }
    
    public update(options: VisualUpdateOptions): void {
        //code to update your visual goes here (called on all view or data changes)
    }

    public getFormattingModel(): FormattingModel {
        // returns modern format pane formatting model that contain all format pane components and properties (called on opening format and analytics pane or on editing format properties)
    }
    
    public destroy(): void {
        //one time cleanup code goes here (called once)
    }
}

ผู้สร้าง

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

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

อินเทอร์เฟซเหล่านี้ได้รับการอัปเดตด้วย API เวอร์ชันใหม่แต่ละเวอร์ชัน สําหรับรูปแบบอินเทอร์เฟซที่อัปเดตมากที่สุด ให้ไปที่ GitHub repo ของเรา

รายการต่อไปนี้อธิบายคุณสมบัติบางอย่างของ VisualConstructorOptions อินเทอร์เฟซ:

• element: HTMLElement - การอ้างอิงไปยังองค์ประกอบ DOM ที่มีวิชวลของคุณ

• host: IVisualHost - คอลเลกชันของคุณสมบัติและบริการที่สามารถใช้เพื่อโต้ตอบกับโฮสต์วิชวล (Power BI)

  IVisualHost ประกอบด้วยบริการต่อไปนี้:

  • createSelectionIdBuilder - สร้างและจัดเก็บเมตาดาต้าสําหรับรายการที่เลือกได้ในวิชวลของคุณ
  • createSelectionManager- สร้างบริดจ์การสื่อสารที่ใช้เพื่อแจ้งโฮสต์วิชวลเกี่ยวกับการเปลี่ยนแปลงในสถานะตัวเลือก ดูการเลือก API
  • hostCapabilities
  • refreshHostData
  • downloadService- ส่งกลับข้อมูลผลลัพธ์ที่ขยายของการดาวน์โหลด
  • eventService- ส่งกลับข้อมูลเกี่ยวกับการแสดงเหตุการณ์
  • hostEnv
  • displayWarningIcon - ส่งกลับ ข้อผิดพลาดหรือข้อความเตือน
  • licenseManager - ส่งกลับ ข้อมูลสิทธิ์การใช้งาน
  • createLocalizationManager - สร้างผู้จัดการเพื่อช่วยในการ แปลเป็นภาษาท้องถิ่น
  • applyJsonFilter - ใช้ชนิดตัวกรองเฉพาะ ดู API ตัวกรอง
  • applyCustomSort - อนุญาตให้มีตัวเลือก การเรียงลําดับแบบกําหนดเอง
  • acquireAADTokenService- ส่งกลับข้อมูลการรับรองความถูกต้อง Microsoft Entra ID
  • webAccessService - แสดงสถานะสิทธิ์สําหรับ การเข้าถึงทรัพยากรระยะไกล
  • openModalDialog- แสดงกล่องโต้ตอบ
  • persistProperties - อนุญาตให้ผู้ใช้สร้างการตั้งค่าแบบถาวรและบันทึกไปพร้อมกับข้อกําหนดของวิชวลเพื่อให้พร้อมใช้งานในการโหลดครั้งถัดไป
  • eventService- ส่งกลับบริการเหตุการณ์เพื่อสนับสนุนเหตุการณ์การแสดงผล
  • storageService - ส่งกลับบริการเพื่อช่วยในการใช้ ที่เก็บข้อมูล ภายในเครื่องในวิชวล
  • storageV2Service - ส่งกลับบริการเพื่อช่วยในการใช้ ที่เก็บข้อมูล ภายในเครื่องเวอร์ชัน 2 ในวิชวล
  • tooltipService - ส่งกลับ บริการ คําแนะนําเครื่องมือเพื่อช่วยในการใช้คําแนะนําเครื่องมือในวิชวล
  • telemetry
  • drill
  • launchUrl - ช่วยในการ เปิดใช้งาน URL ในแท็บถัดไป
  • authenticationService - ส่งกลับโทเค็น Microsoft Entra ID
  • locale - ส่งกลับสตริงของตําแหน่งที่ตั้ง ดู การแปลเป็นภาษาท้องถิ่น
  • instanceId - ส่งกลับสตริงเพื่อระบุอินสแตนซ์วิชวลปัจจุบัน
  • colorPalette - ส่งกลับ colorPalette ที่จําเป็นในการนําสีไปใช้กับข้อมูลของคุณ
  • fetchMoreData - รองรับการใช้ข้อมูลมากกว่าขีดจํากัดมาตรฐาน (1,000 แถว) ดู ดึงข้อมูลเพิ่มเติม
  • switchFocusModeState - ช่วยในการเปลี่ยนสถานะโหมดโฟกัส

อัพเดต

วิชวลทั้งหมดต้องใช้วิธีการอัปเดตสาธารณะที่ถูกเรียกเมื่อใดก็ตามที่มีการเปลี่ยนแปลงในข้อมูลหรือสภาพแวดล้อมของโฮสต์

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

• viewport: IViewport - ขนาดของวิวพอร์ตที่วิชวลควรแสดงผลภายใน
• dataViews: DataView[] - วัตถุมุมมองข้อมูลที่ประกอบด้วยข้อมูลทั้งหมดที่จําเป็นในการแสดงวิชวลของคุณ (โดยทั่วไปแล้ววิชวลใช้คุณสมบัติประเภทภายใต้ DataView)
• type: VisualUpdateType- ค่าสถานะที่ระบุชนิดของข้อมูลที่ถูกอัปเดต (ปรับขนาด | มุมมอง | ปรับขนาด)
• viewMode: ViewMode - ค่าสถานะที่ระบุโหมดมุมมองของวิชวล (ดู | แก้ไข | InFocusEdit)
• editMode: EditMode- ค่าสถานะที่ระบุโหมดแก้ไขของวิชวล (ค่าเริ่มต้น | ขั้นสูง) (ถ้าวิชวลสนับสนุน AdvancedEditMode วิชวลควรแสดงตัวควบคุม UI ขั้นสูงเฉพาะเมื่อ editMode ถูกตั้งค่าเป็น ขั้นสูง เท่านั้น ดู AdvancedEditMode)
• operationKind?: VisualDataChangeOperationKind- ค่าสถานะที่ระบุชนิดของการเปลี่ยนแปลงข้อมูล (สร้าง | ผนวก)
• jsonFilters?: IFilter[] - คอลเลกชันของตัวกรอง json ที่ใช้
• isInFocus?: boolean - ค่าสถานะเพื่อระบุว่าวิชวลอยู่ในโหมดโฟกัสหรือไม่

getFormattingModel (ตัวเลือก)

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

getFormattingModel(): visuals.FormattingModel;

ทําลาย (ไม่บังคับ)

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

public destroy(): void

เคล็ดลับ

โดยทั่วไป Power BI ไม่ได้เรียกใช้ destroy เนื่องจากการลบ IFrame ทั้งหมดที่มีวิชวลทําได้รวดเร็วกว่า

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

• โครงสร้างของโครงการแสดงผล

• API ที่เก็บข้อมูลภายใน