Tutorial: Criar um visual do Power BI usando o React

2024-10-12

Como desenvolvedor, você pode criar seus próprios visuais do Power BI. Esses visuais podem ser usados por você, sua organização ou por terceiros.

Neste tutorial, você desenvolve um visual do Power BI usando o React. O visual exibe um valor de medida formatado dentro de um círculo. O visual tem tamanho adaptável e permite que você personalize as configurações dele.

Neste tutorial, você aprenderá como:

Criar um projeto de desenvolvimento para seu visual.
Desenvolva o seu visual usando o React.
Configurar seu visual para processar dados.
Configure o seu visual para se adaptar às alterações de tamanho.
Defina configurações adaptáveis de cor e borda para o seu visual.

Observação

Para obter o código-fonte completo desse visual, confira Visual de cartão circular do Power BI do React.

Pré-requisitos

Antes de começar a desenvolver seu visual do Power BI, confira se você tem tudo o que está listado nesta seção.

Uma conta do Power BI Pro ou PPU (Premium por usuário) . Caso não tenha uma, inscreva-se em uma avaliação gratuita.
Visual Studio Code (VS Code). O VS Code é um IDE (ambiente de desenvolvimento integrado) ideal para desenvolver aplicativos JavaScript e TypeScript.
Windows PowerShell versão 4 ou posterior (para Windows). ou Terminal (para Mac).
Um ambiente pronto para desenvolver um visual do Power BI. Configure seu ambiente para desenvolver um visual do Power BI.
Este tutorial usa o relatório Análise de vendas dos EUA. Você pode baixar esse relatório e carregá-lo no serviço do Power BI ou usar seu próprio relatório. Se você precisar de mais informações sobre o serviço do Power BI e como carregar arquivos, confira o tutorial Introdução à criação no serviço do Power BI.

Criar um projeto de desenvolvimento

Nesta seção, você cria um projeto para o visual de cartão circular do React.

Abra o PowerShell e navegue até a pasta na qual você deseja criar seu projeto.
Digite o seguinte comando:
```
pbiviz new ReactCircleCard
```
Navegue até a pasta do projeto.
```
cd ReactCircleCard
```
Inicie o visual de cartão circular do React. Agora o visual é executado enquanto é hospedado no computador.
```
pbiviz start
```
Importante

Para impedir que o visual seja executado, digite Ctrl+C no PowerShell e, se solicitado a encerrar o trabalho em lotes, digite Y e pressione Enter.

Exibir o cartão circular do React no serviço do Power BI

Para testar o visual no serviço do Power BI, usaremos o relatório Análise de vendas dos EUA. Você pode baixar esse relatório e carregá-lo no serviço do Power BI.

Você também pode usar seu próprio relatório para testar os visuais.

Observação

Antes de continuar, verifique se você habilitou o modo de desenvolvedor de visuais.

Entre em PowerBI.com e abra o relatório Análise de vendas dos EUA.
Selecione Editar.
Crie uma página para teste clicando no botão Nova página na parte inferior da interface do serviço do Power BI.
No painel Visualizações, selecione Visual do Desenvolvedor.

Esse visual representa o visual personalizado que você está executando em seu computador. Ele só estará disponível quando a configuração depuração de visual personalizado estiver habilitada.
Verifique se um visual foi adicionado à tela do relatório.

Esse é um visual simples que exibe o número de vezes que o método de atualização foi chamado. Neste estágio, o visual não recupera nenhum dado.

Observação

Se o visual exibir uma mensagem de erro de conexão, abra uma nova guia no navegador, navegue até https://localhost:8080/assets e autorize o navegador a usar esse endereço.
Enquanto o novo visual estiver selecionado, vá para o painel Dados , expanda Vendas e selecione Quantidade.
Para testar como o visual está respondendo, redimensione-o e observe se o valor de Atualizar contagem aumenta sempre que você redimensiona o visual.

Configure o React em seu projeto

