Utilidades de FormatModel

Artículo
11/30/2023

Las utilidades de modelo de formato contienen las clases, interfaces y métodos necesarios para crear un modelo de configuración de formato para rellenar los paneles de propiedades (paneles de formato y análisis) del objeto visual personalizado de Power BI.

Servicio de configuración de formato

El servicio de configuración de formato recibe un modelo de configuración de formato y lo convierte en un modelo de formato que rellena el panel de formato. El servicio de modelo de formato también admite localizaciones de cadenas.

Inicializar el servicio de configuración de formato:

import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";

export class MyVisual implements IVisual {
    // declaring formatting settings service 
    private formattingSettingsService: FormattingSettingsService;

    constructor(options: VisualConstructorOptions) {
        
        this.formattingSettingsService = new FormattingSettingsService();
        
        // ...
    }
}

La interfaz de servicio de configuración de formato IFormattingSettingsService tiene dos métodos principales:

    /**
     * Build visual formatting settings model from metadata dataView
     * 
     * @param dataViews metadata dataView object
     * @returns visual formatting settings model 
     */
    populateFormattingSettingsModel<T extends Model>(typeClass: new () => T, dataViews: powerbi.DataView[]): T;

    /**
     * Build formatting model by parsing formatting settings model object 
     * 
     * @returns powerbi visual formatting model
     */
    buildFormattingModel(formattingSettingsModel: Model): visuals.FormattingModel;

Modelo de configuración de formato

El modelo de configuración contiene y ajusta todas las tarjetas de formato para el panel de formato y el panel de análisis.

export class Model {
    cards: Array<Cards>;
}

En este ejemplo se declara un nuevo modelo de configuración de formato:

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCompositeCard = formattingSettings.CompositeCard;
import FormattingSettingsCards = formattingSettings.Cards;
import FormattingSettingsModel = formattingSettings.Model;

export class VisualSettingsModel extends FormattingSettingsModel {
    // Building my visual formatting settings card
    myVisualCard: FormattingSettingsCompositeCard = new myVisualCardSettings();

    // Add formatting settings card to cards list in model
    cards: FormattingSettingsCards[] = [this.myVisualCard];
}

Tarjeta de configuración de formato

Una tarjeta de configuración de formato especifica una tarjeta de formato en el panel de formato o análisis. Una tarjeta de configuración de formato puede contener varios segmentos, contenedores, grupos y propiedades de formato.

Agregar segmentos a una tarjeta de configuración de formato coloca todos estos segmentos en una tarjeta de formato.

Las tarjetas, los segmentos y los grupos se pueden ocultar dinámicamente estableciendo el parámetro visible en false (true de forma predeterminada).

La tarjeta puede rellenar el panel de formato o el panel de análisis estableciendo el parámetro analyticsPane en true o false.

Ejemplo de declaración de tarjeta de configuración de formato, que incluye un segmento y un grupo de configuración de formato:

El nombre de la tarjeta debe coincidir con el nombre del objeto en capabilities.json
El nombre del segmento debe coincidir con el nombre de la propiedad en capabilities.json

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCompositeCard = formattingSettings.CompositeCard;
import FormattingSettingsGroup = formattingSettings.Group;
import FormattingSettingsSlice = formattingSettings.Slice;

