Compartir a través de

Tutorial: Creación de un objeto visual de Power BI mediante React

Como desarrollador, puede crear sus propios objetos visuales de Power BI. Estos objetos visuales los puede utilizar usted, su organización o terceros.

En este tutorial, desarrollará un objeto visual de Power BI con React. El objeto visual muestra el valor de una medida con formato dentro de un círculo. El objeto visual tiene un tamaño adaptable y permite personalizar su configuración.

En este tutorial, obtendrá información sobre cómo:

  • Crear un proyecto de desarrollo para el objeto visual.
  • Desarrollar el objeto visual usando React.
  • Configurar el objeto visual para procesar los datos.
  • Configurar el objeto visual para que se adapte a los cambios de tamaño.
  • Configurar valores de color y borde adaptables para el objeto visual.

Nota

Para obtener el código fuente completo de este objeto visual, vea la página sobre el objeto visual Circle Card de Power BI basado en React.

Requisitos previos

Antes de empezar a desarrollar el objeto visual de Power BI, compruebe que tiene todo lo que se indica en esta sección.

Creación de un proyecto de desarrollo

En esta sección, creará un proyecto para el objeto visual Circle Card de React.

  1. Abra PowerShell y navegue hasta la carpeta en la que desea crear el proyecto.

  2. Escriba el comando siguiente:

    pbiviz new ReactCircleCard

  3. Vaya a la carpeta del proyecto.

    cd ReactCircleCard

  4. Inicie el objeto visual Circle Card basado en React. Su objeto visual ahora se ejecuta mientras está hospedado en el equipo.

    pbiviz start

    Importante

    Para detener la ejecución del objeto visual, en PowerShell, escriba Ctrl+C y, si el sistema le pregunta si desea terminar el trabajo por lotes, escriba Y y presione Entrar.

Visualización del objeto visual Circle Card de React en el servicio Power BI

Para probar el objeto visual en el servicio Power BI, usaremos el informe US Sales Analysis. Puede descargar este informe y cargarlo en servicio Power BI.

También puede usar su propio informe para probar el objeto visual.

Nota:

Antes de continuar, compruebe que ha habilitado el modo de desarrollador de objetos visuales.

  1. Inicie sesión en PowerBI.com y abra el informe US Sales Analysis.

  2. Seleccione Editar.

    Captura de pantalla de la opción de edición en servicio Power BI.

  3. Cree una nueva página para realizar pruebas; para ello, haga clic en el botón Nueva página situado en la parte inferior de la interfaz del servicio Power BI.

    Captura de pantalla del botón nueva página en servicio Power BI.

  4. Seleccione el Objeto visual de desarrollador en el panel Visualizaciones.

    Captura de pantalla del objeto visual de desarrollador en el panel Visualizaciones.

    Este objeto visual representa el objeto visual personalizado que se está ejecutando en el equipo. Solo está disponible cuando está habilitada la opción de depuración de objetos visuales personalizados.

  5. Compruebe que se ha agregado un objeto visual al lienzo del informe.

    Captura de pantalla del nuevo objeto visual agregado al informe.

    Este es un objeto visual simple que muestra el número de veces que se ha llamado al método update. En esta fase, el objeto visual todavía no recupera los datos.

    Nota

    Si el objeto visual muestra un mensaje de error de conexión, abra una nueva pestaña en el explorador, vaya a https://localhost:8080/assets y autorice al explorador para que use esta dirección.

    Captura de pantalla del nuevo objeto visual que muestra un error de conexión.

  6. Mientras se selecciona el nuevo objeto visual, vaya al panel Datos , expanda Ventas y seleccione Cantidad.

    Captura de pantalla del campo cantidad de servicio Power BI en la tabla sales del informe de análisis de ventas de EE. UU.

  7. Para probar cómo responde el objeto visual, cambie su tamaño y observe que el valor Recuento de actualizaciones: se incrementa cada vez que lo hace.

    Captura de pantalla del nuevo objeto visual que muestra un número de recuento de actualizaciones diferente, después de cambiar el tamaño.

Configuración de React en el proyecto

En esta sección, verá cómo configurar React para el proyecto del objeto visual de Power BI.

Abra PowerShell y escriba Ctrl+C para detener la ejecución del objeto visual. Cuando el sistema le pregunte si desea terminar el trabajo por lotes, escriba S y presione Entrar.

