Udostępnij za pośrednictwem

Dynamiczna kontrolka przechodzenia do szczegółów

  • Artykuł

Uwaga

Ta funkcja jest dostępna w wersji 5.7.0 interfejsu API.

Funkcja dynamicznej kontroli przechodzenia do szczegółów umożliwia wizualizacji dynamiczne włączanie lub wyłączanie funkcji przechodzenia do szczegółów przy użyciu wywołania interfejsu API. Po włączeniu funkcji przechodzenia do szczegółów dostępne są wszystkie funkcje przechodzenia do szczegółów i funkcje rozwijania/zwijania , w tym wywołania interfejsu API, polecenia menu kontekstowego, przyciski przechodzenia do szczegółów nagłówka i obsługa danych hierarchii. Po wyłączeniu te funkcje nie są dostępne.

Na poniższych obrazach przedstawiono przykład wizualizacji z włączoną i wyłączoną funkcją dynamicznej kontrolki przechodzenia do szczegółów:

Funkcja dynamicznego sterowania przechodzeniem do szczegółów obejmuje następujące elementy interfejsu API:

  • Flaga isDrillDisabled w elemecie DataRolesInfo:

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

  • Metoda setCanDrill w interfejsie IVisualHost :

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

Aby określić, czy przechodzenie do szczegółów jest wyłączone, użyj isDrillDisabled właściwości w metodzie update:

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

Następnie użyj wywołania interfejsu API, aby włączyć lub wyłączyć przechodzenie do szczegółów zgodnie z potrzebami:

  • Aby włączyć: this.host.setCanDrill(true /* drillAllowed */);

  • Aby wyłączyć: this.host.setCanDrill(false /* drillAllowed */);

Wymagania dotyczące dynamicznej kontroli przechodzenia do szczegółów

Przechodzenie do szczegółów jest domyślnie włączone, ale funkcja dynamicznego sterowania przechodzeniem do szczegółów umożliwia wizualizacji włączanie lub wyłączanie przechodzenia do szczegółów przy użyciu wywołania interfejsu API.

Wizualizacja z funkcją dynamicznego sterowania przechodzeniem do szczegółów zawiera następujący kod w pliku capabilities.json :

  • Po wyłączeniu przechodzenia do szczegółów domyślnie:

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

  • Po włączeniu przechodzenia do szczegółów domyślnie:

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

Właściwość wskazuje, że wizualizacja canDisableDrill obsługuje tę funkcję. Bez tej właściwości wywołanie interfejsu API nie jest przestrzegane.
Właściwość disabledByDefault wskazuje, czy domyślnie wyłączyć funkcję przeglądania szczegółowego.

Uwaga

Właściwość disabledByDefault ma zastosowanie podczas wykonywania jednej z następujących akcji:

  • Dodawanie nowej wizualizacji do kanwy
  • Przekonwertuj wizualizację na wizualizację, która nie obsługuje tej funkcji.

Jeśli na przykład przekonwertujesz element sourceVisual na targetVisual, właściwość targetVisualdisabledByDefault jest traktowana tylko wtedy, gdy źródłoVisual nie obsługuje tej funkcji. Jeśli funkcja sourceVisual obsługuje tę funkcję, element targetVisual zachowuje stan sourceVisual, a nie domyślny.

Dodawanie obsługi przechodzenia do szczegółów do nowej wersji istniejącej wizualizacji

Użycie funkcji przechodzenia do szczegółów reprezentuje zmianę powodującą niezgodność. W związku z tym w przypadku najładniejszego przejścia zalecamy użycie nowego graficznego identyfikatora GUID dla nowej wersji.

Jeśli jednak chcesz zachować ten sam identyfikator GUID, pamiętaj o następujących kwestiach:

  • W przypadku migracji z wersji niezwiązanej z możliwością przechodzenia do nowej wersji z możliwością przechodzenia do szczegółów niektóre dane mogą nie być udostępniane ze dataView względu na obsługę danych hierarchicznych wprowadzonych w ramach funkcji przechodzenia do szczegółów. Funkcja dynamicznej kontroli przechodzenia do szczegółów nie oferuje automatycznej obsługi tego problemu, ale może służyć do zarządzania procesem migracji.

  • W przypadku samodzielnej migracji wizualizacji wizualizacja powinna wykonać następujące czynności:

    • Zidentyfikuj pierwszy raz, gdy nowa wersja zostanie załadowana zamiast starszej wersji, i zastosuj persistProperties interfejs API.

    • Wyłącz przechodzenie do szczegółów, aby odbierać wszystkie dane przy użyciu interfejsu setCanDrill API.

W poniższym przykładzie pokazano, jak samodzielnie migrować starszą wizualizację do wizualizacji korzystającej z dynamicznej kontrolki przechodzenia do szczegółów:

  1. Dodaj następujący obiekt do pliku capabilities.json:

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

  2. Dodaj następujący kod do pliku 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);
      }
  }

Po pierwszym otwarciu wizualizacji po dodaniu tego kodu zmienna DrillMigration jest ustawiona na wartość true, a wizualizacja zostanie otwarta w stanie domyślnym.

Rozważania i ograniczenia

  • Stan przechodzenia do szczegółów nie jest zapisywany po wyłączeniu przechodzenia do szczegółów. Jeśli po jego wyłączeniu można ponownie przejść do szczegółów, wyświetlany jest tylko pierwszy poziom niezależnie od tego, co było wyświetlane przed jego wyłączeniem.

  • Stan rozwijania/zwijania nie jest zapisywany po wyłączeniu przechodzenia do szczegółów. Wszystkie wiersze są zwinięte po ponownym uruchomieniu przechodzenia do szczegółów.

  • Wywołanie interfejsu API nie jest obsługiwane w przypadku pulpitów nawigacyjnych.

  • Warunki mapowania widoku danych: użyj "max": 1 dla wszystkich warunków roli z możliwością przechodzenia do szczegółów, aby ograniczyć wizualizację do wyświetlania tylko jednego pola po wyłączeniu przechodzenia do szczegółów. Na przykład:

    • W przypadku widoku danych kategorii:

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

    • W przypadku widoku danych macierzy:

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