动态钻取控制

项目
06/06/2024

注意

从 API 5.7.0 版开始提供此功能。

动态钻取控制功能允许视觉对象使用 API 调用动态启用或禁用钻取功能。启用钻取功能后，可以使用所有向下钻取功能和展开/折叠功能，包括 API 调用、上下文菜单命令、标头钻取按钮以及对层次结构数据的支持。禁用钻取功能后，这些功能不可用。

下图显示了启用和禁用动态钻取控制功能的视觉对象示例：

已启用钻取
已禁用钻取

Screenshot of a visual with drilldown disabled displaying each continent with all the countries/regions in that continent displayed under it.

动态钻取控制功能包括以下 API 元素：

isDrillDisabled 中的 DataRolesInfo 标志：

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

setCanDrill 接口中的 IVisualHost 方法：

  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 } },
]

通过

动态钻取控制

动态钻取控制要求

向新版现有视觉对象添加向下钻取支持

注意事项和限制

反馈

其他资源