Объекты и свойства визуальных элементов 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когда выполняются условия правила.
Эта связь между свойством заполнения и правилом подстановки задана в"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+. Чтобы узнать, какая версия используется, проверьте apiVersion файл pbiviz.json .
Чтобы эффективно использовать объекты в 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
}