DataViewUtilsDataViewUtils

DataViewUtils es un conjunto de funciones y clases para simplificar el análisis del objeto DataView para objetos visuales de Power BIThe DataViewUtils is a set of functions and classes to simplify parsing of the DataView object for Power BI visuals

InstalaciónInstallation

Para instalar el paquete, debe ejecutar el comando siguiente en el directorio con el objeto visual personalizado actual:To install the package, you should run the following command in the directory with your current custom visual:

npm install powerbi-visuals-utils-dataviewutils --save Este comando instala el paquete y agrega un paquete como dependencia al archivo package.jsonnpm install powerbi-visuals-utils-dataviewutils --save This command installs the package and adds a package as a dependency to your package.json

DataViewWildcardDataViewWildcard

DataViewWildcard proporciona la función createDataViewWildcardSelector para admitir el formato condicional de una propiedad.DataViewWildcard provides the createDataViewWildcardSelector function to support a property's conditional formatting.

createDataViewWildcardSelector devuelve un selector necesario para definir cómo se aplicará la entrada de formato condicional en el panel de formato, según dataviewWildcardMatchingOption (InstancesAndTotals (default), InstancesOnly, TotalsOnly).createDataViewWildcardSelector returns a selector required for defining how the conditional formatting entry in the format pane will be applied, based on dataviewWildcardMatchingOption (InstancesAndTotals (default), InstancesOnly, TotalsOnly).

Ejemplo:Example:

import { dataViewWildcard } from "powerbi-visuals-utils-dataviewutils";

let selector = dataViewWildcard.createDataViewWildcardSelector(dataViewWildcard.DataViewWildcardMatchingOption.InstancesAndTotals);
// returns {data: [{dataViewWildcard:{matchingOption: 0}}]};

DataRoleHelperDataRoleHelper

DataRoleHelper proporciona funciones para comprobar los roles del objeto dataView.The DataRoleHelper provides functions to check roles of the dataView object.

El módulo proporciona las siguientes funciones:The module provides the following functions:

getMeasureIndexOfRolegetMeasureIndexOfRole

Esta función busca la medida por el nombre de rol y devuelve su índice.This function finds the measure by role name and returns its index.

function getMeasureIndexOfRole(grouped: DataViewValueColumnGroup[], roleName: string): number;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewValueColumnGroup = powerbi.DataViewValueColumnGroup;
import { dataRoleHelper } from "powerbi-visuals-utils-dataviewutils";
// ...

// This object is actually a part of the dataView object.
let columnGroup: DataViewValueColumnGroup[] = [{
    values: [
        {
            source: {
                displayName: "Microsoft",
                roles: {
                    "company": true
                }
            },
            values: []
        },
        {
            source: {
                displayName: "Power BI",
                roles: {
                    "product": true
                }
            },
            values: []
        }
    ]
}];

dataRoleHelper.getMeasureIndexOfRole(columnGroup, "product");

// returns: 1

getCategoryIndexOfRolegetCategoryIndexOfRole

Esta función busca la categoría por el nombre de rol y devuelve su índice.This function finds the category by role name and returns its index.

function getCategoryIndexOfRole(categories: DataViewCategoryColumn[], roleName: string): number;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewCategoryColumn = powerbi.DataViewCategoryColumn;
import { dataRoleHelper } from "powerbi-visuals-utils-dataviewutils";
// ...

// This object is actually a part of the dataView object.
let categoryGroup: DataViewCategoryColumn[] = [
    {
        source: {
            displayName: "Microsoft",
            roles: {
                "company": true
            }
        },
        values: []
    },
    {
        source: {
            displayName: "Power BI",
            roles: {
                "product": true
            }
        },
        values: []
    }
];

dataRoleHelper.getCategoryIndexOfRole(categoryGroup, "product");

// returns: 1

hasRolehasRole

Esta función comprueba si el rol proporcionado está definido en los metadatos.This function checks if the provided role is defined in the metadata.

function hasRole(column: DataViewMetadataColumn, name: string): boolean;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewMetadataColumn = powerbi.DataViewMetadataColumn;
import { dataRoleHelper } from "powerbi-visuals-utils-dataviewutils";

// This object is actually a part of the dataView object.
let metadata: DataViewMetadataColumn = {
    displayName: "Microsoft",
    roles: {
        "company": true
    }
};

DataRoleHelper.hasRole(metadata, "company");

// returns: true

hasRoleInDataViewhasRoleInDataView

