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

项目
03/23/2023

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

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 类型为填充。

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"
                    ]
            }
        }
    }
}

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

填充属性和替代规则之间的此链接在 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 方法
enumerateObjectInstances API 方法 - 已弃用

注意

从 API 版本 5.1 开始支持 getFormattingModel API 方法。若要了解正在使用的版本，请检查 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 方法从 API 版本 5.1 起已弃用。在新 API 中，它已被 getFormattingModel 取代。

若要有效使用对象，需要使用自定义视觉对象中名为 enumerateObjectInstances 的函数。此函数使用对象填充属性窗格，并决定对象在 dataView 中的绑定位置。

典型设置如下所示：

public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
    let objectName: string = options.objectName;
    let objectEnumeration: VisualObjectInstance[] = [];

    switch( objectName ) {
        case 'myCustomObject':
            objectEnumeration.push({
                objectName: objectName,
                properties: { ... },
                selector: { ... }
            });
            break;
    };

    return objectEnumeration;
}

enumerateObjectInstances 属性

enumerateObjectInstances 中的属性反映在功能中定义的属性。有关示例，请参阅本文末尾。

enumerateObjectInstances 示例

以下示例显示具有一个属性（“填充”）的 customColor 对象的 objectEnumeration 的外观。我们希望将此对象静态绑定到 dataViews[index].metadata.objects，如下所示：

objectEnumeration.push({
    objectName: "customColor",
    displayName: "Custom Color",
    properties: {
        fill: {
            solid: {
                color: dataPoint.color
            }
        }
    },
    selector: null
});

对象选择器类型

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

static
列
选择器
作用域标识

static

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

selector: null

列

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

selector: {
    metadata: 'QueryName'
}

选择器

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

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

作用域标识

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

selector: {
    data: <DataViewScopeIdentity[]>identities
}

后续步骤

性能提示

Share via