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 类型为填充。
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 版本。
注意
从 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 中的选择器决定每个对象在 dataView 中的绑定位置。 有四种不同选项：
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
}