Power BI 시각적 개체의 개체 및 속성
개체는 시각적 개체와 연결된 사용자 지정 가능한 속성을 설명합니다. 각 개체에 여러 개의 속성이 있을 수 있으며, 속성마다 해당 속성이 무엇인지를 설명하는 연결된 형식이 있습니다. 이 문서에서는 개체와 속성 형식에 대한 정보를 제공합니다.
myCustomObject는 dataView 내에서 개체를 참조하는 데 사용되는 내부 이름입니다.
"objects": {
"myCustomObject": {
"properties": { ... }
}
}
표시 이름 및 설명
참고 항목
API 버전 5.1 이상에서는 표시 이름과 설명이 더 이상 사용되지 않습니다. 이제 표시 이름과 설명이 capabilities.json 파일 대신 서식 모델에 추가됩니다.
displayName은 속성 창에 표시되는 이름입니다.
description은 사용자에게 도구 설명으로 표시될 서식 속성에 대한 설명입니다.
속성
properties는 개발자가 정의한 속성 맵입니다.
"properties": {
"myFirstProperty": {
"type": ValueTypeDescriptor | StructuralTypeDescriptor
}
}
참고 항목
show는 스위치가 개체를 토글할 수 있도록 하는 특수 속성입니다.
예시:
"properties": {
"show": {
"type": {"bool": true}
}
}
속성 형식
ValueTypeDescriptor 및 StructuralTypeDescriptor라는 두 가지 속성 형식이 있습니다.
값 형식 설명자
ValueTypeDescriptor 형식은 대체로 기본 형식이며, 일반적으로 정적 개체로 사용됩니다.
몇 가지 일반적인 ValueTypeDescriptor 요소는 다음과 같습니다.
export interface ValueTypeDescriptor {
text?: boolean;
numeric?: boolean;
integer?: boolean;
bool?: boolean;
}
구조적 형식 설명자
StructuralTypeDescriptor 형식은 데이터 바인딩된 개체에 주로 사용됩니다.
가장 일반적인 StructuralTypeDescriptor 형식은 fill입니다.
export interface StructuralTypeDescriptor {
fill?: FillTypeDescriptor;
}
그라데이션 속성
그라데이션 속성은 표준 속성으로 설정할 수 없는 속성입니다. 대신, 색 선택기 속성(채우기 유형)을 대체하는 규칙을 설정해야 합니다.
예제는 다음 코드에 나와 있습니다.
"properties": {
"showAllDataPoints": {
"type": {
"bool": true
}
},
"fill": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
"fillRule": {
"type": {
"fillRule": {}
},
"rule": {
"inputRole": "Gradient",
"output": {
"property": "fill",
"selector": [
"Category"
]
}
}
}
}
fill 및 fillrule 속성에 주의합니다. 첫 번째 속성은 색 선택기이고, 두 번째 속성은 규칙 조건이 충족될 때 ‘fill’ 속성 visually를 바꾸는 그라데이션 대체 규칙입니다.
‘fill’ 속성과 대체 규칙 간의 이러한 연결은 fillRule 속성의 "rule">"output" 섹션에서 설정됩니다.
"Rule">"InputRole" 속성은 규칙(조건)을 트리거하는 데이터 역할을 설정합니다. 이 예제에서는 데이터 역할 "Gradient"에 데이터가 포함된 경우 "fill" 속성에 규칙이 적용됩니다.
채우기 규칙(the last item)을 트리거하는 데이터 역할의 예는 다음 코드에 나와 있습니다.
{
"dataRoles": [
{
"name": "Category",
"kind": "Grouping",
"displayName": "Details",
"displayNameKey": "Role_DisplayName_Details"
},
{
"name": "Series",
"kind": "Grouping",
"displayName": "Legend",
"displayNameKey": "Role_DisplayName_Legend"
},
{
"name": "Gradient",
"kind": "Measure",
"displayName": "Color saturation",
"displayNameKey": "Role_DisplayName_Gradient"
}
]
}
서식 지정 창
서식 창에서 속성을 사용자 지정하려면 사용 중인 API 버전에 따라 다음 방법 중 하나를 사용합니다.
참고 항목
getFormattingModel API 메서드는 API 버전 5.1 이상에서 지원됩니다. 사용 중인 버전을 확인하려면 pbiviz.json 파일에서 apiVersion을 확인합니다.
API 버전 5.1 이상에서 개체를 효과적으로 사용하려면 getFormattingModel 메서드를 구현해야 합니다.
이 메서드는 서식 지정 카드, 서식 그룹의 전체 속성 창 계층 구조를 포함하는 서식 모델을 빌드하고 반환합니다. 또한 서식 속성 및 해당 값도 포함합니다.
서식 모델에 반영된 기능 개체
서식 모델의 각 서식 속성에는 capabilities.json 파일의 해당 개체가 필요합니다. 서식 속성에는 해당 기능 개체와 정확히 일치하는 개체 이름과 속성 이름을 가진 설명자가 포함되어야 합니다(개체 및 속성 이름은 대/소문자를 구분함).
예시:
서식 모델의 다음 서식 속성에 대해서는 설명자 개체 콘텐츠를 참조하세요.
const myCustomCard: powerbi.visuals.FormattingCard = {
displayName: "My Custom Object Card",
uid: "myCustomObjectCard_uid",
groups: [{
displayName: undefined,
uid: "myCustomObjectGroup_uid",
slices: [
{
uid: "myCustomProperty_uid",
displayName: "My Custom Property",
control: {
type: powerbi.visuals.FormattingComponent.ColorPicker,
properties: {
descriptor: {
objectName: "myCustomObject",
propertyName: "myCustomProperty",
selector: null // selector is optional
},
value: { value: "#000000" }
}
}
}
],
}],
};
기능 objects 섹션의 해당 개체는 다음과 같습니다.
"objects": {
"myCustomObject": {
"properties": {
"myCustomProperty": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
}
}
}
}
서식 속성 선택기
서식 속성 설명자의 선택적 선택기는 각 속성이 dataView에 바인딩되는 위치를 결정합니다. 네 가지 옵션이 있습니다.
예시
위의 myCustomCard 예제는 myCustomProperty 속성이 하나인 개체에 대해 서식 모델의 어떤 서식 속성이 어떻게 표시되는지 보여줍니다. 이 속성 개체는 dataViews[index].metadata.objects에 정적으로 바인딩됩니다.
설명자의 선택기는 선택한 선택기 형식에 따라 변경할 수 있습니다.
개체 선택기 형식
enumerateObjectInstances의 선택기는 dataView에서 각 개체가 바인딩되는 위치를 결정합니다. 다음 네 가지 옵션이 있습니다.
static
이 개체는 여기에 표시된 것처럼 dataviews[index].metadata.objects 메타데이터에 바인딩됩니다.
selector: null
열
이 개체는 QueryName이 일치하는 열에 바인딩됩니다.
selector: {
metadata: 'QueryName'
}
selector
이 개체는 만든 selectionID의 요소에 바인딩됩니다. 이 예제에서는 일부 데이터 요소의 selectionID를 만들었으며, 해당 ID를 반복한다고 가정해 보겠습니다.
for (let dataPoint in dataPoints) {
...
selector: dataPoint.selectionID.getSelector()
}
Scope identity
이 개체는 그룹의 교집합에 있는 특정 값에 바인딩됩니다. 예를 들어 ["Jan", "Feb", "March", ...] 범주와 ["Small", "Medium", "Large"] 계열이 있는 경우, Feb 및 Large와 일치하는 값의 교집합에 개체를 포함할 수 있습니다. 이 작업을 위해 두 열의 DataViewScopeIdentity를 모두 가져와 identities 변수에 밀어넣고, 선택기에서 다음 구문을 사용할 수 있습니다.
selector: {
data: <DataViewScopeIdentity[]>identities
}