Power BI 시각적 개체의 기능 및 속성Capabilities and properties of Power BI visuals

기능을 사용하여 시각적 개체 정보를 호스트에 제공합니다.You use capabilities to provide information to the host about your visual. 기능 모델의 모든 속성은 optional입니다.All properties on the capabilities model are optional.

시각적 개체 기능의 루트 개체는 dataRoles, dataViewMappings 등입니다.The root objects of a visual's capabilities are dataRoles, dataViewMappings, and so on.

{
    "dataRoles": [ ... ],
    "dataViewMappings": [ ... ],
    "objects":  { ... },
    "supportsHighlight": true|false,
    "advancedEditModeSupport": 0|1|2,
    "sorting": { ... }
}

시각적 개체에 필요한 데이터 필드 정의: dataRolesDefine the data fields that your visual expects: dataRoles

데이터에 바인딩할 수 있는 필드를 정의하려면 dataRoles를 사용합니다.To define fields that can be bound to data, you use dataRoles. dataRoles는 모든 필수 속성을 정의하는 DataViewRole 개체의 배열을 사용합니다.dataRoles takes an array of DataViewRole objects, which defines all the required properties.

속성Properties

  • name: 이 데이터 필드의 내부 이름(고유해야 함)name: The internal name of this data field (must be unique).
  • kind: 필드 종류:kind: The kind of field:
    • Grouping: 측정값 필드의 그룹화에 사용되는 불연속 값Grouping: Discrete values that are used to group measure fields.
    • Measure: 숫자 데이터 값Measure: Numeric data values.
    • GroupingOrMeasure: 그룹화 또는 측정값으로 사용할 수 있는 값GroupingOrMeasure: Values that can be used as either a grouping or a measure.
  • displayName: 속성 창에서 사용자에게 표시되는 이름displayName: The name displayed to the user in the Properties pane.
  • description: 필드에 대한 간략한 설명(선택 사항)description: A short description of the field (optional).
  • requiredTypes: 이 데이터 역할에 필요한 데이터 형식.requiredTypes: The required type of data for this data role. 일치하지 않는 값은 null로 설정됩니다(선택 사항).Values that don't match are set to null (optional).
  • preferredTypes: 이 데이터 역할의 기본 데이터 형식(선택 사항)preferredTypes: The preferred type of data for this data role (optional).

requiredTypes 및 preferredTypes의 유효한 데이터 형식Valid data types in requiredTypes and preferredTypes

  • bool: 부울 값bool: A boolean value
  • integer: 정수 값integer: An integer (whole number) value
  • numeric: 숫자 값numeric: A numeric value
  • text: 텍스트 값text: A text value
  • geography: 지리 데이터geography: A geographic data

예제Example

"dataRoles": [
    {
        "displayName": "My Category Data",
        "name": "myCategory",
        "kind": "Grouping",
        "requiredTypes": [
            {
                "text": true
            },
            {
                "numeric": true
            },
            {
                "integer": true
            }
        ],
        "preferredTypes": [
            {
                "text": true
            }
        ]
    },
    {
        "displayName": "My Measure Data",
        "name": "myMeasure",
        "kind": "Measure",
        "requiredTypes": [
            {
                "integer": true
            },
            {
                "numeric": true
            }
        ],
        "preferredTypes": [
            {
                "integer": true
            }
        ]
    },
    {
        "displayNameKey": "Visual_Location",
        "name": "Locations",
        "kind": "Measure",
        "displayName": "Locations",
        "requiredTypes": [
            {
                "geography": {
                    "address": true
                }
            },
            {
                "geography": {
                    "city": true
                }
            },
            {
                "geography": {
                    "continent": true
                }
            },
            {
                "geography": {
                    "country": true
                }
            },
            {
                "geography": {
                    "county": true
                }
            },
            {
                "geography": {
                    "place": true
                }
            },
            {
                "geography": {
                    "postalCode": true
                }
            },
            {
                "geography": {
                    "region": true
                }
            },
            {
                "geography": {
                    "stateOrProvince": true
                }
            }
        ]
    }
]

