Tutorial: Membuat visual Power BI menggunakan React

2024-10-12

Sebagai pengembang, Anda dapat membuat visual Power BI Anda sendiri. Visual ini dapat digunakan oleh Anda, organisasi Anda, atau oleh pihak ketiga.

Dalam tutorial ini, Anda mengembangkan visual Power BI menggunakan React. Visual menampilkan nilai pengukuran yang diformat di dalam lingkaran. Visual memiliki ukuran adaptif dan memungkinkan Anda untuk menyesuaikan pengaturannya.

Dalam tutorial ini, Anda akan mempelajari cara:

Buat proyek pengembangan untuk visual Anda.
Kembangkan visual Anda menggunakan React.
Konfigurasikan visual Anda untuk memproses data.
Konfigurasikan visual Anda untuk beradaptasi dengan perubahan ukuran.
Konfigurasikan warna adaptif dan pengaturan batas untuk visual Anda.

Catatan

Untuk kode sumber lengkap visual ini, lihat visual Power BI kartu lingkaran React.

Prasyarat

Sebelum Anda mulai mengembangkan visual Power BI, verifikasi bahwa Anda memiliki semua yang tercantum di bagian ini.

Akun Power BI Pro atau Premium Per Pengguna (PPU). Jika tidak memilikinya, Anda dapat mendaftar untuk coba gratis.
Visual Studio Code (VS Code). Visual Studio Code adalah Lingkungan Pengembangan Terintegrasi (IDE) yang ideal untuk mengembangkan aplikasi JavaScript dan TypeScript.
Windows PowerShell versi 4 atau yang lebih baru (untuk Windows). Atau Terminal (untuk Mac).
Lingkungan yang siap untuk mengembangkan visual Power BI. Menyiapkan lingkungan Anda untuk mengembangkan visual Power BI.
Tutorial ini menggunakan laporan Analisis Penjualan AS. Anda dapat mengunduh laporan ini dan mengunggahnya ke layanan Power BI, atau menggunakan laporan Anda sendiri. Jika Anda memerlukan informasi selengkapnya tentang layanan Power BI, dan mengunggah file, lihat tutorial Mulai membuat di layanan Power BI.

Membuat proyek pengembangan

Di bagian ini, Anda membuat proyek untuk visual kartu lingkaran React.

Buka PowerShell dan navigasikan ke folder tempat Anda ingin membuat proyek.
Masukkan perintah berikut:
```
pbiviz new ReactCircleCard
```
Navigasikan ke folder proyek.
```
cd ReactCircleCard
```
Mulai visual kartu lingkaran React. Visual Anda sekarang berjalan saat sedang dihosting di komputer Anda.
```
pbiviz start
```
Penting

Untuk menghentikan visual berjalan, di PowerShell masukkan Ctrl+C dan jika diminta untuk mengakhiri pekerjaan batch, masukkan Y, dan tekan Enter.

Menampilkan kartu lingkaran React di layanan Power BI

Untuk menguji visual di layanan Power BI, kita akan menggunakan laporan Analisis Penjualan AS. Anda dapat mengunduh laporan ini dan mengunggahnya ke layanan Power BI.

Anda juga dapat menggunakan laporan Anda sendiri untuk menguji visual.

Catatan

Sebelum melanjutkan, verifikasi bahwa Anda mengaktifkan mode pengembang visual.

Masuk ke PowerBI.com dan buka laporan Analisis Penjualan AS.
Pilih Edit.
Buat halaman baru untuk pengujian, dengan mengklik tombol Halaman baru di bagian bawah antarmuka layanan Power BI.
Dari panel Visualisasi, pilih Visual Pengembang.

Visual ini mewakili visual kustom yang Anda jalankan di komputer Anda. Ini hanya tersedia saat pengaturan penelusuran kesalahan visual kustom diaktifkan.
Verifikasi bahwa visual ditambahkan ke kanvas laporan.

Ini adalah visual sederhana yang menampilkan berapa kali metode pembaruannya telah dipanggil. Pada tahap ini, visual tidak mengambil data apa pun.

Catatan

Jika visual menampilkan pesan kesalahan koneksi, buka tab baru di browser Anda, navigasi ke https://localhost:8080/assets, dan otorisasi browser Anda untuk menggunakan alamat ini.
Saat visual baru dipilih, buka panel Data , perluas Penjualan, dan pilih Kuantitas.
Untuk menguji bagaimana visual merespons, ubah ukurannya dan perhatikan bahwa nilai Jumlah pembaruan bertambah setiap kali Anda mengubah ukuran visual.

