Поделиться через

Динамический элемент управления детализации

  • Статья

Примечание.

Эта функция доступна в API версии 5.7.0.

Функция динамической детализации позволяет визуальному элементу включить или отключить функцию детализации динамически с помощью вызова API. Если функция детализации включена, все функции детализации и расширения и свертывание доступны, включая вызовы API, команды контекстного меню, кнопки детализации заголовка и поддержку данных иерархии. Если эти функции отключены, эти функции недоступны.

На следующих изображениях показан пример визуального элемента с включенным и отключенным функцией динамического элемента управления детализацией:

Функция динамического элемента управления детализацией включает следующие элементы API:

  • Флаг isDrillDisabled в :DataRolesInfo

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

  • Метод setCanDrill в интерфейсе IVisualHost :

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

Чтобы определить, отключена ли детализация, используйте isDrillDisabled свойство в методе обновления:

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

Затем используйте вызов API, чтобы включить или отключить детализацию по мере необходимости:

  • Чтобы включить: this.host.setCanDrill(true /* drillAllowed */);

  • Чтобы отключить: this.host.setCanDrill(false /* drillAllowed */);

Требования к динамической детализации

Детализация включена по умолчанию, но функция динамического элемента управления детализацией позволяет визуальному элементу включить или отключить бурение с помощью вызова API.

Визуальный элемент с функцией динамической детализации содержит следующий код в файле capabilities.json :

  • Если детализация отключена по умолчанию:

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

  • С включенной детализацией по умолчанию:

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

Свойство canDisableDrill указывает, что визуальный элемент поддерживает эту функцию. Без этого свойства вызов API не учитывается.
Свойство disabledByDefault указывает, следует ли отключить функцию детализации по умолчанию.

Примечание.

Свойство disabledByDefault вступает в силу при выполнении одного из следующих действий:

  • Добавление нового визуального элемента на холст
  • Преобразуйте визуальный элемент из одного, который не поддерживает эту функцию.

Например, при преобразовании sourceVisual в targetVisual свойство targetVisual disabledByDefaultсчитается только в том случае, если источник Не поддерживает эту функцию. Если sourceVisual поддерживает эту функцию, targetVisual сохраняет состояние источника и не по умолчанию.

Добавление поддержки детализации в новую версию существующего визуального элемента

Использование функции детализации представляет критическое изменение. Поэтому для наиболее плавного перехода рекомендуется использовать новый визуальный GUID для новой версии.

Однако если вы хотите сохранить один и тот же GUID, имейте в виду следующие моменты:

  • При миграции из неоплаченной версии в новую детализацию некоторые данные могут не предоставляться из-за поддержки иерархических данных, представленной в dataView рамках функции детализации. Функция динамической детализации не предоставляет автоматическую поддержку этой проблемы, но может использоваться для управления процессом миграции.

  • Для самостоятельной миграции визуального элемента визуальный элемент должен выполнить следующие действия:

    • Определите первый раз, когда новая версия загружается вместо старой версии, и примените persistProperties API.

    • Отключите детализацию для получения всех данных с помощью setCanDrill API.

В следующем примере показано, как самостоятельно перенести старый визуальный элемент в один, использующий динамический элемент управления детализацией:

  1. Добавьте следующий объект в файл capabilities.json:

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

  2. Добавьте следующее в файл 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);
      }
  }

При первом открытии визуального элемента после добавления этого кода переменная DrillMigration имеет значение true, а визуальный элемент открывается в состоянии по умолчанию.

Рекомендации и ограничения

  • Состояние детализации не сохраняется после отключения детализации. Если вы повторно создайте детализацию после отключения, отображается только первый уровень независимо от того, что отображалось до его отключения.

  • Состояние развертывания и свертывания не сохраняется после отключения детализации. Все строки свернуты после повторной детализации.

  • Вызов API не поддерживается для панелей мониторинга.

  • Условия сопоставления представлений данных: используйте "max": 1 для всех условий для детализации роли, чтобы ограничить визуальный элемент только одним полем при отключении детализации. Например:

    • Для представления категориальных данных:

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

    • Для представления данных матрицы:

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