Samouczek: tworzenie wizualizacji usługi Power BI przy użyciu platformy React

Jako deweloper możesz tworzyć własne wizualizacje usługi Power BI. Te wizualizacje mogą być używane przez Ciebie, Twoją organizację lub przez inne firmy.

W tym samouczku utworzysz wizualizację usługi Power BI przy użyciu platformy React. Wizualizacja wyświetla sformatowaną wartość miary wewnątrz okręgu. Wizualizacja ma rozmiar adaptacyjny i umożliwia dostosowanie jej ustawień.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

Tworzenie projektu programistycznego dla wizualizacji.
Opracowywanie wizualizacji przy użyciu platformy React.
Skonfiguruj wizualizację do przetwarzania danych.
Skonfiguruj wizualizację, aby dostosować się do zmian rozmiaru.
Skonfiguruj ustawienia adaptacyjnego koloru i obramowania dla wizualizacji.

Uwaga

Pełny kod źródłowy tej wizualizacji można znaleźć w temacie React circle card Power BI visual (Wizualizacja usługi Power BI z kartą platformy React).

Wymagania wstępne

Przed rozpoczęciem tworzenia wizualizacji usługi Power BI sprawdź, czy masz wszystkie elementy wymienione w tej sekcji.

Konto usługi Power BI Pro lub Premium na użytkownika (PPU). Jeśli jej nie masz, utwórz konto bezpłatnej wersji próbnej.
Visual Studio Code (VS Code). Program VS Code to idealne zintegrowane środowisko projektowe (IDE) do tworzenia aplikacji JavaScript i TypeScript.
Windows PowerShell w wersji 4 lub nowszej (dla systemu Windows). Lub Terminal (dla komputerów Mac).
Środowisko gotowe do tworzenia wizualizacji usługi Power BI. Skonfiguruj środowisko do tworzenia wizualizacji usługi Power BI.
W tym samouczku jest używany raport US Sales Analysis . Możesz pobrać ten raport i przekazać go do usługa Power BI lub użyć własnego raportu. Jeśli potrzebujesz więcej informacji na temat usługa Power BI i przekazywania plików, zapoznaj się z samouczkiem Wprowadzenie do tworzenia w usługa Power BI.

Tworzenie projektu programistycznego

W tej sekcji utworzysz projekt wizualizacji karty circle React.

Otwórz program PowerShell i przejdź do folderu, w którym chcesz utworzyć projekt.
Podaj następujące polecenie:
```
pbiviz new ReactCircleCard
```
Przejdź do folderu projektu.
```
cd ReactCircleCard
```
Uruchom wizualizację karty circle react. Wizualizacja jest teraz uruchomiona podczas hostowania na komputerze.
```
pbiviz start
```
Ważne

Aby zatrzymać uruchamianie wizualizacji, w programie PowerShell wprowadź Ctrl+Y i naciśnij Enter.

Wyświetlanie karty circle react w usługa Power BI

Aby przetestować wizualizację w usługa Power BI, użyjemy raportu US Sales Analysis. Możesz pobrać ten raport i przekazać go do usługa Power BI.

Możesz również użyć własnego raportu, aby przetestować wizualizację.

Uwaga

Przed kontynuowaniem sprawdź, czy włączono tryb dewelopera wizualizacji.

Zaloguj się, aby PowerBI.com i otworzyć raport US Sales Analysis.
Zaznacz Edytuj.
Utwórz nową stronę do testowania, klikając przycisk Nowa strona w dolnej części interfejsu usługa Power BI.
W okienku Wizualizacje wybierz wizualizację dewelopera.

Ta wizualizacja reprezentuje wizualizację niestandardową uruchomioną na komputerze. Jest ona dostępna tylko wtedy, gdy jest włączone niestandardowe ustawienie debugowania wizualizacji .
Sprawdź, czy wizualizacja została dodana do kanwy raportu.

Jest to prosta wizualizacja, która wyświetla liczbę wywołań metody aktualizacji. Na tym etapie wizualizacja nie pobiera żadnych danych.

Uwaga

Jeśli wizualizacja wyświetla komunikat o błędzie połączenia, otwórz nową kartę w przeglądarce, przejdź do https://localhost:8080/assetsadresu i autoryzuj przeglądarkę do korzystania z tego adresu.
Po wybraniu nowej wizualizacji przejdź do okienka Dane, rozwiń węzeł Sales (Sprzedaż) i wybierz pozycję Quantity (Ilość).
Aby przetestować, jak wizualizacja odpowiada, zmień jej rozmiar i zwróć uwagę, że wartość Liczba aktualizacji zwiększa się za każdym razem, gdy zmieniasz rozmiar wizualizacji.

