Power BI 视觉对象的对象和属性

对象描述与视觉对象关联的可自定义属性。 对象可以具有多个属性，并且每个属性都具有描述属性的关联类型。 本文提供有关对象和属性类型的信息。

myCustomObject 是用于引用 dataView 中的对象的内部名称。

JSON复制

"objects": {    "myCustomObject": {        "properties": { ... }
    }
}

显示名称和说明

备注

显示名称和说明从 API 版本 5.1 开始已弃用。 现在，在格式设置模型而非 capabilities.json 文件中添加显示名称和说明。

displayName 是将显示在属性窗格中的名称。 description 是格式设置属性的说明，该属性将以工具提示的形式向用户显示。

属性

properties 是开发者定义的属性的映射。

JSON复制

"properties": {    "myFirstProperty": {        "type": ValueTypeDescriptor | StructuralTypeDescriptor
    }
}

备注

show 是一个特殊属性，允许通过开关来切换对象。

示例：

JSON复制

"properties": {    "show": {        "type": {"bool": true}
    }
}

属性类型

具有两种属性类型：ValueTypeDescriptor 和 StructuralTypeDescriptor。

值类型描述符

ValueTypeDescriptor 类型大多为基元类型，通常用作静态对象。

下面是一些常见 ValueTypeDescriptor 元素：

TypeScript复制

export interface ValueTypeDescriptor {
    text?: boolean;
    numeric?: boolean;
    integer?: boolean;
    bool?: boolean;
}

结构类型描述符

StructuralTypeDescriptor 类型主要用于数据绑定对象。 最常见的 StructuralTypeDescriptor 类型为填充。

TypeScript复制

export interface StructuralTypeDescriptor {
    fill?: FillTypeDescriptor;
}

渐变属性

渐变属性不能设置为标准属性。 相反，需要设置一个规则，以替代颜色选取器属性（填充类型）。

以下代码中显示了一个示例：

JSON复制

"properties": {    "showAllDataPoints": {        "type": {            "bool": true
        }
    },    "fill": {        "type": {            "fill": {                "solid": {                    "color": true
                }
            }
        }
    },    "fillRule": {        "type": {            "fillRule": {}
        },        "rule": {            "inputRole": "Gradient",            "output": {                "property": "fill",                    "selector": [                        "Category"
                    ]
            }
        }
    }
}

请注意填充和 fillRule 属性。 第一个属性是颜色选取器，第二个属性是在满足规则条件时将替代“填充”属性 visually 的渐变替代规则。

填充属性和替代规则之间的此链接在 fillRule 属性的 "rule">"output" 部分中设置 。

"Rule">"InputRole" 属性设置触发规则（条件）的数据角色。 在此示例中，如果数据角色 "Gradient" 包含数据，将为 "fill" 属性应用该规则。

下面的代码显示了触发填充规则 (the last item) 的数据角色的示例：

JSON复制

{    "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 方法

• enumerateObjectInstances API 方法 - 已弃用

 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": {        "myCustomObject": {            "properties": {                "myCustomProperty": {                    "type": {                         "fill": {                            "solid": {                                "color": true
                            }
                        }
                    }
                }
            }
        }
    }           

对象选择器类型

enumerateObjectInstances 中的选择器决定每个对象在 dataView 中的绑定位置。 有四种不同选项：

• static

• 列

• 选择器

• 作用域标识

static

此对象绑定到元数据 dataviews[index].metadata.objects，如下所示。

TypeScript复制

selector: null

列

此对象绑定到具有匹配 QueryName 的列。

TypeScript复制

selector: {
    metadata: 'QueryName'}

选择器

此对象将绑定到你为其创建了 selectionID 的元素。 在此示例中，假设已为某些数据点创建 selectionID，并且正在循环遍历它们。

TypeScript复制

for (let dataPoint in dataPoints) {
    ...
    selector: dataPoint.selectionID.getSelector()
}

作用域标识

此对象绑定到组交集处的特定值。 例如，如果具有类别 ["Jan", "Feb", "March", ...] 和系列 ["Small", "Medium", "Large"]，可能会需要在匹配 Feb 和 Large 的值的交集上有一个对象。 为实现此目的，可以获取这两个列的 DataViewScopeIdentity，将它们推送到变量 identities，然后再结合使用此语法与选择器。

TypeScript复制

selector: {
    data: identities
}