Esta función comprueba si el rol proporcionado está definido en el objeto dataView.This function checks if the provided role is defined in the dataView.

function hasRoleInDataView(dataView: DataView, name: string): boolean;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataView = powerbi.DataView;
import { dataRoleHelper } from "powerbi-visuals-utils-dataviewutils";

// This object is actually a part of the dataView object.
let dataView: DataView = {
    metadata: {
        columns: [
            {
                displayName: "Microsoft",
                roles: {
                    "company": true
                }
            },
            {
                displayName: "Power BI",
                roles: {
                    "product": true
                }
            }
        ]
    }
};

DataRoleHelper.hasRoleInDataView(dataView, "product");

// returns: true

hasRoleInValueColumnhasRoleInValueColumn

Esta función comprueba si el rol proporcionado está definido en la columna de valor.This function checks if the provided role is defined in the value column.

function hasRoleInValueColumn(valueColumn: DataViewValueColumn, name: string): boolean;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewValueColumn = powerbi.DataViewValueColumn;
import { dataRoleHelper } from "powerbi-visuals-utils-dataviewutils";

// This object is actually a part of the dataView object.
let valueColumn: DataViewValueColumn = {
    source: {
        displayName: "Microsoft",
        roles: {
            "company": true
        }
    },
    values: []
};

dataRoleHelper.hasRoleInValueColumn(valueColumn, "company");

// returns: true

DataViewObjectsDataViewObjects

DataViewObjects proporciona funciones para extraer valores de los objetos.The DataViewObjects provides functions to extract values of the objects.

El módulo proporciona las siguientes funciones:The module provides the following functions:

getValuegetValue

Esta función devuelve el valor del objeto actual.This function returns the value of the given object.

function getValue<T>(objects: DataViewObjects, propertyId: DataViewObjectPropertyIdentifier, defaultValue?: T): T;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewObjectPropertyIdentifier = powerbi.DataViewObjectPropertyIdentifier;
import { dataViewObjects } from "powerbi-visuals-utils-dataviewutils";

let property: DataViewObjectPropertyIdentifier = {
    objectName: "microsoft",
    propertyName: "bi"
};

// This object is actually a part of the dataView object.
let objects: powerbi.DataViewObjects = {
    "microsoft": {
        "windows": 5,
        "bi": "Power"
    }
};

dataViewObjects.getValue(objects, property);

// returns: Power

getObjectgetObject

Esta función devuelve un objeto del objeto proporcionado.This function returns an object of the given object.

function getObject(objects: DataViewObjects, objectName: string, defaultValue?: IDataViewObject): IDataViewObject;

Ejemplo:Example:

import { dataViewObjects } from "powerbi-visuals-utils-dataviewutils";

// This object is actually a part of the dataView object.
let objects: powerbi.DataViewObjects = {
    "microsoft": {
        "windows": 5,
        "bi": "Power"
    }
};

dataViewObjects.getObject(objects, "microsoft");

/* returns: {
    "bi": "Power",
    "windows": 5

}*/

getFillColorgetFillColor

Esta función devuelve un color sólido de los objetos.This function returns a solid color of the objects.

function getFillColor(objects: DataViewObjects, propertyId: DataViewObjectPropertyIdentifier, defaultColor?: string): string;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewObjectPropertyIdentifier = powerbi.DataViewObjectPropertyIdentifier;
import { dataViewObjects } from "powerbi-visuals-utils-dataviewutils";

let property: DataViewObjectPropertyIdentifier = {
    objectName: "power",
    propertyName: "fillColor"
};

// This object is actually part of the dataView object.
let objects: powerbi.DataViewObjects = {
    "power": {
        "fillColor": {
            "solid": {
                "color": "yellow"
            }
        },
        "bi": "Power"
    }
};

dataViewObjects.getFillColor(objects, property);

// returns: yellow

getCommonValuegetCommonValue

Esta función es una función universal para recuperar el color o el valor de un objeto determinado.This function is a universal function for retrieving the color or value of a given object.

function getCommonValue(objects: DataViewObjects, propertyId: DataViewObjectPropertyIdentifier, defaultValue?: any): any;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewObjectPropertyIdentifier = powerbi.DataViewObjectPropertyIdentifier;
import { dataViewObjects } from "powerbi-visuals-utils-dataviewutils";

let colorProperty: DataViewObjectPropertyIdentifier = {
    objectName: "power",
    propertyName: "fillColor"
};

let biProperty: DataViewObjectPropertyIdentifier = {
    objectName: "power",
    propertyName: "bi"
};