Konfigurowanie platformy React w projekcie

W tej sekcji dowiesz się, jak skonfigurować platformę React dla projektu wizualizacji usługi Power BI.

Otwórz program PowerShell i zatrzymaj uruchamianie wizualizacji, wprowadzając Ctrl+C. Jeśli zostanie wyświetlony monit o zakończenie zadania wsadowego, wprowadź wartość Y i naciśnij Enter.

Instalowanie oprogramowania React

Aby zainstalować wymagane zależności platformy React, otwórz program PowerShell w folderze ReactCircleCard i uruchom następujące polecenie:

npm i react react-dom

Instalowanie definicji typów platformy React

Aby zainstalować definicje typów dla platformy React, otwórz program PowerShell w folderze reactCircleCard i uruchom następujące polecenie:

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

Tworzenie klasy składnika React

Wykonaj następujące kroki, aby utworzyć klasę składnika React.

Otwórz program VS Code i przejdź do folderu reactCircleCard .
Utwórz nowy plik, wybierając pozycję Plik>nowy plik.

Skopiuj następujący kod do nowego pliku.

import * as React from "react";

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

export default ReactCircleCard;

Wybierz pozycję Zapisz jako i przejdź do folderu src .
Zapisz plik w następujący sposób:
- W polu Nazwa pliku wprowadź składnik.
- Z menu rozwijanego Zapisz jako typ wybierz pozycję TypeScript React.

Dodawanie platformy React do pliku wizualizacji

Zastąp kod w pliku visual.ts kodem, który umożliwia korzystanie z platformy React.

W folderze src otwórz visual.ts i zastąp kod w pliku następującym kodem:

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

    }
}

Uwaga

Ponieważ domyślne ustawienia języka TypeScript usługi Power BI nie rozpoznają plików tsx platformy React, program VS Code wyróżnia component się jako błąd.

Aby renderować składnik, dodaj docelowy element HTML do visual.ts. Ten element znajduje HTMLElement się w VisualConstructorOptionselemecie , który jest przekazywany do konstruktora.

W folderze src otwórz visual.ts.
Dodaj następujący kod do Visual klasy:

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

Dodaj następujące wiersze do konstruktora VisualConstructorOptions :

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

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

Plik visual.ts powinien teraz wyglądać następująco:

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

    }
}

Zapisz visual.ts.

Edytowanie pliku tsconfig

Edytuj tsconfig.json, aby pracować z platformą React.

W folderze reactCircleCard otwórz tsconfig.json i dodaj dwa wiersze na początku compilerOptions elementu.

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

Plik tsconfig.json powinien teraz wyglądać następująco, a component błąd w visual.ts powinien zniknąć.

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

Zapisz tsconfig.json.

Testowanie wizualizacji

Otwórz program PowerShell w folderze CircleCardVisual i uruchom projekt:

pbiviz start

Po dodaniu nowej wizualizacji dewelopera do raportu w usługa Power BI wygląda następująco:

Zrzut ekranu przedstawiający komunikat hello React w nowo utworzonej wizualizacji dewelopera w usłudze Power BI.

Konfigurowanie pola danych wizualizacji

Skonfiguruj plik możliwości wizualizacji, aby tylko jedno pole danych można było przesłać do pola Dane miary wizualizacji.

W programie VS Code z folderu reactCircleCard otwórz capabilities.json.
Zostanie wyświetlona pojedyncza ReactCircleCard wartość. Measure Data Category Data Usuń obiekt z dataRoles.

Po usunięciu Category Data obiektu dataRoles klucz wygląda następująco:
```
"dataRoles": [
    {
        "displayName": "Measure Data",
        "name": "measure",
        "kind": "Measure"
    }
],
```
Usuń całą zawartość objects klucza (wypełnisz go później).

Po usunięciu objects jego zawartości klucz wygląda następująco:
```
"objects": {},
```

Zastąp dataViewMappings właściwość następującym kodem. max: 1 w measure parametrze określa, że do pola Danych miary wizualizacji można przesłać tylko jedno pole danych .

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

Zapisz zmiany wprowadzone w capabilities.json.
Sprawdź, czy pbiviz start działa i w usługa Power BI odśwież wizualizację React Circle Card. Pole Dane miary może akceptować tylko jedno pole danych, zgodnie z wartością max: 1.

Aktualizowanie stylu wizualizacji

W tej sekcji przekształcisz kształt wizualizacji w okrąg. Użyj pliku visual.less, aby kontrolować styl wizualizacji.

W folderze style otwórz plik visual.less.