Nesta seção, você aprende a configurar o React para o seu projeto de visual do Power BI.

Abra o PowerShell e interrompa a execução do visual pressionando Ctrl + C. Se solicitado a encerrar o trabalho em lotes, digite Y e pressione Enter.

Instalar o React

Para instalar as dependências reajam necessárias, abra o PowerShell na pasta ReactCircleCard e execute o seguinte comando:

npm i react react-dom

Instalar definições de tipo do React

Para instalar definições de tipo para o React, abra o PowerShell na pasta reactCircleCard e execute o seguinte comando:

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

Criar uma classe de componente do React

Siga estas etapas para criar uma classe de componente do React.

Abra o VS Code e navegue até a pasta reactCircleCard.
Crie um arquivo selecionando Arquivo>Novo Arquivo.

Copie o código a seguir para esse novo arquivo.

import * as React from "react";

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

export default ReactCircleCard;

Selecione Salvar Como e navegue até a pasta src.
Salve o arquivo conforme mostrado abaixo:
- No campo Nome do arquivo, insira componente.
- No menu suspenso Salvar como tipo, selecione TypeScript React.

Adicionar o React ao arquivo do visual

Substitua o código no arquivo visual.ts pelo código que permite o uso do React.

Na pasta src, abra visual.ts e substitua o código no arquivo pelo seguinte 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) {

    }
}

Observação

Como as configurações padrão de TypeScript do Power BI não reconhecem arquivos tsx do React, o VS Code realça component como um erro.

Para renderizar o componente, adicione o elemento HTML de destino para visual.ts. Esse elemento é HTMLElement em VisualConstructorOptions, que é passado para o construtor.

Na pasta src, abra visual.ts.
Adicione o código a seguir à classe Visual:

private target: HTMLElement;
private reactRoot: React.ComponentElement<any, any>;

Adicione as seguintes linhas ao construtor VisualConstructorOptions:

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

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

Agora, o arquivo visual.ts deverá ser semelhante a este:

"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) {

    }
}

Salve o visual.ts.

Editar o arquivo tsconfig

Edite o tsconfig.json para funcionar com o React.

Na pasta reactCircleCard, abra o arquivo tsconfig.json e adicione duas linhas ao início do item compilerOptions.

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

O arquivo tsconfig.json agora deve ter esta aparência, e o erro component em visual.ts deve ter 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"
    ]
}

Salve o tsconfig.json.

Testar o seu visual

Abra o PowerShell na pasta CircleCardVisual e execute o seu projeto:

pbiviz start

Quando você adiciona um novo Visual de Desenvolvedor ao seu relatório no serviço do Power BI, ele se parece com isso:

Captura de tela mostrando a mensagem olá do React no visual do desenvolvedor recém-criado no serviço do Power BI.

Configurar o campo de dados do visual

Configure o arquivo de funcionalidades do visual para que apenas um campo de dados possa ser enviado para o campo Dados de medida do visual.

No VS Code, na pasta reactCircleCard, abra capabilities.json.
O ReactCircleCard exibe apenas um valor, Measure Data. Remova o objeto Category Data de dataRoles.

Depois de remover o objeto Category Data, a chave dataRoles terá esta aparência:
```
"dataRoles": [
    {
        "displayName": "Measure Data",
        "name": "measure",
        "kind": "Measure"
    }
],
```
Remova todo o conteúdo da chave objects (você adicionará o conteúdo posteriormente).

Depois de remover o conteúdo, a chave objects fica assim:
```
"objects": {},
```

Substitua a propriedade dataViewMappings pelo código a seguir. max: 1 em measure especifica que apenas um campo de dados pode ser enviado para o campo de Dados de medida do visual.

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

Salve as alterações feitas a capabilities.json.
Verifique se pbiviz start o está em execução e, no serviço do Power BI, atualize o seu visual Cartão Circular do React. O campo Dados de medida pode aceitar apenas um campo de dados, conforme especificado por max: 1.

