動態鑽研控制

發行項
08/06/2024

注意

此功能從 API 版本 5.7.0 開始可用。

動態鑽研控制功能允許視覺效果使用 API 呼叫來動態啟用或停用鑽研功能。啟用鑽研功能時，可使用所有向下切入功能和展開/折疊功能，包括 API 呼叫、快顯功能表命令、標頭鑽研按鈕，以及階層資料支援。停用時，無法使用這些功能。

下列影像顯示已啟用和停用動態鑽研控制功能的視覺效果範例：

已啟用鑽研
已停用鑽研

已停用向下切入的視覺效果螢幕擷取畫面，其中顯示每一大洲以及其下的所有國家/地區。

動態鑽研控制功能包含下列 API 元素：

DataRolesInfo 中的 isDrillDisabled 旗標：

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

IVisualHost 介面中的 setCanDrill 方法：

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

若要識別鑽研是否已停用，請在 update 方法中使用 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，則只有在sourceVisual 不支援此功能時，才會考慮 targetVisual 的 disabledByDefault 屬性。如果 sourceVisual 支援此功能，targetVisual 會保留 sourceVisual 的狀態，而不是預設值。

將向下切入支援新增至新版的現有視覺效果

使用向下切入功能代表重大變更。因此，為了達到最順暢的轉換，建議您針對新版本使用新的視覺 GUID。

不過，如果您想要保留相同的 GUID，請記住下列幾點：

當您從不可鑽研的版本移轉至新的可鑽研版本時，dataView 中可能不會提供某些資料，因為階層式資料支援作為鑽研功能的一部分引進。動態鑽研控制功能不提供此問題的自動支援，但可用來管理移轉程序。
針對視覺效果的自我移轉，視覺效果應該採取下列動作：
- 識別第一次載入新版本，而不是舊版，並套用 persistProperties API。
- 使用 setCanDrill API 停用鑽研以接收所有資料。

下列範例示範如何將較舊的視覺效果自我移轉至使用動態鑽研控制的視覺效果：

在 capabilities.json 檔案中新增下列物件：

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

將下列內容新增至 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 } },
]

共用方式為

動態鑽研控制

動態鑽研控制需求

將向下切入支援新增至新版的現有視覺效果

考量與限制

意見反應

其他資源