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