Personalizar el panel Formato en objetos visuales personalizados de Power BI
A partir de la versión 5.1 de la API, los desarrolladores pueden crear objetos visuales que usen el nuevo panel Formato de Power. Los desarrolladores pueden definir las tarjetas y sus categorías para cualquier propiedad de su objeto visual personalizado, lo que facilita a los creadores de informes el uso de estos objetos visuales.
La nueva API usa el método FormatModel para personalizar partes de los paneles de formato y análisis.
Sugerencia
El método getFormattingModel reemplaza el método enumerateObjectInstances en versiones anteriores de la API.
getFormattingModel devuelve un valor de tipo FormattingModel que define el aspecto del panel de formato y análisis del objeto visual.
Además de todas las funcionalidades del panel de formato antiguo, el nuevo modelo de formato admite nuevas funcionalidades del panel de formato, nuevas propiedades y nuevas jerarquías.
Para actualizar a la versión 5.1 o posterior de la API, establezca la apiVersion en el archivo pbiviz.json en 5.1 o posterior y realice una de las siguientes acciones:
- Use utilidades de formattingmodel. (Recomendado)
- Sin esta utilidad, use solo las API según el método siguiente.
Crear un objeto visual compatible con el nuevo panel de formato
Para crear un objeto visual personalizado que use el nuevo panel de formato:
Defina todas los
objectspersonalizables en el archivo capabilities.json.
Se requieren las siguientes propiedades para cada objeto:- nombre de objeto
- nombre de la propiedad
- tipo de propiedad
Todas las demás propiedades, incluidas
DisplayNameydescription, ahora son opcionales.Compile el objeto visual personalizado FormatModel. Defina las propiedades del modelo de formato de objeto visual personalizado y compílelo mediante código (no JSON).
Implemente la API
getFormattingModelen la clase de objeto visual personalizada que devuelve el modelo de formato de objeto visual personalizado. (Esta API reemplaza a laenumerateObjectInstancesque se usó en versiones anteriores).
Propiedades de formato de mapa
Si tiene un objeto visual personalizado creado con una API anterior y desea migrar al nuevo panel de formato, o si va a crear un nuevo objeto visual personalizado:
Establezca la
apiVersionen el archivo pbiviz.json en5.1o posterior.Para cada nombre de objeto y nombre de propiedad en capabilities.json, cree una propiedad de formato coincidente. La propiedad de formato debe tener un descriptor que contenga
objectNameypropertyNameque coincida con el nombre de objeto y el nombre de propiedad en capabilities.json.
Las propiedades objects del archivo de funcionalidades siguen teniendo el mismo formato y no es necesario cambiarlas.
Por ejemplo, si el objeto circle del archivo capabilities.json se define de la siguiente manera:
"objects": {
"circle": {
"properties": {
"circleColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
}
}
}
La propiedad de formato del modelo debe ser de tipo ColorPicker y tener este aspecto:
control: {
type: "ColorPicker",
properties: {
descriptor: {
objectName: "circle",
propertyName: "circleColor"
},
value: {
value: this.visualSettings.circle.circleColor
}
}
}
Recibirá un error si el valor de una de las condiciones siguientes es true:
- El nombre de objeto o propiedad del archivo de funcionalidades no coincide con el del modelo de formato
- El tipo de propiedad del archivo de funcionalidades no coincide con el tipo en el modelo de formato
Modelo de formato
El modelo de formato es donde se describen y personalizan todas las propiedades del panel de formato.
Aplicación de formato a los componentes del modelo
En el nuevo modelo de formato, los componentes de propiedad se agrupan en categorías lógicas y subcategorías. Estos grupos facilitan el examen del modelo. Hay cinco componentes básicos, de más grande a más pequeño:
Modelo de formato
El contenedor de panel más grande, que se usa para dar formato a la interfaz frontal del panel. Contiene una lista de tarjetas de formato.Tarjeta de formato
Contenedor de agrupación de propiedades de nivel superior para aplicar formato a las propiedades. Cada tarjeta consta de uno o varios grupos de formato, como se muestra aquí.
Grupo de formato
Contenedor de agrupación de propiedades de nivel secundario. El grupo de formato se muestra como un contenedor de agrupación para segmentos de formato.
Segmento de formato
Contenedor de propiedades. Hay dos tipos de segmentos:- Segmento simple: contenedor de propiedad individual
- Segmento compuesto: varios contenedores de propiedades relacionados agrupados en un segmento de formato
En la imagen siguiente se muestran los distintos tipos de segmentos. "Fuente" es un segmento compuesto que consta de la familia de fuentes, tamaño y negrita, cursiva y modificadores de subrayado. "Color", "unidades de visualización" y los demás segmentos son segmentos simples con un componente cada uno.
Propiedades de formato del panel de visualización
Cada propiedad del modelo de formato debe coincidir y el tipo de objeto en el archivo capabilities.json.
En la tabla siguiente se muestran los tipos de propiedad de formato en el archivo capabilities.json y su clase de tipo coincidente en las propiedades del modelo de formato moderno:
| Tipo | Tipo de valor de funcionalidades | Propiedad Formatting |
|---|---|---|
| Boolean | Bool | ToggleSwitch |
| Number | ||
| Lista de enumeración | enumeration:[] | |
| Color | Rellenar | ColorPicker |
| Degradado | fillRule | GradientBar: el valor de propiedad debe ser una cadena que conste de: minValue[,midValue],maxValue |
| Texto | Texto |
Objeto de formato de funcionalidades
| Tipo | Tipo de valor de funcionalidades | Propiedad Formatting |
|---|---|---|
| Tamaño de fuente | FontSize | NumUpDown |
| Familia de fuentes | FontFamily | FontPicker |
| Alineación de líneas | Alineación | AlignmentGroup |
| Unidades de presentación de etiquetas | LabelDisplayUnits | AutoDropDown |
* La propiedad de formato de lista de enumeración es diferente en el modelo de formato y en el archivo de funcionalidades.
Declare las siguientes propiedades en la clase de configuración de formato, incluida la lista de elementos de enumeración:
- ItemDropdown
- ItemFlagsSelection
Declare las siguientes propiedades en la clase de configuración de formato, sin la lista de elementos de enumeración. Declare su lista de elementos de enumeración en capabilities.json en el objeto adecuado. (Estos tipos son los mismos que en las versiones anteriores de la API):
- AutoDropdown
- AutoFlagSelection
Propiedades del segmento compuesto
Un segmento compuesto de formato es un segmento de formato que contiene varias propiedades relacionadas juntas.
Por ahora tenemos dos tipos de segmentos compuestos:
FontControl
Esto mantiene juntas todas las propiedades relacionadas con la fuente. Consta de las siguientes propiedades:- Familia de fuentes
- Tamaño de fuente
- Negrita [opcional]
- Cursiva [opcional]
- Subrayado [opcional]
Cada una de estas propiedades debe tener un objeto correspondiente en el archivo de funcionalidades:
Propiedad Tipo de funcionalidad Tipo de formato Familia de fuentes Formato: {fontFamily} FontPicker Tamaño de fuente Formato: {fontSize} NumUpDown Bold Bool ToggleSwitch Cursiva Bool ToggleSwitch Subrayado Bool ToggleSwitch MarginPadding El relleno del margen determina la alineación del texto en el objeto visual. Consta de las siguientes propiedades:
- Left
- Right
- Superior
- Inferior
Cada una de estas propiedades debe tener un objeto correspondiente en el archivo de funcionalidades:
Propiedad Tipo de funcionalidad Tipo de formato Izquierda Numeric NumUpDown Right Numeric NumUpDown Superior Numeric NumUpDown Inferior Numeric NumUpDown
Ejemplo: aplicar formato a una tarjeta de datos
En este ejemplo, se muestra cómo crear un modelo de formato de objeto visual personalizado con una tarjeta.
La tarjeta tiene dos grupos:
- Grupo de control de fuente con una propiedad compuesta
- Control de fuente
- Grupo de diseño de datos con dos propiedades simples
- Color de fuente
- Alineación de líneas
En primer lugar, agregue objetos al archivo de funcionalidades:
"objects": {
"dataCard": {
"properties": {
"displayUnitsProperty": {
"type":
{
"formatting": {
"labelDisplayUnits": true
}
}
},
"fontSize": {
"type": {
"formatting": {
"fontSize": true
}
}
},
"fontFamily": {
"type": {
"formatting": {
"fontFamily": true
}
}
},
"fontBold": {
"type": {
"bool": true
}
},
"fontUnderline": {
"type": {
"bool": true
}
},
"fontItalic": {
"type": {
"bool": true
}
},
"fontColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
"lineAlignment": {
"type": {
"formatting": {
"alignment": true
}
}
}
}
}
}
A continuación, cree el getFormattingModel
public getFormattingModel(): powerbi.visuals.FormattingModel {
// Building data card, We are going to add two formatting groups "Font Control Group" and "Data Design Group"
let dataCard: powerbi.visuals.FormattingCard = {
description: "Data Card Description",
displayName: "Data Card",
uid: "dataCard_uid",
groups: []
}
// Building formatting group "Font Control Group"
// Notice that "descriptor" objectName and propertyName should match capabilities object and property names
let group1_dataFont: powerbi.visuals.FormattingGroup = {
displayName: "Font Control Group",
uid: "dataCard_fontControl_group_uid",
slices: [
{
uid: "dataCard_fontControl_displayUnits_uid",
displayName:"display units",
control: {
type: powerbi.visuals.FormattingComponent.Dropdown,
properties: {
descriptor: {
objectName: "dataCard",
propertyName:"displayUnitsProperty"
},
value: 0
}
}
},
// FontControl slice is composite slice, It means it contain multiple properties inside it
{
uid: "data_font_control_slice_uid",
displayName: "Font",
control: {
type: powerbi.visuals.FormattingComponent.FontControl,
properties: {
fontFamily: {
descriptor: {
objectName: "dataCard",
propertyName: "fontFamily"
},
value: "wf_standard-font, helvetica, arial, sans-serif"
},
fontSize: {
descriptor: {
objectName: "dataCard",
propertyName: "fontSize"
},
value: 16
},
bold: {
descriptor: {
objectName: "dataCard",
propertyName: "fontBold"
},
value: false
},
italic: {
descriptor: {
objectName: "dataCard",
propertyName: "fontItalic"
},
value: false
},
underline: {
descriptor: {
objectName: "dataCard",
propertyName: "fontUnderline"
},
value: false
}
}
}
}
],
};
// Building formatting group "Font Control Group"
// Notice that "descriptor" objectName and propertyName should match capabilities object and property names
let group2_dataDesign: powerbi.visuals.FormattingGroup = {
displayName: "Data Design Group",
uid: "dataCard_dataDesign_group_uid",
slices: [
// Adding ColorPicker simple slice for font color
{
displayName: "Font Color",
uid: "dataCard_dataDesign_fontColor_slice",
control: {
type: powerbi.visuals.FormattingComponent.ColorPicker,
properties: {
descriptor:
{
objectName: "dataCard",
propertyName: "fontColor"
},
value: { value: "#01B8AA" }
}
}
},
// Adding AlignmentGroup simple slice for line alignment
{
displayName: "Line Alignment",
uid: "dataCard_dataDesign_lineAlignment_slice",
control: {
type: powerbi.visuals.FormattingComponent.AlignmentGroup,
properties: {
descriptor:
{
objectName: "dataCard",
propertyName: "lineAlignment"
},
mode: powerbi.visuals.AlignmentGroupMode.Horizonal,
value: "right"
}
}
},
]
};
// Add formatting groups to data card
dataCard.groups.push(group1_dataFont);
dataCard.groups.push(group2_dataDesign);
// Build and return formatting model with data card
const formattingModel: powerbi.visuals.FormattingModel = { cards: [dataCard] };
return formattingModel;
}
Este es el panel resultante:
Restablecer la configuración al valor predeterminado
El nuevo panel de formato tiene la opción de restablecer todos los valores de propiedades de tarjeta de formato de forma predeterminada haciendo clic en el botón Restablecer al valor predeterminado que aparece en la tarjeta abierta.
Para habilitar esta característica, agregue una lista de descriptores de propiedades de tarjeta de formato a la tarjeta de formato revertToDefaultDescriptors.
En el ejemplo siguiente se muestra cómo agregar el botón Restablecer al valor predeterminado :
let dataCard: powerbi.visuals.FormattingCard = {
displayName: "Data Card",
// ... card parameters and groups list
revertToDefaultDescriptors: [
{
objectName: "dataCard",
propertyName:"displayUnitsProperty"
},
{
objectName: "dataCard",
propertyName: "fontFamily"
},
// ... the rest of properties descriptors
]
};
Agregar revertToDefaultDescriptors a tarjetas de formato también permite restablecer todas las propiedades de las tarjetas de formato a la vez haciendo clic en el botón restablecer toda la configuración al valor predeterminado en la barra superior del panel de formato:
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. Obtenga información sobre ellos en los tipos de selectores de objetos.
Localización
Para obtener más información sobre la característica de localización y para configurar un entorno de localización, consulte Incorporación del idioma local a un objeto visual de Power BI. Usar el administrador de localización para dar formato a los componentes que desea localizar:
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Para localizar las utilidades del modelo de formato, consulte Localización de utilidades de formato.
Recursos de GitHub
Todas las interfaces de modelo de formato se pueden encontrar en GitHub: microsoft/powerbi-visuals-api: API de objetos visuales personalizados de Power BI en "format-model-api.d.ts"
Se recomienda usar las nuevas utilidades del modelo de formato en GitHub: microsoft/powerbi-visuals-utils-formatmodel: Utilidades auxiliares del modelo de formato de objetos visuales de Power BI
Puede encontrar un ejemplo de un sampleBarChart de objeto visual personalizado que usa la versión de API 5.1.0 e implementa
getFormattingModelcon las nuevas utilidades del modelo de formato en GitHub: microsoft/PowerBI-visuals-sampleBarChart: Objeto visual personalizado de gráfico de barras para el tutorial.
Pasos siguientes
¿Tiene más preguntas? Pregunte a la comunidad de Power BI