// This object is actually part of the dataView object.
let objects: powerbi.DataViewObjects = {
    "power": {
        "fillColor": {
            "solid": {
                "color": "yellow"
            }
        },
        "bi": "Power"
    }
};

dataViewObjects.getCommonValue(objects, colorProperty); // returns: yellow
dataViewObjects.getCommonValue(objects, biProperty); // returns: Power

DataViewObjectDataViewObject

DataViewObject proporciona funciones para extraer valor del objeto.The DataViewObject provides functions to extract value of the object.

El módulo proporciona las siguientes funciones:The module provides the following functions:

getValuegetValue

Esta función devuelve un valor del objeto por nombre de propiedad.This function returns a value of the object by property name.

function getValue<T>(object: IDataViewObject, propertyName: string, defaultValue?: T): T;

Ejemplo:Example:

import { dataViewObject } from "powerbi-visuals-utils-dataviewutils";

// This object is actually a part of the dataView object.
let object: powerbi.DataViewObject = {
    "windows": 5,
    "microsoft": "Power BI"
};

dataViewObject.getValue(object, "microsoft");

// returns: Power BI

getFillColorByPropertyNamegetFillColorByPropertyName

Esta función devuelve un color sólido del objeto por nombre de propiedad.This function returns a solid color of the object by property name.

function getFillColorByPropertyName(object: IDataViewObject, propertyName: string, defaultColor?: string): string;

Ejemplo:Example:

import { dataViewObject } from "powerbi-visuals-utils-dataviewutils";

// This object is actually a part of the dataView object.
let object: powerbi.DataViewObject = {
    "windows": 5,
    "fillColor": {
        "solid": {
            "color": "green"
        }
    }
};

dataViewObject.getFillColorByPropertyName(object, "fillColor");

// returns: green

converterHelperconverterHelper

converterHelper proporciona funciones para comprobar las propiedades del objeto dataView.The converterHelper provides functions to check properties of the dataView.

El módulo proporciona las siguientes funciones:The module provides the following functions:

categoryIsAlsoSeriesRolecategoryIsAlsoSeriesRole

Esta función comprueba si la categoría también es una serie.This function checks if the category is also series.

function categoryIsAlsoSeriesRole(dataView: DataViewCategorical, seriesRoleName: string, categoryRoleName: string): boolean;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewCategorical = powerbi.DataViewCategorical;
import { converterHelper } from "powerbi-visuals-utils-dataviewutils";
// ...


// This object is actually part of the dataView object.
let categorical: DataViewCategorical = {
    categories: [{
        source: {
            displayName: "Microsoft",
            roles: {
                "power": true,
                "bi": true
            }
        },
        values: []
    }]
};

converterHelper.categoryIsAlsoSeriesRole(categorical, "power", "bi");

// returns: true

getSeriesNamegetSeriesName

Esta función devuelve un nombre de la serie.This function returns a name of the series.

function getSeriesName(source: DataViewMetadataColumn): PrimitiveValue;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewMetadataColumn = powerbi.DataViewMetadataColumn;
import { converterHelper } from "powerbi-visuals-utils-dataviewutils";

// This object is actually a part of the dataView object.
let metadata: DataViewMetadataColumn = {
    displayName: "Microsoft",
    roles: {
        "power": true,
        "bi": true
    },
    groupName: "Power BI"
};

converterHelper.getSeriesName(metadata);

// returns: Power BI

isImageUrlColumnisImageUrlColumn

Esta función comprueba si la columna contiene una dirección URL de imagen.This function checks if the column contains an image url.

function isImageUrlColumn(column: DataViewMetadataColumn): boolean;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewMetadataColumn = powerbi.DataViewMetadataColumn;
import { converterHelper } from "powerbi-visuals-utils-dataviewutils";

// This object is actually a part of the dataView object.
let metadata: DataViewMetadataColumn = {
    displayName: "Microsoft",
    type: {
        misc: {
            imageUrl: true
        }
    }
};

converterHelper.isImageUrlColumn(metadata);

// returns: true

isWebUrlColumnisWebUrlColumn

Esta función comprueba si la columna contiene una dirección URL web.This function checks if the column contains a web url.

function isWebUrlColumn(column: DataViewMetadataColumn): boolean;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import DataViewMetadataColumn = powerbi.DataViewMetadataColumn;
import { converterHelper } from "powerbi-visuals-utils-dataviewutils";

// This object is actually a part of the dataView object.
let metadata: DataViewMetadataColumn = {
    displayName: "Microsoft",
    type: {
        misc: {
            webUrl: true
        }
    }
};