Instalación de React

Para instalar las dependencias necesarias de React, abra PowerShell en la carpeta ReactCircleCard y ejecute el siguiente comando:

npm i react react-dom

Instalación de las definiciones de tipos de React

Para instalar las definiciones de tipos de React, abra PowerShell en la carpeta reactCircleCard y ejecute el siguiente comando:

npm i @types/react @types/react-dom

Creación de una clase de componente de React

Siga estos pasos para crear una clase de componente de React.

  1. Abra VS Code y vaya a la carpeta reactCircleCard.

  2. Seleccione Archivo>Nuevo archivo para crear un archivo nuevo.

  3. Copie el siguiente código en el nuevo archivo.

    import * as React from "react";

export class ReactCircleCard extends React.Component<{}>{
    render(){
        return (
            <div className="circleCard">
                Hello, React!
            </div>
        )
    }
}

export default ReactCircleCard;

  4. Seleccione Guardar como y vaya a la carpeta src.

  5. Guarde el archivo como se indica a continuación:

    • En el campo Nombre de archivo, escriba component.
    • En el menú desplegable Guardar como tipo, seleccione TypeScript React.

Agregación de React al archivo del objeto visual

Reemplace el código del archivo visual.ts por código que permita el uso de React.

  1. En la carpeta src, abra el archivo visual.ts y reemplace el código del archivo por el siguiente código:

    "use strict";
import powerbi from "powerbi-visuals-api";

import DataView = powerbi.DataView;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import IVisual = powerbi.extensibility.visual.IVisual;

// Import React dependencies and the added component
import * as React from "react";
import * as ReactDOM from "react-dom";
import ReactCircleCard from "./component";

import "./../style/visual.less";

export class Visual implements IVisual {

    constructor(options: VisualConstructorOptions) {

    }

    public update(options: VisualUpdateOptions) {

    }
}

    Nota

    Puesto que la configuración predeterminada de TypeScript en Power BI no reconoce los archivos tsx de React, VS Code resalta component como un error.

  2. Para representar el componente, agregue el elemento HTML de destino al archivo visual.ts. Este elemento es HTMLElement en VisualConstructorOptions, que se pasa al constructor.

    1. En la carpeta src, abra el archivo visual.ts.

    2. Agregue el siguiente código a la clase Visual:

    private target: HTMLElement;
private reactRoot: React.ComponentElement<any, any>;
    1. Agregue las siguientes líneas al constructor VisualConstructorOptions:
    this.reactRoot = React.createElement(ReactCircleCard, {});
this.target = options.element;

ReactDOM.render(this.reactRoot, this.target);

    Ahora el archivo visual.ts debería tener el siguiente aspecto:

    "use strict";
import powerbi from "powerbi-visuals-api";

import DataView = powerbi.DataView;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import IVisual = powerbi.extensibility.visual.IVisual;
import * as React from "react";
import * as ReactDOM from "react-dom";
import ReactCircleCard from "./component";    

import "./../style/visual.less";

export class Visual implements IVisual {
    private target: HTMLElement;
    private reactRoot: React.ComponentElement<any, any>;

    constructor(options: VisualConstructorOptions) {
        this.reactRoot = React.createElement(ReactCircleCard, {});
        this.target = options.element;

        ReactDOM.render(this.reactRoot, this.target);
    }

    public update(options: VisualUpdateOptions) {

    }
}

  3. Guarde el archivo visual.ts.

Edición del archivo tsconfig

Edite el archivo tsconfig.json para que funcione con React.

  1. En la carpeta reactCircleCard, abra el archivo tsconfig.json y agregue dos líneas al principio del elemento compilerOptions.

    "jsx": "react",
"types": ["react", "react-dom"],

    Ahora el archivo tsconfig.json debería tener el siguiente aspecto y el error component de visual.ts debería haber desaparecido.

    {
    "compilerOptions": {
        "jsx": "react",
        "types": ["react", "react-dom"],
        "allowJs": false,
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true,
        "target": "es6",
        "sourceMap": true,
        "outDir": "./.tmp/build/",
        "moduleResolution": "node",
        "declaration": true,
        "lib": [
            "es2015",
            "dom"
        ]
    },
    "files": [
        "./src/visual.ts"
    ]
}

  2. Guarde el archivo tsconfig.json.