위의 데이터 역할은 다음 이미지에 표시된 필드를 만듭니다.The preceding data roles would create the fields that are displayed in the following image:

데이터 역할 필드

데이터 매핑 방법 정의: dataViewMappingsDefine how you want the data mapped: dataViewMappings

DataViewMappings 속성은 데이터 역할 간의 관계를 설명하고, 이러한 역할에 대해 조건부 요구 사항을 지정할 수 있도록 합니다.A DataViewMappings property describes how the data roles relate to each other and allows you to specify conditional requirements for the them.

대부분의 시각적 개체는 단일 매핑을 제공하지만, 여러 개의 dataViewMappings를 제공할 수 있습니다.Most visuals provide a single mapping, but you can provide multiple dataViewMappings. 유효한 매핑마다 하나의 데이터 뷰를 생성합니다.Each valid mapping produces a data view.

"dataViewMappings": [
    {
        "conditions": [ ... ],
        "categorical": { ... },
        "table": { ... },
        "single": { ... },
        "matrix": { ... }
    }
]

자세한 내용은 Power BI 시각적 개체의 데이터 뷰 매핑 이해를 참조하세요.For more information, see Understand data view mapping in Power BI visuals.

속성 창 옵션 정의: objectsDefine property pane options: objects

개체는 시각적 개체와 연결된 사용자 지정 가능한 속성을 설명합니다.Objects describe customizable properties that are associated with the visual. 각 개체에 여러 개의 속성이 있을 수 있으며, 속성마다 연결된 형식이 있습니다.Each object can have multiple properties, and each property has a type that's associated with it. 형식은 속성이 무엇인지를 나타냅니다.Types refer to what the property will be.

"objects": {
    "myCustomObject": {
        "displayName": "My Object Name",
        "properties": { ... }
    }
}

자세한 내용은 Power BI 시각적 개체의 개체 및 속성을 참조하세요.For more information, see Objects and properties of Power BI visuals.

부분 강조 표시 처리: supportsHighlightHandle partial highlighting: supportsHighlight

기본적으로 이 값은 false로 설정되어 있으므로, 페이지의 항목을 선택하면 값이 자동으로 필터링됩니다.By default, this value is set to false, which means that your values are automatically filtered when something on the page is selected. 이 자동 필터링은 다시 선택한 값만 표시하도록 시각적 개체를 업데이트합니다.This automatic filtering in turn updates your visual to display only the selected value. 전체 데이터를 표시하되 선택한 항목만 강조 표시하려는 경우 capabilities.json 파일에서 supportsHighlighttrue로 설정해야 합니다.If you want to display the full data but highlight only the selected items, you need to set supportsHighlight to true in your capabilities.json file.

자세한 내용은 Power BI 시각적 개체에서 데이터 요소 강조 표시를 참조하세요.For more information, see Highlight data points in Power BI visuals.

고급 편집 모드 처리: advancedEditModeSupportHandle advanced edit mode: advancedEditModeSupport

시각적 개체에서 고급 편집 모드 지원을 선언할 수 있습니다.A visual can declare its support of advanced edit mode. capabilities.json 파일에서 달리 지정되지 않은 경우, 기본적으로 시각적 개체는 고급 편집 모드를 지원하지 않습니다.By default, a visual doesn't support advanced edit mode, unless stated otherwise in the capabilities.json file.

자세한 내용은 Power BI 시각적 개체의 고급 편집 모드를 참조하세요.For more information, see Advanced edit mode in Power BI visuals.

시각적 개체의 데이터 정렬 옵션: sortingData sorting options for visual: sorting

시각적 개체는 해당 기능을 통해 정렬 동작을 정의할 수 있습니다.A visual can define its sorting behavior via its capabilities. capabilities.json 파일에서 달리 지정되지 않은 경우, 기본적으로 시각적 개체는 정렬 순서 수정을 지원하지 않습니다.By default, a visual doesn't support modifying its sorting order, unless stated otherwise in the capabilities.json file.

자세한 내용은 Power BI 시각적 개체의 정렬 옵션을 참조하세요.For more information, see Sorting options for Power BI visuals.