การควบคุมการดูรายละเอียดแบบไดนามิก

หมายเหตุ

คุณลักษณะนี้จะพร้อมใช้งานจาก API เวอร์ชัน 5.7.0

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

รูปภาพต่อไปนี้แสดงตัวอย่างของวิชวลที่เปิดใช้งานและปิดใช้งานคุณลักษณะการควบคุมการดูรายละเอียดแบบไดนามิก:

เปิดใช้งานการดูรายละเอียด

ปิดใช้งานการดูรายละเอียด

คุณลักษณะการควบคุมการดูรายละเอียดแบบไดนามิกประกอบด้วยองค์ประกอบ API ต่อไปนี้:

• ค่า isDrillDisabled สถานะใน DataRolesInfo:

  export interface DataRolesInfo {
        //…
        isDrillDisabled?: boolean; // ----- NEW -----
    }
  

• setCanDrillวิธีการในIVisualHostอินเทอร์เฟซ:

    export interface IVisualHost extends extensibility.IVisualHost {
        //…
        setCanDrill: (drillAllowed: boolean) => void; // ----- NEW -----
    }
  

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

    private update(options: VisualUpdateOptions) {
      //…
      const isDrillDisabled = options.dataViews[0].metadata.dataRoles.isDrillDisabled;
      //…
    }

จากนั้นใช้การเรียกใช้ API เพื่อเปิดหรือปิดใช้งานการดูข้อมูลแบบเจาะลึกตามความจําเป็น:

• เพื่อเปิดใช้งาน: this.host.setCanDrill(true /* drillAllowed */);

• เพื่อปิดใช้งาน: this.host.setCanDrill(false /* drillAllowed */);

ข้อกําหนดการควบคุมการดูรายละเอียดแบบไดนามิก

เปิดใช้งานการดูรายละเอียดตามค่าเริ่มต้น แต่คุณลักษณะการควบคุมการ ดูรายละเอียดแบบไดนามิกอนุญาตให้วิชวลเปิดใช้งานหรือปิดใช้งานการเข้าถึงรายละเอียดโดยใช้การเรียกใช้ API

วิชวลที่มีคุณลักษณะการควบคุมการดูรายละเอียดแบบไดนามิกมีโค้ดต่อไปนี้ใน ไฟล์ capabilities.json :

• เมื่อปิดใช้งานการดูรายละเอียดแนวลึกตามค่าเริ่มต้น:

      "drilldown": {
          "roles": [
              "Rows",
              "Columns"
          ],
          "canDisableDrill": { 
              "disabledByDefault": true
          }
      },
  

• มีการเปิดใช้งานการดูรายละเอียดแบบเจาะลึกตามค่าเริ่มต้น:

      "drilldown": {
          "roles": [
              "Rows",
              "Columns"
          ],
          "canDisableDrill": {}
      },
  

คุณสมบัติ canDisableDrill ระบุว่าวิชวลสนับสนุนคุณลักษณะนี้ หากไม่มีคุณสมบัตินี้ การเรียกใช้ API จะไม่ปฏิบัติตาม
คุณสมบัติ disabledByDefault ระบุว่าจะปิดใช้งานคุณลักษณะการดูรายละเอียดตามค่าเริ่มต้นหรือไม่

หมายเหตุ

คุณสมบัติ disabledByDefault จะมีผลเมื่อคุณทําหนึ่งในการดําเนินการต่อไปนี้:

• เพิ่มวิชวลใหม่ไปยังพื้นที่ทํางาน
• แปลงวิชวลจากวิชวลที่ไม่สนับสนุนคุณลักษณะนี้

ตัวอย่างเช่น ถ้าคุณแปลง sourceVisual เป็น targetVisual คุณสมบัติของ targetVisualdisabledByDefault จะถูกพิจารณาเฉพาะเมื่อ sourceVisual ไม่สนับสนุนคุณลักษณะนี้ ถ้า sourceVisual สนับสนุนคุณลักษณะ นี้ targetVisual จะ รักษาสถานะของ sourceVisual และไม่ใช่ค่าเริ่มต้น

เพิ่มการสนับสนุนการดูรายละเอียดแนวลึกในวิชวลที่มีอยู่เวอร์ชันใหม่

การใช้คุณลักษณะการดูรายละเอียดแนวลึกแสดงถึงการเปลี่ยนแปลงการแบ่งย่อย ดังนั้น สําหรับการเปลี่ยนที่ราบรื่นที่สุด เราขอแนะนําให้คุณใช้ GUID วิชวลใหม่สําหรับเวอร์ชันใหม่

อย่างไรก็ตาม หากคุณต้องการใช้ GUID เดียวกัน โปรดคํานึงถึงประเด็นต่อไปนี้:

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

