Share via

Control de obtención de detalles dinámicos

  • Artículo

Nota:

Esta característica está disponible a partir de la versión 5.7.0 de la API.

La característica de control de obtención de detalles dinámicos permite que el objeto visual habilite o deshabilite la característica de obtención de detalles dinámicamente mediante una llamada API. Cuando se habilita la característica de obtención de detalles, están disponibles todas las funcionalidades de exploración en profundidad y todas las características de expansión y contracción, incluidas las llamadas API, los comandos de menú contextual, los botones de obtención de detalles de encabezado y la compatibilidad con datos de jerarquías. Cuando está deshabilitada, estas funcionalidades no están disponibles.

En las imágenes siguientes se muestra un ejemplo de un objeto visual con la característica de control de obtención de detalles dinámico habilitada y deshabilitada:

La característica de control de obtención de detalles dinámicos incluye los siguientes elementos de API:

  • La marca isDrillDisabled en DataRolesInfo:

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

  • El método setCanDrill en la interfaz IVisualHost:

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

Para identificar si la obtención de detalles está deshabilitada, use la propiedad isDrillDisabled en el método de actualización:

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

A continuación, use la llamada API para habilitar o deshabilitar la obtención de detalles según sea necesario:

  • Para habilitarla: this.host.setCanDrill(true /* drillAllowed */);

  • Para deshabilitarla: this.host.setCanDrill(false /* drillAllowed */);

Requisitos del control de obtención de detalles dinámicos

La obtención de detalles está habilitada de forma predeterminada, pero la característica de control de obtención de detalles dinámicos permite que el objeto visual habilite o deshabilite la obtención de detalles mediante una llamada API.

Un objeto visual que tiene la característica de control de obtención de detalles dinámicos tiene el código siguiente en el archivo capabilities.json:

  • Con la obtención de detalles deshabilitada de forma predeterminada:

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

  • Con la obtención de detalles habilitada de forma predeterminada:

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

La propiedad canDisableDrill indica que el objeto visual admite esta característica. Sin esta propiedad, no se respeta la llamada API.
La propiedad disabledByDefault indica si se va a deshabilitar o no la característica de obtención de detalles de forma predeterminada.

Nota:

La propiedad disabledByDefault surte efecto cuando se lleva a cabo una de las siguientes acciones:

  • Agregar un nuevo objeto visual al lienzo
  • Convertir un objeto visual a partir de uno que no admita esta característica.

Por ejemplo, si convierte un sourceVisual en un targetVisual, la propiedad disabledByDefault de targetVisual solo se tendrá en cuenta si sourceVisual no admite esta característica. Si sourceVisual admite esta característica, targetVisual mantiene el estado de sourceVisual en lugar del valor predeterminado.

Cómo agregar compatibilidad con exploración en profundidad a una nueva versión de un objeto visual existente

El uso de la característica de exploración en profundidad representa un cambio importante. Por lo tanto, para que la transición sea más fluida, se recomienda usar un nuevo GUID de objeto visual para la nueva versión.

Sin embargo, si desea mantener el mismo GUID, debe tener en cuenta los siguientes puntos:

  • Cuando se migra de una versión que no tiene capacidad de obtención de detalles a una que sí tiene, es posible que algunos datos no se proporcionen en dataView debido a la compatibilidad jerárquica con los datos que se ha introducido como parte de la característica de obtención de detalles. La característica de control de obtención de detalles dinámicos no ofrece compatibilidad automática con respecto a este problema, pero se puede usar para administrar el proceso de migración.

  • Para la migración automática del objeto visual, se deben realizar en él las siguientes acciones:

    • Identifique la primera vez que se carga la nueva versión en lugar de la versión anterior y aplique la API persistProperties.

    • Deshabilite la obtención de detalles para recibir todos los datos mediante la API setCanDrill.

En el ejemplo siguiente se muestra cómo migrar automáticamente un objeto visual antiguo a uno que usa el control de obtención de detalles dinámicos:

  1. Agregue el siguiente objeto al archivo capabilities.json:

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

  2. Agregue esto al archivo 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);
      }
  }

La primera vez que se abra el objeto visual después de agregar este código, la variable DrillMigration se establecerá en true y el objeto visual se abrirá en el estado predeterminado.

Consideraciones y limitaciones

  • El estado de obtención de detalles no se guarda después de deshabilitar la obtención de detalles. Si vuelve a habilitar la exploración después de deshabilitarla, solo se mostrará el primer nivel, independientemente de lo que se haya mostrado antes de que se deshabilitara.

  • El estado de expansión/contracción no se guarda después de deshabilitar la obtención de detalles. Todas las filas se contraen una vez que se vuelve a habilitar la obtención de detalles.

  • La llamada API no se admite para los paneles.

  • Condiciones de asignación de vistas de datos: use "max": 1 para todas las condiciones del rol de obtención de detalles para limitar el objeto visual para que solo muestre un campo cuando la obtención de detalles esté deshabilitada. Por ejemplo:

    • Para la vista de datos categóricos:

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

    • Para la vista de datos de matriz:

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