Dynamické řízení přechodu k podrobnostem

  • Článek

Poznámka:

Tato funkce je dostupná z rozhraní API verze 5.7.0.

Funkce dynamického řízení podrobností umožňuje vizuálu dynamicky povolit nebo zakázat funkci přechodu k podrobnostem pomocí volání rozhraní API. Když je funkce přechodu k podrobnostem povolená, jsou k dispozici všechny funkce přechodu k podrobnostem a rozbalení/sbalení , včetně volání rozhraní API, příkazů kontextové nabídky, tlačítek pro přechod k podrobnostem záhlaví a podpory pro data hierarchie. Pokud jsou zakázané, tyto funkce nejsou k dispozici.

Následující obrázky ukazují příklad vizuálu s povolenou a zakázanou funkcí dynamického řízení přechodu k podrobnostem:

Funkce dynamického řízení přechodu k podrobnostem obsahuje následující prvky rozhraní API:

  • Příznak isDrillDisabled v :DataRolesInfo

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

  • Metoda setCanDrill v IVisualHost rozhraní:

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

Pokud chcete zjistit, jestli je postup zakázán, použijte isDrillDisabled vlastnost v metodě aktualizace:

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

Pak pomocí volání rozhraní API podle potřeby povolte nebo zakažte přechod k podrobnostem:

  • Povolení: this.host.setCanDrill(true /* drillAllowed */);

  • Zakázání: this.host.setCanDrill(false /* drillAllowed */);

Požadavky na dynamické řízení přechodu k podrobnostem

Procházení je ve výchozím nastavení povolené, ale funkce dynamického řízení přechodu k podrobnostem umožňuje vizuálu povolit nebo zakázat procházení pomocí volání rozhraní API.

Vizuál s funkcí dynamického řízení přechodu k podrobnostem má v souboru capabilities.json následující kód:

  • Když je přechod k podrobnostem ve výchozím nastavení zakázaný:

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

  • S povoleným přechodem k podrobnostem ve výchozím nastavení:

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

Vlastnost canDisableDrill označuje, že vizuál tuto funkci podporuje. Bez této vlastnosti se volání rozhraní API nerespektuje.
Tato disabledByDefault vlastnost určuje, zda má být funkce přechodu k podrobnostem ve výchozím nastavení zakázána.

Poznámka:

Vlastnost disabledByDefault se projeví, když provedete jednu z následujících akcí:

  • Přidání nového vizuálu na plátno
  • Převeďte vizuál z vizuálu, který tuto funkci nepodporuje.

Pokud například převedete sourceVisual na targetVisual, vlastnost targetVisual disabledByDefaultse považuje pouze v případě, že sourceVisual tuto funkci nepodporuje. Pokud sourceVisual tuto funkci podporuje, cílovávisual zachová stav sourceVisual, nikoli výchozí.

Přidání podpory přechodu k podrobnostem do nové verze existujícího vizuálu

Použití funkce přechodu k podrobnostem představuje zásadní změnu. Proto pro nejhladší přechod doporučujeme pro novou verzi použít nový identifikátor GUID vizuálu.

Pokud ale chcete zachovat stejný identifikátor GUID, mějte na paměti následující body:

  • Když migrujete z neořízitelné verze na novou verzi s možností přechodu k podrobnostem, nemusí být některá data v dataView důsledku podpory hierarchických dat zavedená jako součást funkce přechodu k podrobnostem. Funkce dynamického řízení přechodu k podrobnostem nenabízí automatickou podporu pro tento problém, ale dá se použít ke správě procesu migrace.

  • Při samoobslužné migraci vizuálu by měl vizuál provést následující akce:

    • Zjistěte, kdy se nová verze načte poprvé místo starší verze, a použijte persistProperties rozhraní API.

    • Zakažte procházení k příjmu všech dat pomocí setCanDrill rozhraní API.

Následující příklad ukazuje, jak migrovat starší vizuál do vizuálu, který používá dynamické řízení přechodu k podrobnostem:

  1. Do souboru capabilities.json přidejte následující objekt:

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

  2. Do souboru visual.ts přidejte následující kód:

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

Při prvním otevření vizuálu po přidání tohoto kódu se proměnná DrillMigration nastaví na true a vizuál se otevře ve výchozím stavu.

Úvahy a omezení

  • Po zakázání přechodu k podrobnostem se stav přechodu k podrobnostem neuloží. Pokud můžete přechod k podrobnostem po zakázání znovu povolit, zobrazí se pouze první úroveň bez ohledu na to, co se zobrazilo předtím, než byla zakázána.

  • Po zakázání přechodu k podrobnostem se stav rozbalení nebo sbalení neuloží. Po opětovném povolení přechodu k podrobnostem jsou všechny řádky sbalené.

  • Volání rozhraní API není podporováno pro řídicí panely.

  • Podmínky mapování zobrazení dat: Slouží "max": 1 pro všechny podmínky pro roli s možností přechodu k podrobnostem, aby vizuál omezil na zobrazení pouze jednoho pole při zakázání přechodu k podrobnostem. Příklad:

    • Zobrazení dat kategorií:

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

    • Zobrazení maticových dat:

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