• สําหรับการโยกย้ายวิชวลด้วยตนเอง วิชวลควรดําเนินการต่อไปนี้:

  • ระบุครั้งแรกที่มีการโหลดเวอร์ชันใหม่แทนเวอร์ชันเก่าและใช้ persistProperties API

  • ปิดใช้งานการดูรายละเอียดเพื่อรับข้อมูลทั้งหมดโดยใช้ setCanDrill API

ตัวอย่างต่อไปนี้แสดงวิธีการโยกย้ายวิชวลเก่าไปยังวิชวลแบบเก่าด้วยตนเองไปยังวิชวลที่ใช้การควบคุมการดูรายละเอียดแบบไดนามิก:

1. เพิ่มวัตถุต่อไปนี้ลงในไฟล์ capabilities.json:

   "DrillMigration": {
     "displayName": "Drill Migration",
     "properties": {
         "isMigrated": {
             "displayName": "Is Drill Migrated",
             "type": {
                 "bool": true
             }
         }
     }
   },
   

2. เพิ่มสิ่งต่อไปนี้ลงใน ไฟล์ visual.ts :

   export class Visual implements IVisual {
       //...
         private isCalledToDisableDrillInMigrationScenario = false;
         private drillMigration = { disabledByDefault: true };
         constructor(options: VisualConstructorOptions) {
          //...
          this.host = options.host;
          //...
         }
         private update(options: VisualUpdateOptions) {
            this.handleSelfDrillMigration(options);
             //...
         }
         private handleSelfDrillMigration(options: VisualUpdateOptions): void {
             if (options && options.dataViews && options.dataViews[0] && options.dataViews[0].metadata) {
                 const metadata = options.dataViews[0].metadata;
                 if (metadata && metadata.dataRoles) {
                     const isDrillDisabled = metadata.dataRoles.isDrillDisabled;
                     if (isDrillDisabled === undefined) {
                         return;
                     }
                     // Continue in case the visual is already migrated
                     if (!metadata.objects?.DrillMigration?.isMigrated) {
                         // Persist the isMigrated property when the drill has the correct state
                         if (this.drillMigration.disabledByDefault === isDrillDisabled) {
                             this.persistMigrationProperty();
                         } else if (!this.isCalledToDisableDrillInMigrationScenario) {
                             // Use the API call only once
                             this.host.setCanDrill(!this.drillMigration.disabledByDefault);
                             this.isCalledToDisableDrillInMigrationScenario = true;
                         }
                     }
                 }
             }
         }
         private persistMigrationProperty(): void {
             let property = {
                 merge: [{
                     objectName: "DrillMigration",
                     properties: {
                         isMigrated: true
                     },
                     selector: null
                 }]
             };
             this.host.persistProperties(property);
         }
     }
   

ครั้งแรกที่เปิดวิชวลหลังจากเพิ่มโค้ดนี้ ตัวแปร DrillMigration จะถูกตั้งค่าเป็น true และวิชวลจะเปิดขึ้นในสถานะเริ่มต้น

ข้อควรพิจารณาและข้อจำกัด

• สถานะการดูรายละเอียดจะไม่ถูกบันทึกหลังจากปิดใช้งานการดูรายละเอียด ถ้าคุณเปิดใช้งานการดูรายละเอียดอีกครั้งหลังจากปิดใช้งาน จะมีเฉพาะระดับแรกเท่านั้นที่จะแสดงโดยไม่คํานึงถึงสิ่งที่แสดงก่อนที่จะปิดใช้งาน

• สถานะขยาย/ยุบจะไม่ถูกบันทึกหลังจากปิดใช้งานการดูรายละเอียด แถวทั้งหมดจะถูกยุบเมื่อมีการเปิดใช้งานการดูรายละเอียด

• การเรียกใช้ API ไม่ได้รับการสนับสนุนสําหรับแดชบอร์ด

• เงื่อนไขการแมปมุมมองข้อมูล: ใช้สําหรับ "max": 1 เงื่อนไขทั้งหมดสําหรับบทบาทที่เจาะได้เพื่อจํากัดวิชวลให้แสดงเขตข้อมูลเดียวเท่านั้นเมื่อปิดใช้งานการดูรายละเอียด ตัวอย่างเช่น:

  • สําหรับมุมมองข้อมูลแบบจัดกลุ่ม:

    "conditions": [
         { "category": { "min": 1 }, "measure": { "max": 1 }}
    ]
    

  • สําหรับมุมมองข้อมูลเมทริกซ์:

    "conditions": [
        { "Rows": { "max": 0 }, "Columns": { "max": 0 }, "Value": { "min": 1 } },
        { "Rows": { "min": 1 }, "Columns": { "min": 0 }, "Value": { "min": 0 } },
        { "Rows": { "min": 0 }, "Columns": { "min": 1 }, "Value": { "min": 0 } },
    ]