Menyiapkan React di proyek Anda

Di bagian ini, Anda mempelajari cara menyiapkan React untuk proyek visual Power BI Anda.

Buka PowerShell dan hentikan visual agar tidak berjalan dengan memasukkan Ctrl+C. Jika diminta untuk mengakhiri tugas batch, masukkan Y, dan tekan Enter.

Menginstal React

Untuk menginstal dependensi React yang diperlukan, buka PowerShell di folder ReactCircleCard Anda, dan jalankan perintah berikut:

npm i react react-dom

Menginstal definisi jenis React

Untuk menginstal definisi jenis untuk React, buka PowerShell di folder reactCircleCard Anda dan jalankan perintah berikut:

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

Membuat kelas komponen React

Ikuti langkah-langkah ini untuk membuat kelas komponen React.

Buka Visual Studio Code dan navigasikan ke folder reactCircleCard.
Buat file baru dengan memilih File>File Baru.

Salin kode berikut ke dalam file.

import * as React from "react";

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

export default ReactCircleCard;

Pilih Simpan Sebagai dan navigasikan ke folder src.
Simpan file sebagai berikut:
- Di bidang Nama file, masukkan komponen.
- Dari menu drop-down Simpan sebagai jenis, pilih TypeScript React.

Menambahkan React ke file visual

Ganti kode dalam file visual.ts dengan kode yang memungkinkan penggunaan React.

Di folder src, buka visual.ts dan ganti kode dalam file dengan kode berikut:

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

    }
}

Catatan

Karena pengaturan Power BI TypeScript default tidak mengenali file React tsx, Visual Studio Code menyorot component sebagai kesalahan.

Untuk merender komponen, tambahkan elemen HTML target ke visual.ts. Elemen ini ada HTMLElement di VisualConstructorOptions, yang diteruskan ke konstruktor.

Di folder src, buka visual.ts.
Tambahkan kode berikut ke kelas Visual:

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

Tambahkan kode berikut ke konstruktor VisualConstructorOptions:

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

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

Sekarang file visual.ts Anda akan terlihat seperti ini:

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

    }
}

Simpan visual.ts.

Mengedit file tsconfig

Edit tsconfig.json untuk bekerja dengan React.

Di folder reactCircleCard, buka tsconfig.json dan tambahkan dua baris ke awal compilerOptions item.

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

File tsconfig.json Anda sekarang akan terlihat seperti ini, dan component kesalahan di visual.ts harus hilang.

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

Simpan tsconfig.json.

Menguji visual Anda

Buka PowerShell di folder CircleCardVisual, dan jalankan proyek Anda:

pbiviz start

Saat Anda menambahkan Visual Pengembang baru ke laporan Anda di layanan Power BI, terlihat seperti ini:

Cuplikan layar memperlihatkan pesan hello React di visual pengembang yang baru dibuat di layanan Power B I.

Mengonfigurasi bidang data visual Anda

Konfigurasikan file kemampuan visual Anda sehingga hanya satu bidang data yang dapat dikirimkan ke bidang Mengukur data visual.

Di Visual Studio Code, dari folder reactCircleCard , buka capabilities.json.
ReactCircleCard menampilkan satu nilai, Measure Data. Hapus objek Category Data dari dataRoles.

Setelah menghapus objek Category Data, kunci dataRoles terlihat seperti ini:
```
"dataRoles": [
    {
        "displayName": "Measure Data",
        "name": "measure",
        "kind": "Measure"
    }
],
```
Hapus semua konten kunci objects (Anda akan mengisinya nanti).

Setelah Anda menghapus kontennya, objects kunci terlihat seperti ini:
```
"objects": {},
```

dataViewMappings Ganti properti dengan kode berikut. max: 1 dalam measure menentukan bahwa hanya satu bidang data yang dapat dikirimkan ke bidang Mengukur data visual.

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

Simpan perubahan yang Anda buat pada capabilities.json.
Verifikasi bahwa pbiviz start berjalan dan dalam layanan Power BI, refresh visual Kartu Lingkaran React Anda. Bidang Ukur data hanya dapat menerima satu bidang data, seperti yang ditentukan oleh max: 1.

Memperbarui gaya visual

