Dynamisch besturingselement voor zoomen

Notitie

Deze functie is beschikbaar via API-versie 5.7.0.

Met de functie dynamisch zoombeheer kan de visual de drillfunctie dynamisch in- of uitschakelen met behulp van een API-aanroep. Wanneer de analysefunctie is ingeschakeld, zijn alle functies voor inzoomen en uitvouwen /samenvouwen beschikbaar, waaronder API-aanroepen, contextmenuopdrachten, knoppen voor koptekstanalyse en ondersteuning voor hiërarchiegegevens. Wanneer deze functies zijn uitgeschakeld, zijn deze functies niet beschikbaar.

In de volgende afbeeldingen ziet u een voorbeeld van een visual met de functie voor dynamisch inzoomen ingeschakeld en uitgeschakeld:

Inzoomen ingeschakeld

Inzoomen uitgeschakeld

De functie voor dynamisch zoombeheer bevat de volgende API-elementen:

• De isDrillDisabled vlag in het DataRolesInfo:

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

• De setCanDrill methode in de IVisualHost interface:

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

Als u wilt bepalen of de analyse is uitgeschakeld, gebruikt u de isDrillDisabled eigenschap in de updatemethode:

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

Gebruik vervolgens de API-aanroep om de analyse indien nodig in of uit te schakelen:

• Ga als volgende te werk om het volgende in te schakelen this.host.setCanDrill(true /* drillAllowed */);

• Als u het volgende wilt uitschakelen: this.host.setCanDrill(false /* drillAllowed */);

Vereisten voor dynamisch analysebeheer

Boren is standaard ingeschakeld, maar met de functie voor dynamisch zoomen kan de visual boren in- of uitschakelen met behulp van een API-aanroep.

Een visual met de functie voor dynamisch inzoomen heeft de volgende code in het bestand capabilities.json :

• Met inzoomen is standaard uitgeschakeld:

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

• Met drill is standaard ingeschakeld:

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

De canDisableDrill eigenschap geeft aan dat de visual deze functie ondersteunt. Zonder deze eigenschap wordt de API-aanroep niet gerespecteerd.
De disabledByDefault eigenschap geeft aan of de analysefunctie standaard moet worden uitgeschakeld.

Notitie

De disabledByDefault eigenschap wordt van kracht wanneer u een van de volgende acties uitvoert:

• Een nieuwe visual toevoegen aan het canvas
• Converteer een visual van een visual die deze functie niet ondersteunt.

Als u bijvoorbeeld een sourceVisual converteert naar targetVisual, wordt de eigenschap targetVisualdisabledByDefault alleen beschouwd als de sourceVisual deze functie niet ondersteunt. Als sourceVisual deze functie ondersteunt, behoudt targetVisual de status van sourceVisual en niet de standaardinstelling.

Inzoomondersteuning toevoegen aan een nieuwe versie van een bestaande visual

Het gebruik van de drilldownfunctie vertegenwoordigt een belangrijke wijziging. Daarom raden we u aan voor de soepelste overgang een nieuwe visuele GUID te gebruiken voor de nieuwe versie.

Als u echter dezelfde GUID wilt behouden, moet u rekening houden met de volgende punten:

• Wanneer u migreert van een niet-rille versie naar een nieuwe drillable versie, worden sommige gegevens mogelijk niet opgegeven in het dataView gevolg van de hiërarchische gegevensondersteuning die is geïntroduceerd als onderdeel van de analysefunctie. De functie voor dynamisch analysebeheer biedt geen automatische ondersteuning voor dit probleem, maar kan worden gebruikt om het migratieproces te beheren.

• Voor zelfmigratie van de visual moet de visual de volgende acties uitvoeren:

  • Identificeer de eerste keer dat de nieuwe versie wordt geladen in plaats van de oudere versie en pas de persistProperties API toe.

  • Schakel de analyse uit om alle gegevens te ontvangen met behulp van de setCanDrill API.

In het volgende voorbeeld ziet u hoe u een oudere visual zelf migreert naar een visual die gebruikmaakt van dynamisch zoombesturingselement:

1. Voeg het volgende object toe aan het bestand capabilities.json:

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

2. Voeg het volgende toe aan het bestand 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);
         }
     }
   

De eerste keer dat de visual wordt geopend nadat u deze code hebt toegevoegd, is de DrillMigration-variabele ingesteld op true en wordt de visual geopend met de standaardstatus.

Overwegingen en beperkingen

• De analysestatus wordt niet opgeslagen nadat u de analyse hebt uitgeschakeld. Als u de analyse opnieuw kunt in- en uitschakelen nadat u deze hebt uitgeschakeld, wordt alleen het eerste niveau weergegeven, ongeacht wat er is weergegeven voordat deze werd uitgeschakeld.

• De uitvouw-/samenvouwen status wordt niet opgeslagen na het uitschakelen van de analyse. Alle rijen worden samengevouwen zodra de analyse opnieuw kan worden uitgevoerd.

• De API-aanroep wordt niet ondersteund voor dashboards.

• Toewijzingsvoorwaarden voor gegevensweergave: gebruik "max": 1 deze optie voor alle voorwaarden voor de drillable-rol om de visual te beperken tot slechts één veld wanneer inzoomen is uitgeschakeld. Voorbeeld:

  • Voor categorische gegevensweergave:

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

  • Voor matrixgegevensweergave:

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