Zastąp zawartość pliku visual.less następującym kodem.

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

Zapisz plik visual.less.

Ustawianie wizualizacji w celu odbierania właściwości z usługi Power BI

W tej sekcji skonfigurujesz wizualizację do odbierania danych z usługi Power BI i wysyłasz aktualizacje do wystąpień w pliku component.tsx .

Renderowanie danych przy użyciu platformy React

Dane można renderować przy użyciu platformy React. Składnik może wyświetlać dane z własnego stanu.

W programie VS Code z folderu reactCircleCard otwórz plik component.tsx.

Zastąp zawartość pliku component.tsx następującym kodem.

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

Zapisz plik component.tsx.

Ustawianie wizualizacji na potrzeby odbierania danych

Wizualizacje odbierają dane jako argument update metody . W tej sekcji zaktualizujesz tę metodę w celu odbierania danych.

Poniższy kod wybiera textLabel wartości i textValue z DataView, a jeśli dane istnieją, aktualizuje stan składnika.

W programie VS Code z folderu src otwórz visual.ts.
Zastąp wiersz import ReactCircleCard from "./component"; następującym kodem:
```
import { ReactCircleCard, initialState } from "./component";
```

Dodaj następujący kod do metody 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();
}

Utwórz metodę clear , dodając następujący kod poniżej update metody .
```
private clear() {
    ReactCircleCard.update(initialState);
}
```
Zapisywanie visual.ts

Ustawianie wizualizacji na potrzeby wysyłania danych

W tej sekcji zaktualizujesz wizualizację w celu wysyłania aktualizacji do wystąpień w pliku składnika .

W programie VS Code z folderu src otwórz plik component.tsx.

Dodaj następujący kod do ReactCircleCard klasy:

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

Zapisz plik component.tsx.

Wyświetlanie zmian w wizualizacji

Przetestuj wizualizację karty React Circle, aby wyświetlić wprowadzone zmiany.

Sprawdź, czy pbiviz start jest uruchomiona, a następnie w usługa Power BI odśwież wizualizację React Circle Card.
Dodaj pozycję Sales (Sprzedaż) do pola Miara wizualizacji.

Zrzut ekranu przedstawiający wartość sprzedaży wyświetlaną w wizualizacji karty circle w usługa Power BI.

Zmienianie rozmiaru wizualizacji

Obecnie wizualizacja ma stałą szerokość i wysokość. Aby zmienić rozmiar wizualizacji, należy zdefiniować zmienną size zarówno w plikach visual.ts, jak i component.tsx . W tej sekcji można zmienić rozmiar wizualizacji.

Po wykonaniu kroków opisanych w tej sekcji średnicę okręgu w wizualizacji będzie odpowiadać minimalnej szerokości lub wysokości i będzie można zmienić jej rozmiar w usługa Power BI.

Konfigurowanie pliku visual.ts

Pobierz bieżący rozmiar widoku wizualizacji z options obiektu.

W programie VS Code z folderu src otwórz visual.ts.
Wstaw ten kod, aby zaimportować IViewport interfejs.
```
import IViewport = powerbi.IViewport;
```
viewport Dodaj właściwość do visual klasy.
```
private viewport: IViewport;
```

W metodzie update przed ReactCircleCard.updatedodaj następujący kod.

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

W metodzie update w ReactCircleCard.updatepliku dodaj sizeelement .
```
size,
```
Zapisz visual.ts.

Konfigurowanie pliku component.tsx

W programie VS Code z folderu src otwórz plik component.tsx.
Dodaj następujący kod do pliku export interface State.
```
size: number
```
Dodaj następujący kod do pliku export const initialState: State.
```
size: 200
```
W metodzie render wprowadź następujące zmiany w kodzie:
1. Dodaj size do const { textLabel, textValue, size } = this.state;. Ta deklaracja powinna teraz wyglądać następująco:
```
const { textLabel, textValue, size } = this.state;
```
2. Dodaj poniższy kod powyżej return.
```
const style: React.CSSProperties = { width: size, height: size };
```
3. Zastąp pierwszy :
```
<div className="circleCard" style={style}>
```
Zapisz plik component.tsx.

Konfigurowanie pliku wizualizacji

W programie VS Code z folderu style otwórz plik visual.less.
W .circleCardpliku zastąp wartości width i height elementami min-width i min-height.
```
min-width: 200px;
min-height: 200px;
```
Zapisz plik visual.less.

Dostosowywanie wizualizacji usługi Power BI

W tej sekcji dodasz możliwość dostosowywania wizualizacji, umożliwiając użytkownikom wprowadzanie zmian w kolorze i grubości obramowania.