Di bagian ini, Anda mengubah bentuk visual menjadi lingkaran. Gunakan file visual.less untuk mengontrol gaya visual Anda.

Dari folder gaya, buka visual.less.

Ganti konten visual.less dengan kode berikut.

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

Simpan visual.less.

Atur visual Anda untuk menerima properti dari Power BI

Di bagian ini Anda mengonfigurasi visual untuk menerima data dari Power BI, dan mengirim pembaruan ke instans dalam file component.tsx .

Merender data menggunakan React

Anda dapat merender data menggunakan React. Komponen dapat menampilkan data dari statusnya sendiri.

Di Visual Studio Code, dari folder reactCircleCard, buka component.tsx.

Ganti konten component.tsx dengan kode berikut.

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

Simpan component.tsx.

Mengatur visual Anda untuk menerima data

Visual menerima data sebagai argumen metode update. Di bagian ini, Anda memperbarui metode ini untuk menerima data.

Kode berikut memilih textLabel dan textValue dari DataView, dan jika data ada, perbarui status komponen.

Di Visual Studio Code, dari folder src, buka visual.ts.
Ganti baris import ReactCircleCard from "./component"; dengan kode berikut:
```
import { ReactCircleCard, initialState } from "./component";
```

Tambahkan kode berikut ke metode 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();
}

Buat metode clear dengan menambahkan kode berikut di bawah metode update.
```
private clear() {
    ReactCircleCard.update(initialState);
}
```
Simpan visual.ts

Mengatur visual Anda untuk mengirim data

Di bagian ini, Anda memperbarui visual untuk mengirim pembaruan ke instans dalam file komponen .

Di Visual Studio Code, dari folder src, buka component.tsx.

Tambahkan kode berikut ke kelas 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;
}

Simpan component.tsx.

Menampilkan perubahan pada visual

Uji visual Kartu Lingkaran React Anda untuk melihat perubahan yang Anda buat.

Verifikasi bahwa pbiviz start sedang berjalan, dan di layanan Power BI, refresh visual Kartu Lingkaran React Anda.
Tambahkan Penjualan ke bidang Mengukur data visual.

Cuplikan layar nilai penjualan yang ditampilkan dalam visual kartu lingkaran react di layanan Power BI.

Membuat visual Anda dapat diubah

Saat ini, visual Anda memiliki lebar dan tinggi tetap. Untuk membuat visual dapat diubah ukurannya size, Anda perlu menentukan variabel dalam file visual.ts dan component.tsx. Di bagian ini, Anda membuat visual dapat diubah besar.

Setelah Anda menyelesaikan langkah-langkah yang diuraikan di bagian ini, diameter lingkaran dalam visual Anda akan sesuai dengan lebar atau ukuran tinggi minimal, dan Anda akan dapat mengubah ukurannya dalam layanan Power BI.

Mengonfigurasi file visual.ts

Dapatkan ukuran viewport visual saat ini dari objek options.

Di Visual Studio Code, dari folder src, buka visual.ts.
Sisipkan kode ini untuk mengimpor antarmuka IViewport.
```
import IViewport = powerbi.IViewport;
```
Tambahkan properti viewport berikut ke kelas visual.
```
private viewport: IViewport;
```

Dalam metode update, sebelum ReactCircleCard.update, tambahkan kode berikut.

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

Dalam metode update, di ReactCircleCard.update, tambahkan size.
```
size,
```
Simpan visual.ts.

Mengonfigurasi file component.tsx

Di Visual Studio Code, dari folder src, buka component.tsx.
Tambahkan kode berikut ke export interface State.
```
size: number
```
Tambahkan kode berikut ke export const initialState: State.
```
size: 200
```
Dalam metode , render buat perubahan berikut pada kode:
1. Tambahkan size ke const { textLabel, textValue, size } = this.state;. Pernyataan ini sekarang akan terlihat seperti ini:
```
const { textLabel, textValue, size } = this.state;
```
2. Tambahkan kode berikut di atas return.
```
const style: React.CSSProperties = { width: size, height: size };
```
3. Ganti baris pengembalian pertama <div className="circleCard"> dengan:
```
<div className="circleCard" style={style}>
```
Simpan component.tsx.

Mengonfigurasi file visual

Di Visual Studio Code, dari folder gaya, buka visual.less.
Di .circleCard, ganti width dan height dengan min-width dan min-height.
```
min-width: 200px;
min-height: 200px;
```
Simpan visual.less.