// Formatting settings group
class myVisualGroupSettings extends FormattingSettingsGroup {
    // Formatting settings slice
    myAnotherNumericSlice = new formattingSettings.NumUpDown({
        name: "myAnotherNumericSlice",
        displayName: "My Formatting Numeric Slice in group",
        value: 15,
        visible: true,
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    visible: boolean = true;
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

// Formatting settings card
class myVisualCardSettings extends FormattingSettingsCompositeCard {
    // Formatting settings slice
    myNumericSlice = new formattingSettings.NumUpDown({
        name: "myNumericSlice",
        displayName: "My Formatting Numeric Slice",
        value: 50,
        visible: true,
        options: {
            minValue: {
                type: powerbi.visuals.ValidatorType.Min,
                value: 0,
            },
            maxValue: {
                type: powerbi.visuals.ValidatorType.Max,
                value: 100,
            },
        }
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    visible: boolean = true;

    groupSetting = new myVisualGroupSettings(Object())
    groups: Array<FormattingSettingsGroup> = [this.groupSetting]
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

La declaración de propiedad capabilities.json debe ser:

"objects": {
    "myVisualCard": {
        "properties": {
            "myNumericSlice": {
                "type": {
                    "numeric": true 
                }
            },
            "myAnotherNumericSlice": {
                "type": {
                    "numeric": true 
                }
            },
        }
    }
}

Grupo de configuración de formato

Algunas tarjetas de configuración de formato pueden tener grupos dentro. Los grupos constan de segmentos y se pueden expandir o contraer.

Ejemplo de declaración del grupo de configuración de formato con un segmento:

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsGroup = formattingSettings.Group;
import FormattingSettingsSlice = formattingSettings.Slice;

class myVisualGroupSettings extends FormattingSettingsGroup {
    myAnotherNumericSlice = new formattingSettings.NumUpDown({
        name: "myAnotherNumericSlice",
        displayName: "My Formatting Numeric Slice in group",
        value: 15,
        visible: true
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    visible: boolean = true;
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

Segmento de configuración de formato

El tipo de segmento de configuración de formato consta de dos tipos de segmentos: simples y compuestos.

Cada segmento contiene propiedades de formato. Hay una larga lista de tipos de propiedades de formato disponibles.

Ejemplo de declaración del segmento de configuración de formato de tipo NumUpDown con limitaciones:

El nombre del segmento debe coincidir con el nombre de la propiedad de capabilities.json.

    import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

    myNumericSlice = new formattingSettings.NumUpDown({
        name: "myNumericSlice",
        displayName: "My Formatting Numeric Slice",
        value: 50,
        visible: true,
        options: {
            minValue: {
                type: powerbi.visuals.ValidatorType.Min,
                value: 0,
            },
            maxValue: {
                type: powerbi.visuals.ValidatorType.Max,
                value: 100,
            },
        }
    });

Crear un modelo de panel de formato mediante las utilidades FormattingModel

Abrir el archivo settings.ts.
Cree su propio modelo de configuración de formato con todos sus componentes (tarjetas, grupos, segmentos, propiedades ...), y asígnele el nombre VisualFormattingSettings. Reemplace el código de configuración por el siguiente:

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCompositeCard = formattingSettings.CompositeCard;
import FormattingSettingsSlice = formattingSettings.Slice;
import FormattingSettingsModel = formattingSettings.Model;

export class VisualSettingsModel extends FormattingSettingsModel {
    // Building my visual formatting settings card
    myVisualCard: FormattingSettingsCard = new myVisualCardSettings();

    // Add formatting settings card to cards list in model
    cards: Array<FormattingSettingsCompositeCard> = [this.myVisualCard];
}

class myVisualCardSettings extends FormattingSettingsCompositeCard {
    myNumericSlice = new formattingSettings.NumUpDown({
        name: "myNumericSlice",
        displayName: "My Formatting Numeric Slice",
        value: 100,
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

En el archivo de funcionalidades, agregue los objetos y propiedades de formato

"objects": {
    "myVisualCard": {
        "properties": {
            "myNumericSlice": {
                "type": {
                    "numeric": true 
                }
            }
        }
    }
}

En la clase visual, importe lo siguiente:

import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";
import { VisualFormattingSettingsModel } from "./settings";

Declarar la configuración de formato y el servicio de configuración de formato

   private formattingSettings: VisualFormattingSettingsModel;
   private formattingSettingsService: FormattingSettingsService;

Inicializar el servicio de configuración de formato en el constructor

constructor(options: VisualConstructorOptions) {
    this.formattingSettingsService = new FormattingSettingsService();

    // ...
}

Crear la configuración de formato en la API de actualización mediante el servicio de configuración de formato populateFormattingSettingsModel

public update(options: VisualUpdateOptions) {
    this.formattingSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews);
    // ...
}

Crear el modelo de formato y devolverlo en la API getFormattingModel

public getFormattingModel(): powerbi.visuals.FormattingModel {
    return this.formattingSettingsService.buildFormattingModel(this.formattingSettings);
}

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.

Puede agregar un selector a la propiedad de formato en su objeto descriptor. Este ejemplo se toma de SampleBarChart para puntos de datos de objeto visual personalizados de color mediante selectores de propiedades:

new formattingSettings.ColorPicker({
    name: "fill",
    displayName: dataPoint.category,
    value: { value: dataPoint.color },
    selector: dataViewWildcard.createDataViewWildcardSelector(dataViewWildcard.DataViewWildcardMatchingOption.InstancesAndTotals),
    altConstantSelector: dataPoint.selectionId.getSelector(),
    instanceKind: powerbi.VisualEnumerationInstanceKinds.ConstantOrRule
}

Restablecer la configuración al valor predeterminado

Las utilidades del modelo de formato le permitirán restablecer la configuración al valor predeterminado al agregar automáticamente todos los descriptores de propiedades de formato a la lista de tarjetas de formato de las características para restablecer los descriptores predeterminados revertToDefaultDescriptors.

Puede habilitar el restablecimiento de la configuración del formato desde:

Botón Restablecer al valor predeterminado de la tarjeta de formato
Botón Restablecer toda la configuración al valor predeterminado de la barra superior del panel de formato

Localización

Para obtener más información sobre la característica de localización y para configurar el entorno de localización, consulte Incorporación del idioma local a un objeto visual de Power BI.

Inicializar el servicio de configuración de formato con el administrador de localización en caso de que se requiera localización en el objeto visual personalizado:

constructor(options: VisualConstructorOptions) {

    const localizationManager = options.host.createLocalizationManager();
    this.formattingSettingsService = new FormattingSettingsService(localizationManager);
    
    // ...
}

Agregue displayNameKey o descriptionKey en lugar de displayName y description en el componente de formato adecuado siempre que desee localizar una cadena. Ejemplo para crear un segmento de formato con el nombre para mostrar y la descripción localizados

 myFormattingSlice = new formattingSettings.NumUpDown({
        name: "myFormattingSlice",
        displayNameKey: "myFormattingSlice_Key",
        descriptionKey: "myFormattingSlice_DescriptionKey",
        value: 100
    });

Los valores displayNameKey y descriptionKey deben agregarse a los archivos resources.json.

Compartir a través de