Atualizar o estilo do visual

Nesta seção, você transforma a forma do visual em um círculo. Use o arquivo visual.less para controlar o estilo do seu visual.

Na pasta style, abra visual.less.

Substitua o conteúdo de visual.less com o código a seguir.

.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;
}

Salve visual.less.

Configure o visual para receber propriedades do Power BI

Nesta seção, você configura o visual para receber dados do Power BI e enviará atualizações para as instâncias no arquivo component.tsx.

Renderizar dados usando o React

Você pode renderizar dados usando o React. O componente pode exibir dados de seu próprio estado.

No VS Code, na pasta reactCircleCard, abra component.tsx.

Substitua o conteúdo de component.tsx pelo código a seguir.

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>
        )
    }
}

Salve component.tsx.

Definir o seu visual para receber dados

Os visuais recebem dados como um argumento do método update. Nesta seção, você atualiza esse método para receber dados.

O código a seguir seleciona textLabel e textValue de DataView e, caso os dados existam, atualiza o estado do componente.

No VS Code, na pasta src, abra visual.ts.
Substitua a linha import ReactCircleCard from "./component"; pelo seguinte código:
```
import { ReactCircleCard, initialState } from "./component";
```

Adicione o seguinte código ao update método.

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();
}

Crie um método clear adicionando o código a seguir abaixo do método update.
```
private clear() {
    ReactCircleCard.update(initialState);
}
```
Salve o visual.ts.

Definir o visual para envio de dados

Nesta seção, você atualiza o visual para enviar atualizações para instâncias no arquivo component.

No VS Code, na pasta src, abra component.tsx.

Adicione o código a seguir à classe 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;
}

Salve component.tsx.

Exibir as alterações no visual

Teste seu visual de cartão circular do React para exibir as alterações feitas.

Verifique se pbiviz start o está em execução e, no serviço do Power BI, atualize o seu visual Cartão Circular do React.
Adicione Vendas ao campo Dados de medida do visual.

Captura de tela do valor de vendas exibido no visual do cartão circular do React no serviço do Power BI.

Tornar o seu visual redimensionável

Atualmente, o seu visual tem largura e altura fixas. Para tornar o visual redimensionável, você precisa definir a variável size em ambos os arquivos visual.ts e component.tsx. Nesta seção, você torna o visual redimensionável.

Depois de concluir as etapas descritas nesta seção, o diâmetro circular em seu visual corresponderá ao tamanho mínimo da largura ou altura, e você poderá redimensioná-lo no serviço do Power BI.

Configurar o arquivo visual.ts

Obtenha o tamanho atual do visor do visual do objeto options.

No VS Code, na pasta src, abra visual.ts.
Insira este código para importar a interface IViewport.
```
import IViewport = powerbi.IViewport;
```
Adicione a propriedade viewport à classe visual.
```
private viewport: IViewport;
```

No método update, antes de ReactCircleCard.update, adicione o código a seguir.

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

No método update, em ReactCircleCard.update, adicione size.
```
size,
```
Salve o visual.ts.

Configurar o arquivo component.tsx

No VS Code, na pasta src, abra component.tsx.
Adicione o código a seguir a export interface State.
```
size: number
```
Adicione o código a seguir a export const initialState: State.
```
size: 200
```
No método render, faça as seguintes alterações ao código:
1. Adicione size a const { textLabel, textValue, size } = this.state;. Essa declaração agora deve ter esta aparência:
```
const { textLabel, textValue, size } = this.state;
```
2. Adicione o código a seguir acima de return.
```
const style: React.CSSProperties = { width: size, height: size };
```
3. Substitua a primeira linha de return<div className="circleCard"> por:
```
<div className="circleCard" style={style}>
```
Salve component.tsx.

Configurar o arquivo de visual