Membuat visual Power BI Anda dapat disesuaikan

Di bagian ini, Anda menambahkan kemampuan untuk menyesuaikan visual Anda, memungkinkan pengguna membuat perubahan pada warna dan ketebalan batasnya.

Menambahkan warna dan ketebalan ke file kemampuan

Tambahkan ketebalan warna dan batas ke object properti di capabilities.json.

Di Visual Studio Code, dari folder reactCircleCard, buka capabilities.json.

Tambahkan pengaturan berikut ke properti objects.

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

Simpan capabilities.json.

Menambahkan kelas pengaturan pemformatan lingkaran ke file pengaturan

Circle Tambahkan pengaturan pemformatan ke settings.ts. Untuk informasi selengkapnya cara membuat pengaturan model pemformatan, lihat memformat util.

Di Visual Studio Code, dari folder src, buka settings.ts.

Ganti kode di setting.ts dengan kode berikut:

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

Simpan settings.ts.

Menambahkan metode untuk menerapkan pengaturan visual

Tambahkan metode yang getFormattingModel digunakan untuk menerapkan pengaturan visual dan impor yang diperlukan ke file visual.ts .

Di Visual Studio Code, dari folder src, buka visual.ts.

Tambahkan pernyataan import ini di bagian atas visual.ts.

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

Tambahkan deklarasi berikut ke Visual.

private formattingSettings: VisualFormattingSettingsModel;
private formattingSettingsService: FormattingSettingsService;

Tambahkan metode getFormattingModel ke Visual.

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

Visual Di kelas , tambahkan baris kode berikut ke untuk constructor menginisialisasiformattingSettingsService
```
    this.formattingSettingsService = new FormattingSettingsService();
```

Visual Di kelas , tambahkan kode berikut ke untuk update memperbarui pengaturan pemformatan visual ke nilai properti pemformatan terbaru.

Tambahkan kode ini ke pernyataan if setelah const size = Math.min(width, height);.

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

Tambahkan kode ini ke ReactCircleCard.update setelah size:

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

Simpan visual.ts.

Mengedit file komponen

Edit file komponen sehingga dapat merender perubahan pada warna visual dan ketebalan batas.

Di Visual Studio Code, dari folder src, buka component.tsx.

Tambahkan nilai-nilai ini ke State:

background?: string,
borderWidth?: number

Dalam metode render, ganti baris kode berikut:
1. const { textLabel, textValue, size } = this.state; dengan:
```
const { textLabel, textValue, size, background, borderWidth } = this.state;
```
2. const style: React.CSSProperties = { width: size, height: size }; dengan:
```
const style: React.CSSProperties = { width: size, height: size, background, borderWidth };
```
Simpan component.tsx.

Meninjau perubahan

Bereksperimenlah dengan warna visual dan ketebalan batas, yang sekarang dapat Anda kontrol.

Verifikasi bahwa pbiviz start sedang berjalan, dan di layanan Power BI, refresh visual Kartu Lingkaran React Anda.
Pilih tab Format dan perluas Lingkaran.
Sesuaikan pengaturan Warna dan Ketebalan visual, dan tinjau efeknya pada visual.

Cuplikan layar visual kartu lingkaran react di layanan Power B I, memperlihatkan opsi format ketebalan warna dan batas.

Bagikan melalui

Tutorial: Membuat visual Power BI menggunakan React

Prasyarat

Membuat proyek pengembangan

Menampilkan kartu lingkaran React di layanan Power BI

Menyiapkan React di proyek Anda

Menginstal React

Menginstal definisi jenis React

Membuat kelas komponen React

Menambahkan React ke file visual

Mengedit file tsconfig

Menguji visual Anda

Mengonfigurasi bidang data visual Anda

Memperbarui gaya visual

Atur visual Anda untuk menerima properti dari Power BI

Merender data menggunakan React

Mengatur visual Anda untuk menerima data

Mengatur visual Anda untuk mengirim data

Menampilkan perubahan pada visual

Membuat visual Anda dapat diubah

Mengonfigurasi file visual.ts

Mengonfigurasi file component.tsx

Mengonfigurasi file visual

Membuat visual Power BI Anda dapat disesuaikan

Menambahkan warna dan ketebalan ke file kemampuan

Menambahkan kelas pengaturan pemformatan lingkaran ke file pengaturan

Menambahkan metode untuk menerapkan pengaturan visual

Mengedit file komponen

Meninjau perubahan

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: