Objetos y propiedades de objetos visuales de Power BI
Los objetos describen propiedades personalizables que están asociadas a un objeto visual. Un objeto puede tener varias propiedades, y cada propiedad tiene un tipo asociado que describe cuál será la propiedad. En este artículo se proporciona información sobre los objetos y los tipos de propiedad.
myCustomObject es el nombre interno usado para hacer referencia al objeto en dataView.
"objects": {
"myCustomObject": {
"properties": { ... }
}
}
Nombre para mostrar y descripción
Nota:
El nombre para mostrar y la descripción están en desuso a partir de la versión 5.1 de la API. El nombre para mostrar y la descripción ahora se agregan en el modelo de formato en lugar del archivo capabilities.json.
displayName es el nombre que se mostrará en el panel de propiedades.
description es una descripción de la propiedad de formato que se mostrará al usuario como información sobre herramientas.
Propiedades
properties es un mapa de propiedades que define el desarrollador.
"properties": {
"myFirstProperty": {
"type": ValueTypeDescriptor | StructuralTypeDescriptor
}
}
Nota
show es una propiedad especial que habilita un botón de alternancia para cambiar el valor del objeto.
Ejemplo:
"properties": {
"show": {
"type": {"bool": true}
}
}
Tipos de propiedad
Hay dos tipos de propiedades: ValueTypeDescriptor y StructuralTypeDescriptor.
Descriptor de tipo de valor
Los tipos ValueTypeDescriptor son en su mayoría primitivos y suelen usarse como un objeto estático.
Estos son algunos de los elementos comunes de ValueTypeDescriptor:
export interface ValueTypeDescriptor {
text?: boolean;
numeric?: boolean;
integer?: boolean;
bool?: boolean;
}
Descriptor de tipo estructural
Los tipos StructuralTypeDescriptor se usan principalmente para objetos enlazados a datos.
El tipo más común de StructuralTypeDescriptor es fill.
export interface StructuralTypeDescriptor {
fill?: FillTypeDescriptor;
}
Propiedad de degradado
La propiedad de degradado no se puede establecer como una propiedad estándar. En su lugar, tiene que configurar una regla para sustituir la propiedad del selector de colores (tipo fill).
En el código siguiente se muestra un ejemplo:
"properties": {
"showAllDataPoints": {
"type": {
"bool": true
}
},
"fill": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
"fillRule": {
"type": {
"fillRule": {}
},
"rule": {
"inputRole": "Gradient",
"output": {
"property": "fill",
"selector": [
"Category"
]
}
}
}
}
Preste atención a las propiedades fill y fillRule. La primera es el selector de colores y la segunda es la regla de sustitución del degradado que reemplazará a la propiedad fill, visually, cuando se cumplan las condiciones de la regla.
Este vínculo entre la propiedad fill y la regla de sustitución se establece en la sección "rule">"output" de la propiedad fillRule.
La propiedad "Rule">"InputRole" establece el rol de datos que desencadena la regla (condición). En este ejemplo, si el rol de datos "Gradient" contiene datos, la regla se aplica en la propiedad "fill".
En el siguiente código se muestra un ejemplo del rol de datos que desencadena la regla de relleno (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"
}
]
}
Panel de formato
Para personalizar las propiedades en el panel de formato, use uno de los métodos siguientes, en función de la versión de API que use.
Nota:
El método de API getFormattingModel se admite a partir de la versión 5.1 de la API. Para averiguar qué versión usa, compruebe apiVersion en el archivo pbiviz.json.
Para usar objetos de forma eficaz en la versión 5.1 y posteriores de la API, debe implementar el método getFormattingModel.
Este método compila y devuelve un modelo de formato que incluye la jerarquía completa del panel de propiedades de tarjetas de formato y grupos de formato. También contiene propiedades de formato y sus valores.
Objetos de funcionalidad reflejados en el modelo de formato
Cada propiedad de formato del modelo de formato necesita un objeto correspondiente en el archivo capabilities.json. La propiedad de formato debe contener un descriptor con un nombre de objeto y un nombre de propiedad que coincidan exactamente con el objeto de funcionalidad correspondiente (los nombres de objeto y propiedad distinguen mayúsculas de minúsculas).
Por ejemplo:
Para la siguiente propiedad de formato en el modelo de formato (vea el contenido del objeto descriptor):
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" }
}
}
}
],
}],
};
El objeto correspondiente de la sección objects de las funcionalidades debe ser:
"objects": {
"myCustomObject": {
"properties": {
"myCustomProperty": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
}
}
}
}
Selector de propiedades de formato
El selector opcional en el descriptor de propiedades de formato determina dónde se enlaza cada propiedad en dataView. Hay cuatro opciones disponibles.
Ejemplo
En el ejemplo myCustomCard anterior se muestra el aspecto de la propiedad de formato del modelo de formato para un objeto con una propiedad myCustomProperty. Este objeto de propiedad se enlaza estáticamente a dataViews[index].metadata.objects.
El selector del descriptor se puede cambiar según corresponda al tipo de selector que elija.
Tipos de selectores de objetos
El selector de enumerateObjectInstances determina dónde se enlaza cada objeto en el elemento dataView. Hay cuatro opciones disponibles:
static
Este objeto se enlaza a los metadatos dataviews[index].metadata.objects, como se muestra aquí.
selector: null
columnas
Este objeto se enlaza a columnas con los metadatos QueryName correspondientes.
selector: {
metadata: 'QueryName'
}
selector
Este objeto se enlaza al elemento para el que ha creado un elemento selectionID. En este ejemplo, daremos por hecho que hemos creado elementos selectionID para algunos puntos de datos y que los estamos recorriendo en bucle.
for (let dataPoint in dataPoints) {
...
selector: dataPoint.selectionID.getSelector()
}
Identidad del ámbito
Este objeto se enlaza a valores específicos en la intersección de grupos. Por ejemplo, si tiene las categorías ["Jan", "Feb", "March", ...] y las series ["Small", "Medium", "Large"], puede que quiera tener un objeto en la intersección de los valores que coincidan con Feb y Large. Para lograrlo, podría obtener el valor DataViewScopeIdentity de ambas columnas, insertarlos en la variable identities y, después, usar esta sintaxis con el selector.
selector: {
data: <DataViewScopeIdentity[]>identities
}