Prueba del objeto visual

Abra PowerShell en la carpeta CircleCardVisual y ejecute el proyecto:

pbiviz start

Cuando agregue un nuevo objeto visual de desarrollador al informe en el servicio Power BI, tendrá el siguiente aspecto:

Captura de pantalla que muestra el mensaje

Configuración del campo de datos del objeto visual

Configure el archivo de características del objeto visual para que solo se pueda enviar un campo de datos al campo Measure Data del objeto visual.

  1. En VS Code, en la carpeta reactCircleCard, abra el archivo capabilities.json.

  2. ReactCircleCard muestra un único valor, Measure Data. Quite el objeto Category Data de dataRoles.

    Después de quitar el objeto Category Data, la clave dataRoles tiene el siguiente aspecto:

    "dataRoles": [
    {
        "displayName": "Measure Data",
        "name": "measure",
        "kind": "Measure"
    }
],

  3. Quite todo el contenido de la clave objects (lo rellenará más adelante).

    Después de quitarle el contenido, la clave objects tendrá el siguiente aspecto:

    "objects": {},

  4. Reemplace la propiedad dataViewMappings por el código siguiente. max: 1 en measure especifica que solo se puede enviar un campo de datos al campo Measure Data del objeto visual.

    "dataViewMappings": [
    {
        "conditions": [
            {
                "measure": {
                    "max": 1
                }
            }
        ],
        "single": {
            "role": "measure"
        }
    }
]

  5. Guarde los cambios que ha realizado en el archivo capabilities.json.

  6. Compruebe que pbiviz start se esté ejecutando y, en el servicio Power BI, actualice el objeto visual React Circle Card. El campo Measure Data solo puede aceptar un campo de datos, como se especifica en max: 1.

    Captura de pantalla que muestra el campo Measure Data en la tarjeta circular creada con React en el servicio Power BI.

Actualización del estilo del objeto visual

En esta sección, convertirá la forma del objeto visual en un círculo. Use el archivo visual.less para controlar el estilo del objeto visual.

  1. Desde la carpeta style, abra el archivo visual.less.

  2. Reemplace el contenido de visual.less por el siguiente código.

    .circleCard {
    position: relative;
    box-sizing: border-box;
    border: 1px solid #000;
    border-radius: 50%;
    width: 200px;
    height: 200px;
}

p {
    text-align: center;
    line-height: 30px;
    font-size: 20px;
    font-weight: bold;

    position: relative;
    top: -30px;
    margin: 50% 0 0 0;
}

  3. Guarde el archivo visual.less.

Configuración del objeto visual para que reciba las propiedades de Power BI

En esta sección, configurará el elemento visual para que reciba datos de Power BI y envíe actualizaciones a las instancias del archivo component.tsx.

Representación de los datos mediante React

Puede representar datos mediante React. El componente puede mostrar los datos de su propio estado.

  1. En VS Code, en la carpeta reactCircleCard, abra el archivo component.tsx.

  2. Reemplace el contenido de component.tsx por el siguiente código.

    import * as React from "react";

export interface State {
    textLabel: string,
    textValue: string
}

export const initialState: State = {
    textLabel: "",
    textValue: ""
}

export class ReactCircleCard extends React.Component<{}, State>{
    constructor(props: any){
        super(props);
        this.state = initialState;
    }

    render(){
        const { textLabel, textValue } = this.state;

        return (
            <div className="circleCard">
                <p>
                    {textLabel}
                    <br/>
                    <em>{textValue}</em>
                </p>
            </div>
        )
    }
}

  3. Guarde el archivo component.tsx.

Configuración del objeto visual para recibir datos

Los objetos visuales reciben los datos como un argumento del método update. En esta sección, actualizará este método para recibir datos.

El código siguiente selecciona textLabel y textValue de DataView y, si los datos existen, actualizará el estado del componente.

  1. En VS Code, en la carpeta src, abra el archivo visual.ts.

  2. Reemplace la línea import ReactCircleCard from "./component"; con el código siguiente:

    import { ReactCircleCard, initialState } from "./component";

  3. Agregue el siguiente código al método update.

    if(options.dataViews && options.dataViews[0]){
    const dataView: DataView = options.dataViews[0];

    ReactCircleCard.update({
        textLabel: dataView.metadata.columns[0].displayName,
        textValue: dataView.single.value.toString()
    });
} else {
    this.clear();
}

  4. Cree un método clear agregando el siguiente código delante del método update.

    private clear() {
    ReactCircleCard.update(initialState);
}

  5. Guarde el archivo visual.ts.

