Teilen über

Dynamisches Drillsteuerelement

  • Artikel

Hinweis

Dieses Feature ist ab API-Version 5.7.0 verfügbar.

Das Feature Dynamisches Drillsteuerelement ermöglicht es dem visuellen Element, das Drillfeature dynamisch mithilfe eines API-Aufrufs zu aktivieren oder zu deaktivieren. Wenn das Drillfeature aktiviert ist, sind alle Drilldownfunktionen und Erweiterungs-/Reduzieren-Features verfügbar, einschließlich API-Aufrufe, Kontextmenübefehle, Header-Drillschaltflächen und Unterstützung für Hierarchiedaten. Wenn es deaktiviert ist, sind diese Funktionen nicht verfügbar.

Die folgenden Bilder zeigen ein Beispiel für ein visuelles Element mit aktivierter und deaktivierter dynamischer Drillsteuerelementfunktion:

Das Feature für dynamische Drillsteuerelemente enthält die folgenden API-Elemente:

  • Das Flag isDrillDisabled in im DataRolesInfo:

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

  • Die Methode setCanDrill in der IVisualHost-Schnittstelle:

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

Um zu ermitteln, ob der Drilldown deaktiviert ist, verwenden Sie die isDrillDisabled-Eigenschaft in der Updatemethode:

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

Verwenden Sie dann den API-Aufruf, um den Drill nach Bedarf zu aktivieren oder zu deaktivieren:

  • So aktivieren Sie: this.host.setCanDrill(true /* drillAllowed */);

  • So deaktivieren Sie: this.host.setCanDrill(false /* drillAllowed */);

Anforderungen für dynamische Drillsteuerelemente

Drilldown ist standardmäßig aktiviert, aber das dynamische Drillsteuerelement-Feature ermöglicht das visuelle Aktivieren oder Deaktivieren des Drilldowns mithilfe eines API-Aufrufs.

Ein visuelles Element mit dem dynamischen Drillsteuerelement-Feature verfügt über den folgenden Code in der Datei capabilities.json:

  • Standardmäßig deaktivierter Drilldown:

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

  • Standardmäßig aktivierter Drilldown:

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

Die canDisableDrill-Eigenschaft gibt an, dass das visuelle Element dieses Feature unterstützt. Ohne diese Eigenschaft wird der API-Aufruf nicht berücksichtigt.
Die disabledByDefault-Eigenschaft gibt an, ob das Drillfeature standardmäßig deaktiviert werden soll.

Hinweis

Die disabledByDefault-Eigenschaft wird wirksam, wenn Sie eine der folgenden Aktionen ausführen:

  • Hinzufügen eines neuen visuellen Elements zum Canvas
  • Konvertieren Sie ein visuelles Element aus einem, das dieses Feature nicht unterstützt.

Wenn Sie beispielsweise ein sourceVisual in ein targetVisual konvertieren, wird die Eigenschaft disabledByDefault des targetVisuals nur berücksichtigt, wenn das sourceVisual diese Funktion nicht unterstützt. Wenn das sourceVisual diese Funktion unterstützt, behält das targetVisual den Zustand des sourceVisuals und nicht den Standardzustand.

Hinzufügen von Drilldownunterstützung zu einer neuen Version eines vorhandenen visuellen Elements

Die Verwendung des Drilldownfeatures stellt eine bedeutende Änderung dar. Um einen möglichst reibungslosen Übergang zu gewährleisten, empfehlen wir Ihnen daher, eine neue visuelle GUID für die neue Version zu verwenden.

Wenn Sie jedoch die gleiche GUID beibehalten möchten, beachten Sie die folgenden Punkte:

  • Wenn Sie von einer nicht drillbaren Version zu einer neuen drillbaren Version migrieren, werden einige Daten in dataView möglicherweise aufgrund der hierarchischen Datenunterstützung, die als Teil des Drillfeatures eingeführt wurde, nicht bereitgestellt. Das Feature für dynamische Drilldownsteuerung bietet keine automatische Unterstützung für dieses Problem, kann jedoch zum Verwalten des Migrationsprozesses verwendet werden.

  • Für die Selbstmigration des visuellen Elements sollte das Visual die folgenden Aktionen ausführen:

    • Identifizieren Sie das erste Mal, wenn die neue Version anstelle der älteren Version geladen wird, und wenden Sie die persistProperties-API an.

    • Deaktivieren Sie den Drilldown, um alle Daten mithilfe der setCanDrill-API zu empfangen.

Das folgende Beispiel zeigt, wie Sie ein älteres Visual zu einem Visual migrieren, das eine dynamische Drillsteuerung verwendet:

  1. Fügen Sie der Datei „capabilities.json“ das folgende Objekt hinzu:

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

  2. Fügen Sie der Datei visual.ts Folgendes hinzu:

    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);
      }
  }

Wenn das visuelle Element nach dem Hinzufügen dieses Codes zum ersten Mal geöffnet wird, wird die DrillMigration-Variable auf „true“ festgelegt, und das visuelle Element wird im Standardzustand geöffnet.

Überlegungen und Einschränkungen

  • Der Drillstatus wird nach dem Deaktivieren des Drilldowns nicht gespeichert. Wenn Sie den Drill nach dem Deaktivieren erneut ausführen können, wird nur die erste Ebene angezeigt, unabhängig davon, was vor der Deaktivierung angezeigt wurde.

  • Der Status „Erweitern/Reduzieren“ wird nach dem Deaktivieren des Drills nicht gespeichert. Alle Zeilen werden reduziert, sobald der Drill erneut ausgeführt wird.

  • Der API-Aufruf wird für Dashboards nicht unterstützt.

  • Verwenden Sie "max": 1 für alle Bedingungen für die drillbare Rolle, um die Anzeige auf ein einziges Feld zu beschränken, wenn der Drill deaktiviert ist. Beispiel:

    • Für kategorische Datenansicht:

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

    • Für die Matrixdatenansicht:

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