DataViewUtils

아티클
01/13/2024

DataViewUtils는 Power BI 시각적 개체의 DataView 개체 구문 분석을 간소화하는 함수 및 클래스 세트입니다.

설치

패키지를 설치하려면 현재 사용자 지정 시각적 개체가 있는 디렉터리에서 다음 명령을 실행합니다.

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

이 명령은 패키지를 설치하고 package.json 파일에 대한 종속성으로 패키지를 추가합니다.

DataViewWildcard

DataViewWildcard는 속성의 createDataViewWildcardSelector을 지원하는 함수를 제공합니다.

createDataViewWildcardSelector는 dataviewWildcardMatchingOption (InstancesAndTotals (default), InstancesOnly, TotalsOnly)에 따라 서식 창의 조건부 서식 지정 항목이 적용되는 방법을 정의하는 데 필요한 선택기를 반환합니다.

예시:

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

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

DataRoleHelper

DataRoleHelper는 dataView 개체의 역할을 확인하는 함수를 제공합니다.

이 모듈은 다음과 같은 함수를 제공합니다.

getMeasureIndexOfRole

이 함수는 역할 이름으로 측정값을 찾은 다음, 해당 인덱스를 반환합니다.

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

예시:

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

이 함수는 역할 이름으로 카테고리를 찾은 다음, 해당 인덱스를 반환합니다.

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

예시:

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

이 함수는 제공된 역할이 메타데이터에 정의되어 있는지 확인합니다.

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

예시:

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

이 함수는 제공된 역할이 dataView에 정의되어 있는지 확인합니다.

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

예시:

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

이 함수는 제공된 역할이 값 열에 정의되어 있는지 확인합니다.

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

예시:

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

DataViewObjects는 개체의 값을 추출하는 함수를 제공합니다.

이 모듈은 다음과 같은 함수를 제공합니다.

getValue

이 함수는 특정 개체의 값을 반환합니다.

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

예시:

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

이 함수는 지정된 개체에서 개체를 반환합니다.

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

예시:

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

이 함수는 개체의 단색을 반환합니다.

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

예시:

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

이 범용 함수는 특정 개체의 색이나 값을 가져옵니다.

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

예시:

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

DataViewObject는 개체의 값을 추출하는 함수를 제공합니다.

이 모듈은 다음과 같은 함수를 제공합니다.

getValue

이 함수는 개체의 값을 속성 이름으로 반환합니다.

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

예시:

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

이 함수는 개체의 단색을 속성 이름으로 반환합니다.

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

예시:

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

converterHelper는 dataView의 속성을 확인하는 함수를 제공합니다.

이 모듈은 다음과 같은 함수를 제공합니다.

categoryIsAlsoSeriesRole

이 함수는 범주가 계열이기도 한지 확인합니다.

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

예시:

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

이 함수는 계열의 이름을 반환합니다.

function getSeriesName(source: DataViewMetadataColumn): PrimitiveValue;

예시:

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

이 함수는 열에 이미지 URL이 포함되어 있는지 확인합니다.

function isImageUrlColumn(column: DataViewMetadataColumn): boolean;

예시:

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

이 함수는 열에 웹 URL이 포함되어 있는지 확인합니다.

function isWebUrlColumn(column: DataViewMetadataColumn): boolean;

예시:

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

이 함수는 dataView에 이미지 URL이 포함된 열이 있는지 확인합니다.

function hasImageUrlColumn(dataView: DataView): boolean;

예시:

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

DataViewObjectsParser는 서식 창의 속성을 구문 분석하는 가장 간단한 방법을 제공합니다.

이 클래스는 다음과 같은 메서드를 제공합니다.

getDefault

이 정적 메서드는 DataViewObjectsParser의 인스턴스를 반환합니다.

static getDefault(): DataViewObjectsParser;

예시:

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

dataViewObjectsParser.getDefault();

// returns: an instance of the DataViewObjectsParser

parse

이 메서드는 서식 창의 속성을 구문 분석하고 DataViewObjectsParser의 인스턴스를 반환합니다.

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

예시:

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

Important

enumerateObjectInstances는 API 버전 5.1에서 더 이상 사용되지 않습니다. getFormattingModel로 대체되었습니다. 또한 FormattingModel 유틸리티를 참조하세요.

이 정적 메서드는 속성을 열거하고 VisualObjectInstanceEnumeration의 인스턴스를 반환합니다.

시각적 개체의 enumerateObjectInstances 메서드에서 실행합니다.

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

예시:

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

다음을 통해 공유

DataViewUtils

설치

DataViewWildcard

DataRoleHelper

getMeasureIndexOfRole

getCategoryIndexOfRole

hasRole

hasRoleInDataView

hasRoleInValueColumn

DataViewObjects

getValue

getObject

getFillColor

getCommonValue

DataViewObject

getValue

getFillColorByPropertyName

converterHelper

categoryIsAlsoSeriesRole

getSeriesName

isImageUrlColumn

isWebUrlColumn

hasImageUrlColumn

DataViewObjectsParser

getDefault

parse

enumerateObjectInstances

피드백

추가 리소스