Tutorial: Criar um visual do Power BI usando o React

Como desenvolvedor, você pode criar seus próprios visuais do Power BI. Estes elementos visuais podem ser utilizados por si, pela 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 personalizar suas configurações.

Neste tutorial, irá aprender a:

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

Nota

Para obter o código-fonte completo deste visual, consulte React circle card Power BI visual.

Pré-requisitos

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

Uma conta Power BI Pro ou Premium por usuário (PPU). Se não tiver uma, inscreva-se numa avaliação gratuita.
Código do Visual Studio (VS Code). O VS Code é um ambiente de desenvolvimento integrado (IDE) ideal para o desenvolvimento de aplicações 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 precisar de mais informações sobre o serviço do Power BI e o carregamento de ficheiros, consulte 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 do cartão circular React.

Abra o PowerShell e navegue até a pasta na qual você deseja criar seu projeto.
Introduza o seguinte comando:
```
pbiviz new ReactCircleCard
```
Navegue até a pasta do projeto.
```
cd ReactCircleCard
```
Inicie o visual do cartão de círculo React. O seu visual está agora a ser executado enquanto está alojado no seu computador.
```
pbiviz start
```
Importante

Para interromper a execução do visual, no PowerShell, digite Ctrl+C e, se solicitado a encerrar o trabalho em lote, digite Y e pressione Enter.

Exibir o cartão de círculo 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 o visual.

Nota

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

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

Este visual representa o visual personalizado que você está executando no seu computador. Ele só está disponível quando a configuração de depuração visual personalizada está ativada.
Verifique se um visual foi adicionado à tela de relatório.

Este é um visual simples que exibe o número de vezes que seu método de atualização foi chamado. Nesta fase, o visual não recupera nenhum dado.

Nota

Se o visual exibir uma mensagem de erro de conexão, abra uma nova guia no navegador, navegue até https://localhost:8080/assetse 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 que o valor de contagem de atualizações aumenta sempre que você redimensiona o visual.

Configurar o React no seu projeto

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

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

Instalar o React

Para instalar as dependências necessárias do React, 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 React

Siga estas etapas para criar uma classe de componente React.

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

Copie o código a seguir para o 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 da seguinte maneira:
- No campo Nome do arquivo, insira o componente.
- No menu suspenso Salvar como tipo, selecione TypeScript React.

Adicionar React ao arquivo visual

Substitua o código no arquivo visual.ts por um código que permita o uso do React.

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

    }
}

Nota

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

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

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

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

Adicione as seguintes linhas ao VisualConstructorOptions construtor:

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

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

Seu arquivo visual.ts agora deve ter esta aparência:

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

    }
}

Poupe visual.ts.

Editar o arquivo tsconfig

Edite o tsconfig.json para trabalhar com o React.

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

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

Seu arquivo tsconfig.json agora deve ter esta aparência, e o component erro em visual.ts deve desaparecer.

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

Poupe tsconfig.json.

Teste o seu visual

Abra o PowerShell na pasta CircleCardVisual e execute seu projeto:

pbiviz start

Quando você adiciona um novo Visual do Desenvolvedor ao seu relatório no serviço do Power BI, ele tem a seguinte aparência:

Captura de tela mostrando a mensagem hello React no visual do desenvolvedor recém-criado no serviço Power B I.

Configurar o campo de dados do seu visual

Configure o arquivo de recursos do visual para que apenas um campo de dados possa ser enviado para o campo de dados Medir do visual.

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

Depois de remover o Category Data objeto, a dataRoles chave tem esta aparência:
```
"dataRoles": [
    {
        "displayName": "Measure Data",
        "name": "measure",
        "kind": "Measure"
    }
],
```
Remova todo o conteúdo da objects chave (preenchê-la-á mais tarde).

Depois de remover o conteúdo, a chave tem o objects seguinte aspeto:
```
"objects": {},
```

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

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

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

Atualize 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 pelo 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.

Definir 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 visual para receber dados

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

O código a seguir seleciona textLabel e textValue de , e se os dados existirem, atualiza o estado do DataViewcomponente.

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

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

Definir o visual para enviar dados

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

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

Adicione o seguinte código à ReactCircleCard classe:

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.

Ver as alterações ao visual

Teste o visual do seu React Circle Card para ver as alterações feitas.

Verifique se pbiviz start está em execução e, no serviço do Power BI, atualize o visual do React Circle Card .
Adicione Vendas ao campo de dados Medir do visual.

Captura de ecrã do valor de vendas apresentado no visual do cartão de círculo de reação no serviço do Power BI.

Torne o seu visual redimensionável

Atualmente, o seu visual tem largura e altura fixas. Para tornar o visual redimensionável, você precisa definir a size variável nos 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 do círculo em seu visual corresponderá ao tamanho mínimo de largura ou altura e você poderá redimensioná-lo no serviço do Power BI.

Configurar o arquivo visual.ts

Obtenha o tamanho atual da janela de visualização visual do options objeto.

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

update No método, 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);

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

Configurar o arquivo component.tsx

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

Configurar o arquivo visual

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

Torne o seu visual do Power BI personalizável

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

Adicionar cor e espessura ao arquivo de recursos

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

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

Adicione as seguintes configurações à objects propriedade.

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

Poupe capabilities.json.

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

Adicione as Circle configurações de formatação ao settings.ts. Para obter mais informações sobre como criar configurações de modelo de formatação, consulte formatting utils.

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

Substitua o código no 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 configurações visuais

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

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

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

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

Adicione a seguinte declaração ao Visual.

private formattingSettings: VisualFormattingSettingsModel;
private formattingSettingsService: FormattingSettingsService;

Adicione o getFormattingModel método a Visual.

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

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

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

Adicione este código à instrução if após 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 depois :size

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

Poupe visual.ts.

Editar o arquivo do componente

Edite o arquivo do componente para que ele possa renderizar as alterações na cor e na 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, substitua render as seguintes linhas de código:
1. const { textLabel, textValue, size } = this.state; com:
```
const { textLabel, textValue, size, background, borderWidth } = this.state;
```
2. const style: React.CSSProperties = { width: size, height: size }; com:
```
const style: React.CSSProperties = { width: size, height: size, background, borderWidth };
```
Salve component.tsx.

Reveja as suas alterações

Experimente a cor e a espessura da borda do visual, que agora você pode controlar.

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

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

Feedback

Esta página foi útil?

Last updated on 2025-12-15

Partilhar via

Tutorial: Criar um visual do Power BI usando o React

Pré-requisitos

Criar um projeto de desenvolvimento

Exibir o cartão de círculo React no serviço do Power BI

Configurar o React no seu projeto

Instalar o React

Instalar definições de tipo do React

Criar uma classe de componente React

Adicionar React ao arquivo visual

Editar o arquivo tsconfig

Teste o seu visual

Configurar o campo de dados do seu visual

Atualize o estilo do visual

Definir o visual para receber propriedades do Power BI

Renderizar dados usando o React

Definir o visual para receber dados

Definir o visual para enviar dados

Ver as alterações ao visual

Torne o seu visual redimensionável

Configurar o arquivo visual.ts

Configurar o arquivo component.tsx

Configurar o arquivo visual

Torne o seu visual do Power BI personalizável

Adicionar cor e espessura ao arquivo de recursos

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

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

Editar o arquivo do componente

Reveja as suas alterações

Conteúdos relacionados

Feedback

Recursos adicionais