Configuración del objeto visual para enviar datos

En esta sección, actualizará el objeto visual para enviar actualizaciones a las instancias del archivo component.

  1. En VS Code, en la carpeta src, abra el archivo component.tsx.

  2. Agregue el siguiente código a la clase ReactCircleCard:

    private static updateCallback: (data: object) => void = null;

public static update(newState: State) {
    if(typeof ReactCircleCard.updateCallback === 'function'){
        ReactCircleCard.updateCallback(newState);
    }
}

public state: State = initialState;

public componentWillMount() {
        ReactCircleCard.updateCallback = (newState: State): void => { this.setState(newState); };
}

public componentWillUnmount() {
    ReactCircleCard.updateCallback = null;
}

  3. Guarde el archivo component.tsx.

Visualización de los cambios realizados en el objeto visual

Pruebe el objeto visual Circle Card basado en React para ver los cambios que ha realizado.

  1. Compruebe que pbiviz start se esté ejecutando y, en el servicio Power BI, actualice el objeto visual React Circle Card.

  2. Agregue Sales al campo Measure Data del objeto visual.

Captura de pantalla del valor de venta que se muestra en el objeto visual Circle Card de React en el servicio Power BI.

Configuración del objeto visual para que se le pueda cambiar el tamaño

Actualmente, el objeto visual tiene un ancho y un alto fijos. Para cambiar el tamaño del objeto visual, debe definir la variable size en los archivos visual.ts y component.tsx. En esta sección, configurará el objeto visual para que se le pueda cambiar el tamaño.

Después de realizar los pasos descritos en esta sección, el diámetro del círculo del objeto visual será el tamaño mínimo de ancho o alto, y podrá cambiarle el tamaño en el servicio Power BI.

Configuración del archivo visual.ts

Obtenga el tamaño actual de la ventanilla del objeto visual a partir del objeto options.

  1. En VS Code, en la carpeta src, abra el archivo visual.ts.

  2. Inserte este código para importar la interfaz IViewport.

    import IViewport = powerbi.IViewport;

  3. Agregue la propiedad viewport a la clase visual.

    private viewport: IViewport;

  4. En el método update, antes de ReactCircleCard.update, agregue el siguiente código.

    this.viewport = options.viewport;
const { width, height } = this.viewport;
const size = Math.min(width, height);

  5. En el método update, en ReactCircleCard.update, agregue size.

    size,

  6. Guarde el archivo visual.ts.

Configuración del archivo component.tsx

  1. En VS Code, en la carpeta src, abra el archivo component.tsx.

  2. Agregue el siguiente código a export interface State.

    size: number

  3. Agregue el siguiente código a export const initialState: State.

    size: 200

  4. En el método render, realice los siguientes cambios en el código:

    1. Agregue size a const { textLabel, textValue, size } = this.state;. Ahora esta declaración debería tener el siguiente aspecto:

      const { textLabel, textValue, size } = this.state;

    2. Agregue el siguiente código encima de return.

      const style: React.CSSProperties = { width: size, height: size };

    3. Reemplace la primera línea return<div className="circleCard"> por:

      <div className="circleCard" style={style}>

  5. Guarde el archivo component.tsx.

Configuración del archivo del objeto visual

  1. En VS Code, en la carpeta style, abra el archivo visual.less.

  2. En .circleCard, reemplace width y height por min-width y min-height.

    min-width: 200px;
min-height: 200px;

  3. Guarde el archivo visual.less.

Hacer que el objeto visual de Power BI sea personalizable

En esta sección, agregará la capacidad para personalizar el objeto visual, de modo que los usuarios puedan cambiarle el color y el grosor del borde.

Agregación del color y el grosor al archivo de características

Agregue el color y el grosor del borde a la propiedad object en el archivo capabilities.json.

  1. En VS Code, en la carpeta reactCircleCard, abra el archivo capabilities.json.

  2. Agregue las siguientes configuraciones a la propiedad objects.

    "circle": {
    "properties": {
       "circleColor": {
            "type": {
                "fill": {
                    "solid": {
                        "color": true
                    }
                }
            }
        },
        "circleThickness": {
            "type": {
                "numeric": true
            }
        }
    }
}

  3. Abra el archivo capabilities.json.

