Dela via

Dynamisk detaljkontroll

  • Artikel

Kommentar

Den här funktionen är tillgänglig från API version 5.7.0.

Funktionen för dynamisk detaljnivåkontroll gör att det visuella objektet kan aktivera eller inaktivera funktionen för detaljgranskning dynamiskt med hjälp av ett API-anrop. När detaljgranskningsfunktionen är aktiverad är alla funktioner för ökad detaljnivå och funktioner för att expandera/komprimera tillgängliga, inklusive API-anrop, snabbmenykommandon, knappar för sidhuvudgranskning och stöd för hierarkidata. När de är inaktiverade är dessa funktioner inte tillgängliga.

Följande bilder visar ett exempel på ett visuellt objekt med funktionen för dynamisk detaljkontroll aktiverad och inaktiverad:

Funktionen för dynamisk detaljnivåkontroll innehåller följande API-element:

  • Flaggan isDrillDisabled i DataRolesInfo:

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

  • Metoden setCanDrill i IVisualHost gränssnittet:

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

Om du vill identifiera om detaljnivån är inaktiverad använder du isDrillDisabled egenskapen i uppdateringsmetoden:

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

Använd sedan API-anropet för att aktivera eller inaktivera detaljnivån efter behov:

  • Så här aktiverar du: this.host.setCanDrill(true /* drillAllowed */);

  • Så här inaktiverar du: this.host.setCanDrill(false /* drillAllowed */);

Krav för dynamisk detaljnivåkontroll

Borrning är aktiverat som standard, men med funktionen för dynamisk detaljkontroll kan det visuella objektet aktivera eller inaktivera borrning med hjälp av ett API-anrop.

Ett visuellt objekt med funktionen för dynamisk detaljkontroll har följande kod i filen capabilities.json :

  • Med detaljnivån inaktiverad som standard:

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

  • Med detaljnivån aktiverad som standard:

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

Egenskapen canDisableDrill anger att det visuella objektet stöder den här funktionen. Utan den här egenskapen respekteras inte API-anropet.
Egenskapen disabledByDefault anger om du vill inaktivera detaljgranskningsfunktionen som standard.

Kommentar

Egenskapen disabledByDefault börjar gälla när du utför någon av följande åtgärder:

  • Lägga till ett nytt visuellt objekt på arbetsytan
  • Konvertera ett visuellt objekt från ett objekt som inte stöder den här funktionen.

Om du till exempel konverterar en sourceVisual till targetVisual betraktas egenskapen targetVisualdisabledByDefault endast om sourceVisual inte stöder den här funktionen. Om sourceVisual stöder den här funktionen behåller targetVisual källanVisuals tillstånd och inte standardvärdet.

Lägga till stöd för ökad detaljnivå i en ny version av ett befintligt visuellt objekt

Att använda funktionen drilldown representerar en icke-bakåtkompatibel ändring. För den smidigaste övergången rekommenderar vi därför att du använder ett nytt visuellt GUID för den nya versionen.

Om du dock vill behålla samma GUID bör du tänka på följande:

  • När du migrerar från en icke-tillgänglig version till en ny drillable-version kanske vissa data inte tillhandahålls i dataView på grund av det hierarkiska datastöd som introducerades som en del av detaljgranskningsfunktionen. Funktionen för dynamisk detaljkontroll erbjuder inte automatiskt stöd för det här problemet, men kan användas för att hantera migreringsprocessen.

  • För självmigrering av det visuella objektet bör det visuella objektet vidta följande åtgärder:

    • Identifiera första gången den nya versionen läses in i stället för den äldre versionen och tillämpa API:et persistProperties .

    • Inaktivera detaljnivån för att ta emot alla data med hjälp av API:et setCanDrill .

I följande exempel visas hur du själv migrerar ett äldre visuellt objekt till ett som använder dynamisk detaljkontroll:

  1. Lägg till följande objekt i filen capabilities.json:

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

  2. Lägg till följande i filen 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);
      }
  }

Första gången det visuella objektet öppnas efter att den här koden har lagts till anges variabeln DrillMigration till true och det visuella objektet öppnas i standardtillståndet.

Beaktanden och begränsningar

  • Detaljgranskningstillståndet sparas inte när du har inaktiverat detaljnivån. Om du kan aktivera detaljnivån igen när du har inaktiverat den visas endast den första nivån oavsett vad som visades innan den inaktiverades.

  • Expandera/dölj-tillståndet sparas inte när du har inaktiverat detaljnivån. Alla rader komprimeras när detaljnivån kan återanvändas.

  • API-anropet stöds inte för instrumentpaneler.

  • Datavisningsmappningsvillkor: Använd "max": 1 för alla villkor för den drillbara rollen för att begränsa det visuella objektet till att endast visa ett fält när detaljnivån är inaktiverad. Till exempel:

    • För kategorisk datavy:

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

    • För matrisdatavy:

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