No VS Code, na pasta style, abra visual.less.
Em .circleCard, substitua width e height por min-width e min-height.
```
min-width: 200px;
min-height: 200px;
```
Salve visual.less.

Tornar o visual do Power BI personalizável

Nesta seção, você adicionar capacidade de personalizar seu visual, permitindo que os usuários façam alterações na cor e na espessura da borda.

Adicionar cor e espessura ao arquivo de funcionalidades

Adicione a cor e a espessura da borda à propriedade object em capabilities.json.

No VS Code, na pasta reactCircleCard, abra capabilities.json.

Adicione as seguintes configurações à propriedade objects.

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

Salve capabilities.json.

Adicionar uma classe de configurações de formatação de círculo ao arquivo de configurações

Adicione as configurações de formatação Circle a settings.ts. Para obter mais informações sobre como criar configurações de modelo de formatação, confira os utilitários de formatação.

No VS Code, na pasta src, abra settings.ts.

Substitua o código em settings.ts pelo seguinte código:

"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];
}

Salve settings.ts.

Adicionar um método para aplicar as configurações visuais

Adicione o método getFormattingModel usado para aplicar as configurações visuais e as importações necessárias ao arquivo visual.ts.

No VS Code, na pasta src, abra visual.ts.

Adicione estas instruções import na parte superior de visual.ts.

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

Adicione a declaração a seguir a Visual.

private formattingSettings: VisualFormattingSettingsModel;
private formattingSettingsService: FormattingSettingsService;

Adicione o método getFormattingModel a Visual.

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

Na classe Visual, adicione a linha de código a seguir a constructor para inicializar formattingSettingsService
```
    this.formattingSettingsService = new FormattingSettingsService();
```

Na classe Visual, adicione o código a seguir a update para atualizar as configurações de formatação visual aos valores de propriedades de formatação mais recentes.

Adicione este código à instrução if depois de const size = Math.min(width, height);.

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

Adicione este código a ReactCircleCard.update após size:

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

Salve o visual.ts.

Editar o arquivo de componente

Edite o arquivo de componente para que ele possa renderizar as alterações na cor e espessura da borda do visual.

No VS Code, na pasta src, abra component.tsx.

Adicione estes valores a State:

background?: string,
borderWidth?: number

No método render, substitua as seguintes linhas 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 };
```
Salve component.tsx.

Examinar as alterações

Experimente com as possibilidades de cor e espessura da borda do visual, que agora você pode controlar.

Verifique se pbiviz start o está em execução e, no serviço do Power BI, atualize o seu visual Cartão Circular do React.
Selecione a guia Formato e expanda Círculo.
Ajuste as configurações de Cor e Espessura do visual e examine o efeito delas no visual.

Uma captura de tela do Visual do cartão de círculo reagir no serviço do Power BI, mostrando as opções de formato de espessura e borda da cor.

Compartilhar via

Tutorial: Criar um visual do Power BI usando o React

Pré-requisitos

Criar um projeto de desenvolvimento

Exibir o cartão circular do React no serviço do Power BI

Configure o React em seu projeto

Instalar o React

Instalar definições de tipo do React

Criar uma classe de componente do React

Adicionar o React ao arquivo do visual

Editar o arquivo tsconfig

Testar o seu visual

Configurar o campo de dados do visual

Atualizar o estilo do visual

Configure o visual para receber propriedades do Power BI

Renderizar dados usando o React

Definir o seu visual para receber dados

Definir o visual para envio de dados

Exibir as alterações no visual

Tornar o seu visual redimensionável

Configurar o arquivo visual.ts

Configurar o arquivo component.tsx

Configurar o arquivo de visual

Tornar o visual do Power BI personalizável

Adicionar cor e espessura ao arquivo de funcionalidades

Adicionar uma classe de configurações de formatação de círculo ao arquivo de configurações

Adicionar um método para aplicar as configurações visuais

Editar o arquivo de componente

Examinar as alterações

Conteúdo relacionado

Comentários

Recursos adicionais