Incorporación de una clase de configuración de formato Circle al archivo de configuración

Agregue la configuración de formato Circle a settings.ts. Para obtener más información sobre cómo crear la configuración del modelo de formato, consulte las utilidades de formato.

  1. En VS Code, en la carpeta src, abra el archivo settings.ts.

  2. Reemplace el código de settings.ts por el siguiente:

    "use strict";

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

import FormattingSettingsCard = formattingSettings.SimpleCard;
import FormattingSettingsSlice = formattingSettings.Slice;
import FormattingSettingsModel = formattingSettings.Model;

/**
* Circle Formatting Card
*/
class CircleCardSettings extends FormattingSettingsCard {
    circleColor = new formattingSettings.ColorPicker({
        name: "circleColor", // circle color name should match circle color property name in capabilities.json
        displayName: "Color",
        description: "The fill color of the circle.",
        show: true,
        value: { value: "white" }
    });

    circleThickness = new formattingSettings.NumUpDown({
        name: "circleThickness", // circle thickness name should match circle color property name in capabilities.json
        displayName: "Thickness",
        description: "The circle thickness.",
        show: true,
        value: 2
    });

    name: string = "circle"; // circle card name should match circle object name in capabilities.json
    displayName: string = "Circle";
    show: boolean = true;
    slices: Array<FormattingSettingsSlice> = [this.circleColor, this.circleThickness];
}

/**
* visual settings model class
*
*/
export class VisualFormattingSettingsModel extends FormattingSettingsModel {
    // Create formatting settings model circle formatting card
    circleCard = new CircleCardSettings();

    cards = [this.circleCard];
}

  3. Guarde el archivo settings.ts.

Agregación de un método para aplicar la configuración del objeto visual

Agregue el método getFormattingModel, que se usa para aplicar la configuración del objeto visual, y las importaciones necesarias en el archivo visual.ts.

  1. En VS Code, en la carpeta src, abra el archivo visual.ts.

  2. Agregue estas instrucciones import al principio del archivo visual.ts.

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

  3. Agregue la siguiente declaración a Visual.

    private formattingSettings: VisualFormattingSettingsModel;
private formattingSettingsService: FormattingSettingsService;

  4. Agregue el método getFormattingModel a Visual.

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

  5. En la clase Visual, agregue la siguiente línea de código a constructor para inicializar formattingSettingsService.

        this.formattingSettingsService = new FormattingSettingsService();

  6. En la clase Visual, agregue el código siguiente a update para actualizar la configuración de formato del objeto visual a los valores de propiedad de formato más recientes.

    1. Agregue este código a la instrucción if después de const size = Math.min(width, height);.

      this.formattingSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews[0]);
const circleSettings = this.formattingSettings.circleCard;

    2. Agregue este código a ReactCircleCard.update después de size:

      borderWidth: circleSettings.circleThickness.value,
background: circleSettings.circleColor.value.value,
}

  7. Guarde el archivo visual.ts.

Edición del archivo component

Edite el archivo component para que pueda representar los cambios de color y grosor del borde del objeto visual.

  1. En VS Code, en la carpeta src, abra el archivo component.tsx.

  2. Agregue estos valores a State:

    background?: string,
borderWidth?: number

  3. En el método render, reemplace las siguientes líneas de código:

    1. const { textLabel, textValue, size } = this.state; por:

      const { textLabel, textValue, size, background, borderWidth } = this.state;

    2. const style: React.CSSProperties = { width: size, height: size }; por:

      const style: React.CSSProperties = { width: size, height: size, background, borderWidth };

  4. Guarde el archivo component.tsx.

Revisar los cambios

Experimente con el color y el grosor del borde del objeto visual, que ahora puede controlar.

  1. Compruebe que pbiviz start se esté ejecutando y, en el servicio Power BI, actualice el objeto visual React Circle Card.

  2. Seleccione la pestaña Formato y expanda Circle.

  3. Ajuste los valores de Color y Thickness del objeto visual, y revise el efecto en el objeto.

Captura de pantalla del objeto visual Circle Card basado en React en el servicio Power BI, que muestra las opciones de formato de color y grosor del borde.

Contenido relacionado