Dodawanie koloru i grubości do pliku capabilities

Dodaj grubość koloru i obramowania do object właściwości w capabilities.json.

W programie VS Code z folderu reactCircleCard otwórz capabilities.json.

Dodaj następujące ustawienia do objects właściwości .

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

Zapisz capabilities.json.

Dodawanie klasy ustawień formatowania okręgu do pliku ustawień

Circle Dodaj ustawienia formatowania do settings.ts. Aby uzyskać więcej informacji na temat tworzenia ustawień modelu formatowania, zobacz narzędzia formatowania.

W programie VS Code z folderu src otwórz settings.ts.

Zastąp kod w settings.ts następującym kodem:

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

Zapisz settings.ts.

Dodawanie metody do stosowania ustawień wizualizacji

Dodaj metodę używaną getFormattingModel do stosowania ustawień wizualizacji i wymaganych importów do pliku visual.ts .

W programie VS Code z folderu src otwórz visual.ts.

Dodaj te import instrukcje w górnej części visual.ts.

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

Dodaj następującą deklarację do wizualizacji.

private formattingSettings: VisualFormattingSettingsModel;
private formattingSettingsService: FormattingSettingsService;

Dodaj metodę do wizualizacji getFormattingModel.

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

Visual W klasie dodaj następujący wiersz kodu, aby constructor zainicjowaćformattingSettingsService
```
    this.formattingSettingsService = new FormattingSettingsService();
```

Visual W klasie dodaj następujący kod, aby update zaktualizować ustawienia formatowania wizualizacji do najnowszych wartości właściwości formatowania.

Dodaj ten kod do instrukcji if po const size = Math.min(width, height);.

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

Dodaj ten kod do ReactCircleCard.update pliku po :size

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

Zapisz visual.ts.

Edytowanie pliku składnika

Edytuj plik składnika, aby mógł renderować zmiany koloru i grubości obramowania wizualizacji.

W programie VS Code z folderu src otwórz plik component.tsx.
Dodaj następujące wartości do elementu State:
```
background?: string,
borderWidth?: number
```
W metodzie zastąp render następujące wiersze kodu:
1. const { textLabel, textValue, size } = this.state; z:
```
const { textLabel, textValue, size, background, borderWidth } = this.state;
```
2. const style: React.CSSProperties = { width: size, height: size }; z:
```
const style: React.CSSProperties = { width: size, height: size, background, borderWidth };
```
Zapisz plik component.tsx.

Przeglądanie zmian

Poeksperymentuj z kolorem i grubością obramowania wizualizacji, którą można teraz kontrolować.

Sprawdź, czy pbiviz start jest uruchomiona, a następnie w usługa Power BI odśwież wizualizację React Circle Card.
Wybierz kartę Format i rozwiń węzeł Circle.
Dostosuj ustawienia Kolor i Grubość wizualizacji i przejrzyj ich wpływ na wizualizację.

Zrzut ekranu przedstawiający wizualizację karty circle circle w usłudze Power BI z opcjami formatu koloru i grubości obramowania.

Opinia

Czy ta strona była pomocna?

Last updated on 2025-12-15

Udostępnij za pośrednictwem

Samouczek: tworzenie wizualizacji usługi Power BI przy użyciu platformy React

Wymagania wstępne

Tworzenie projektu programistycznego

Wyświetlanie karty circle react w usługa Power BI

Konfigurowanie platformy React w projekcie

Instalowanie oprogramowania React

Instalowanie definicji typów platformy React

Tworzenie klasy składnika React

Dodawanie platformy React do pliku wizualizacji

Edytowanie pliku tsconfig

Testowanie wizualizacji

Konfigurowanie pola danych wizualizacji

Aktualizowanie stylu wizualizacji

Ustawianie wizualizacji w celu odbierania właściwości z usługi Power BI

Renderowanie danych przy użyciu platformy React

Ustawianie wizualizacji na potrzeby odbierania danych

Ustawianie wizualizacji na potrzeby wysyłania danych

Wyświetlanie zmian w wizualizacji

Zmienianie rozmiaru wizualizacji

Konfigurowanie pliku visual.ts

Konfigurowanie pliku component.tsx

Konfigurowanie pliku wizualizacji

Dostosowywanie wizualizacji usługi Power BI

Dodawanie koloru i grubości do pliku capabilities

Dodawanie klasy ustawień formatowania okręgu do pliku ustawień

Dodawanie metody do stosowania ustawień wizualizacji

Edytowanie pliku składnika

Przeglądanie zmian

Powiązana zawartość

Opinia

Dodatkowe zasoby