converterHelper.isWebUrlColumn(metadata);

// returns: true

hasImageUrlColumnhasImageUrlColumn

Esta función comprueba si el objeto dataView tiene una columna con una dirección URL de imagen.This function checks if the dataView has a column with image url.

function hasImageUrlColumn(dataView: DataView): boolean;

Ejemplo:Example:

import DataView = powerbi.DataView;
import converterHelper = powerbi.extensibility.utils.dataview.converterHelper;

// This object is actually part of the dataView object.
let dataView: DataView = {
    metadata: {
        columns: [
            {
                displayName: "Microsoft"
            },
            {
                displayName: "Power BI",
                type: {
                    misc: {
                        imageUrl: true
                    }
                }
            }
        ]
    }
};

converterHelper.hasImageUrlColumn(dataView);

// returns: true

DataViewObjectsParserDataViewObjectsParser

DataViewObjectsParser proporciona la manera más sencilla de analizar propiedades del panel de formato.The DataViewObjectsParser provides the simplest way to parse properties of the formatting panel.

La clase proporciona los métodos siguientes:The class provides the following methods:

getDefaultgetDefault

Este método estático devuelve una instancia de DataViewObjectsParser.This static method returns an instance of DataViewObjectsParser.

static getDefault(): DataViewObjectsParser;

Ejemplo:Example:

import { dataViewObjectsParser } from "powerbi-visuals-utils-dataviewutils";
// ...

dataViewObjectsParser.getDefault();

// returns: an instance of the DataViewObjectsParser

parseparse

Este método analiza las propiedades del panel de formato y devuelve una instancia de DataViewObjectsParser.This method parses properties of the formatting panel and returns an instance of DataViewObjectsParser.

static parse<T extends DataViewObjectsParser>(dataView: DataView): T;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import IVisual = powerbi.extensibility.IVisual;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import { dataViewObjectsParser } from "powerbi-visuals-utils-dataviewutils";

/**
 * This class describes formatting panel properties.
 * Name of the property should match its name described in the capabilities.
 */
class DataPointProperties {
    public fillColor: string = "red"; // This value is a default value of the property.
}

class PropertiesParser extends dataViewObjectsParser.DataViewObjectsParser {
    /**
     * This property describes a group of properties.
     */
    public dataPoint: DataPointProperties = new DataPointProperties();
}

export class YourVisual extends IVisual {
    // implementation of the IVisual.

    private propertiesParser: PropertiesParser;

    public update(options: VisualUpdateOptions): void {
        // Parses properties.
        this.propertiesParser = PropertiesParser.parse<PropertiesParser>(options.dataViews[0]);

        // You can use the properties after parsing
        console.log(this.propertiesParser.dataPoint.fillColor); // returns "red" as default value, it will be updated automatically after any change of the formatting panel.
    }
}

enumerateObjectInstancesenumerateObjectInstances

Este método estático enumera las propiedades y devuelve una instancia de VisualObjectInstanceEnumeration.This static method enumerates properties and returns an instance of VisualObjectInstanceEnumeration.

Ejecútelo en el método enumerateObjectInstances del objeto visual.Execute it in enumerateObjectInstances method of the visual.

static enumerateObjectInstances(dataViewObjectParser: dataViewObjectsParser.DataViewObjectsParser, options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration;

Ejemplo:Example:

import powerbi from "powerbi-visuals-api";
import IVisual = powerbi.extensibility.IVisual;
import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
import VisualObjectInstanceEnumeration = powerbi.VisualObjectInstanceEnumeration;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import { dataViewObjectsParser } from "powerbi-visuals-utils-dataviewutils";

/**
 * This class describes formatting panel properties.
 * Name of the property should match its name described in the capabilities.
 */
class DataPointProperties {
    public fillColor: string = "red";
}

class PropertiesParser extends dataViewObjectsParser.DataViewObjectsParser {
    /**
     * This property describes a group of properties.
     */
    public dataPoint: DataPointProperties = new DataPointProperties();
}

export class YourVisual extends IVisual {
    // implementation of the IVisual.

    private propertiesParser: PropertiesParser;

    public update(options: VisualUpdateOptions): void {
        // Parses properties.
        this.propertiesParser = PropertiesParser.parse<PropertiesParser>(options.dataViews[0]);
    }

    /**
     * This method will be executed only if the formatting panel is open.
     */
    public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
        return PropertiesParser.enumerateObjectInstances(this.propertiesParser, options);
    }
}