DataViewUtils

Dit DataViewUtils is een set functies en klassen om het parseren van het DataView-object voor Power BI-visuals te vereenvoudigen.

Installatie

Als u het pakket wilt installeren, voert u de volgende opdracht uit in de map met uw huidige aangepaste visual:

npm install powerbi-visuals-utils-dataviewutils --save

Met deze opdracht wordt het pakket geïnstalleerd en wordt een pakket als een afhankelijkheid aan uw package.json bestand toegevoegd.

DataViewWildcard

DataViewWildcardbiedt de functie ter ondersteuning van de createDataViewWildcardSelector voorwaardelijke opmaak van een eigenschap.

createDataViewWildcardSelector retourneert een selector die is vereist voor het definiëren van hoe de vermelding voor voorwaardelijke opmaak in het opmaakvenster wordt toegepast, op dataviewWildcardMatchingOption (InstancesAndTotals (default), InstancesOnly, TotalsOnly)basis van .

Voorbeeld:

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

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

DataRoleHelper

De DataRoleHelper functie bevat functies om de rollen van het dataView-object te controleren.

De module biedt de volgende functies:

getMeasureIndexOfRole

Deze functie vindt de meting op basis van de rolnaam en retourneert de index.

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

Voorbeeld:

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

getCategoryIndexOfRole

Deze functie zoekt de categorie op basis van de rolnaam en retourneert de index.

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

Voorbeeld:

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

hasRole

Met deze functie wordt gecontroleerd of de opgegeven rol is gedefinieerd in de metagegevens.

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

Voorbeeld:

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

hasRoleInDataView

Met deze functie wordt gecontroleerd of de opgegeven rol is gedefinieerd in de dataView.

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

Voorbeeld:

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

hasRoleInValueColumn

Met deze functie wordt gecontroleerd of de opgegeven rol is gedefinieerd in de waardekolom.

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

Voorbeeld:

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

DataViewObjects

De DataViewObjects functie biedt functies voor het extraheren van de waarden van de objecten.

De module biedt de volgende functies:

getValue

Deze functie retourneert de waarde van het specifieke object.

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

Voorbeeld:

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

getObject

Deze functie retourneert een object van opgegeven objecten.

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

Voorbeeld:

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

}*/

getFillColor

Deze functie retourneert een effen kleur van de objecten.

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

Voorbeeld:

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

getCommonValue

Met deze universele functie wordt de kleur of waarde van een specifiek object opgehaald.

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

Voorbeeld:

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

DataViewObject

De DataViewObject functie biedt functies om de waarde van het object te extraheren.

De module biedt de volgende functies:

getValue

Deze functie retourneert een waarde van het object op basis van de eigenschapsnaam.

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

Voorbeeld:

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

getFillColorByPropertyName

Deze functie retourneert een effen kleur van het object op basis van de naam van de eigenschap.

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

Voorbeeld:

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

converterHelper

De converterHelper functie bevat functies om de eigenschappen van de dataView te controleren.

De module biedt de volgende functies:

categoryIsAlsoSeriesRole

Met deze functie wordt gecontroleerd of de categorie ook een reeks is.

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

Voorbeeld:

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

getSeriesName

Deze functie retourneert een naam van de reeks.

function getSeriesName(source: DataViewMetadataColumn): PrimitiveValue;

Voorbeeld:

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

isImageUrlColumn

Met deze functie wordt gecontroleerd of de kolom een afbeeldings-URL bevat.

function isImageUrlColumn(column: DataViewMetadataColumn): boolean;

Voorbeeld:

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

isWebUrlColumn

Met deze functie wordt gecontroleerd of de kolom een web-URL bevat.

function isWebUrlColumn(column: DataViewMetadataColumn): boolean;

Voorbeeld:

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

hasImageUrlColumn

Met deze functie wordt gecontroleerd of de dataView een kolom met een afbeeldings-URL heeft.

function hasImageUrlColumn(dataView: DataView): boolean;

Voorbeeld:

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

DataViewObjectsParser

Het DataViewObjectsParser biedt de eenvoudigste manier om de eigenschappen van het opmaakvenster te parseren.

De klasse biedt de volgende methoden:

getDefault

Deze statische methode retourneert een exemplaar van DataViewObjectsParser.

static getDefault(): DataViewObjectsParser;

Voorbeeld:

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

dataViewObjectsParser.getDefault();

// returns: an instance of the DataViewObjectsParser

parseren

Deze methode parseert de eigenschappen van het opmaakvenster en retourneert een exemplaar van DataViewObjectsParser.

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

Voorbeeld:

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.
    }
}

enumerateObjectInstances

Belangrijk

enumerateObjectInstances is afgeschaft in API-versie 5.1. Het is vervangen door getFormattingModel. Zie ook De hulpprogramma's FormatModel.

Deze statische methode inventariseert eigenschappen en retourneert een exemplaar van VisualObjectInstanceEnumeration.

Voer deze uit in de enumerateObjectInstances methode van de visual.

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

Voorbeeld:

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