Поделиться через

Руководство. Создание визуального элемента Power BI с помощью React

Разработчик может создавать собственные визуальные элементы Power BI. Эти визуальные элементы могут использоваться вами, вашей организацией или сторонними лицами.

В этом руководстве описано, как разработать визуальный элемент Power BI с помощью React. Визуальный элемент отображает форматируемое значение меры внутри круга. Визуальный элемент имеет адаптивный размер и позволяет настраивать его параметры.

В этом руководстве описано следующее:

  • Создайте проект разработки для визуального элемента.
  • Разработка визуального элемента с помощью React.
  • Настройте визуальный элемент для обработки данных.
  • Настройте визуальный элемент для адаптации к изменениям размера.
  • Настройте адаптивные параметры цвета и границы для визуального элемента.

Примечание.

Полный исходный код этого визуального элемента см . в визуальном элементе React Circle Card Power BI.

Необходимые компоненты

Прежде чем приступить к разработке визуального элемента Power BI, убедитесь, что у вас есть все, что указано в этом разделе.

Создание проекта разработки

В этом разделе описано, как создать проект для визуального элемента карточки "Круг React".

  1. Откройте PowerShell и перейдите в папку, в которой вы хотите создать проект.

  2. Введите следующую команду:

    pbiviz new ReactCircleCard

  3. Перейдите в папку проекта.

    cd ReactCircleCard

  4. Запустите визуальный элемент карточки круга React. Теперь визуальный элемент запущен во время размещения на компьютере.

    pbiviz start

    Внимание

    Чтобы остановить запуск визуального элемента, в PowerShell введите CTRL+ и при появлении запроса на завершение пакетного задания, введите Y и нажмите клавишу ВВОД.

Просмотр карточки круга React в служба Power BI

Чтобы протестировать визуальный элемент в служба Power BI, мы будем использовать отчет по анализу продаж в США. Вы можете скачать этот отчет и отправить его в служба Power BI.

Вы также можете использовать собственный отчет для тестирования визуального элемента.

Примечание.

Прежде чем продолжить, убедитесь, что вы включили режим разработчика визуальных элементов.

  1. Войдите в PowerBI.com и откройте отчет по анализу продаж США.

  2. Выберите Изменить.

    Снимок экрана: параметр редактирования в служба Power BI.

  3. Создайте новую страницу для тестирования, нажав кнопку "Создать страницу" в нижней части интерфейса служба Power BI.

    Снимок экрана: кнопка новой страницы в служба Power BI.

  4. В области "Визуализации" выберите визуальный элемент разработчика.

    Снимок экрана: визуальный элемент разработчика в области визуализаций.

    Этот визуальный элемент представляет пользовательский визуальный элемент, запущенный на компьютере. Он доступен только в том случае, если включен пользовательский параметр визуальной отладки .

  5. Убедитесь, что визуальный элемент добавлен на холст отчета.

    Снимок экрана: новый визуальный элемент, добавленный в отчет.

    Это простой визуальный элемент, отображающий количество вызовов метода обновления. На этом этапе визуальный элемент не получает никаких данных.

    Примечание.

    Если визуальный элемент отображает сообщение об ошибке подключения, откройте новую вкладку в браузере, перейдите https://localhost:8080/assetsк браузеру и авторизации браузера для использования этого адреса.

    Снимок экрана: новый визуальный элемент, отображающий ошибку подключения.

  6. Пока выбран новый визуальный элемент, перейдите в область данных , разверните узел "Продажи" и выберите "Количество".

    Снимок экрана: поле служба Power BI количества в таблице продаж в отчете по анализу продаж США.

  7. Чтобы проверить, как визуальный элемент отвечает, измените его размер и обратите внимание, что значение счетчика обновлений увеличивается при каждом изменении размера визуального элемента.

    Снимок экрана: новый визуальный элемент, отображающий другое число обновлений после изменения размера.

Настройка React в проекте

В этом разделе описано, как настроить React для визуального проекта Power BI.

Откройте PowerShell и остановите работу визуального элемента, введя ctrl+C. Если появится запрос на завершение пакетного задания, введите Y и нажмите клавишу ВВОД.

Установка React

Чтобы установить необходимые зависимости React, откройте PowerShell в папке ReactCircleCard и выполните следующую команду:

npm i react react-dom

Установка определений типов React

Чтобы установить определения типов для React, откройте PowerShell в папке ReactCircleCard и выполните следующую команду:

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

Создание класса компонента React

Выполните следующие действия, чтобы создать класс компонента React.

  1. Откройте VS Code и перейдите в папку ReactCircleCard .

  2. Создайте файл, выбрав >"Создать файл".

  3. Скопируйте следующий код в новый файл.

    import * as React from "react";

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

export default ReactCircleCard;

  4. Выберите "Сохранить как" и перейдите в папку src .

  5. Сохраните файл следующим образом:

    • В поле имени файла введите компонент.
    • В раскрывающемся меню "Сохранить как тип" выберите TypeScript React.

Добавление React в визуальный файл

Замените код в файле visual.ts кодом, который позволяет использовать React.

  1. В папке src откройте visual.ts и замените код в файле следующим кодом:

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

    }
}

    Примечание.

    Так как параметры Power BI TypeScript по умолчанию не распознают файлы React tsx , VS Code выделяется component как ошибка.

  2. Чтобы отобразить компонент, добавьте целевой ЭЛЕМЕНТ HTML в visual.ts. Этот элемент находится в HTMLElementконструкторе, который передается VisualConstructorOptions в конструктор.

    1. В папке src откройте visual.ts.

    2. Добавьте в класс Visual следующий код.

    private target: HTMLElement;
private reactRoot: React.ComponentElement<any, any>;
    1. Добавьте в конструктор следующие строки VisualConstructorOptions :
    this.reactRoot = React.createElement(ReactCircleCard, {});
this.target = options.element;

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

    Теперь файл visual.ts должен выглядеть следующим образом:

    "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. Сохраните visual.ts.

Изменение файла tsconfig

Измените tsconfig.json для работы с React.

  1. В папке ReactCircleCard откройте tsconfig.json и добавьте две строки в начало compilerOptions элемента.

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

    Теперь файл tsconfig.json должен выглядеть следующим образом, и component ошибка в visual.ts должна быть удалена.

    {
    "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. Сохраните tsconfig.json.

Тестирование визуального элемента

Откройте PowerShell в папке CircleCardVisual и запустите проект:

pbiviz start

При добавлении нового визуального элемента разработчика в отчет в служба Power BI выглядит следующим образом:

Снимок экрана: сообщение hello React в созданном визуальном элементе разработчика в службе Power B I.

Настройка поля данных визуального элемента

Настройте файл возможностей визуального элемента, чтобы отправить только одно поле данных в поле данных измерения визуального элемента.

  1. В VS Code в папке ReactCircleCard откройте capabilities.json.

  2. Отображается ReactCircleCard одно значение. Measure Data Category Data Удалите объект из dataRoles.

    После удаления Category Data объекта dataRoles ключ выглядит следующим образом:

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

  3. Удалите все содержимое objects ключа (вы заполните его позже).

    После удаления содержимого objects ключ выглядит следующим образом:

    "objects": {},

  4. Замените dataViewMappings свойство следующим кодом. max: 1в measure поле данных меры визуального элемента можно отправить только одно поле данных.

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

  5. Сохраните внесенные изменения в capabilities.json.

  6. Убедитесь, что pbiviz start выполняется и в служба Power BI, обновите визуальный элемент React Circle Card. Поле данных Measure может принимать только одно поле данных , как указано в max: 1разделе .

    Снимок экрана: поле

Обновление стиля визуального элемента

В этом разделе фигура визуального элемента превращается в круг. Используйте файл visual.less для управления стилем визуального элемента.

  1. В папке стилей откройте visual.less.

  2. Замените содержимое visual.less следующим кодом.

    .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. Сохраните visual.less.

Настройка визуального элемента для получения свойств из Power BI

В этом разделе описана настройка визуального элемента для получения данных из Power BI и отправки обновлений экземплярам в файле component.tsx .

Отрисовка данных с помощью React

Данные можно отобразить с помощью React. Компонент может отображать данные из собственного состояния.

  1. В VS Code из папки ReactCircleCard откройте component.tsx.

  2. Замените содержимое component.tsx следующим кодом.

    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. Сохраните component.tsx.

Настройка визуального элемента для получения данных

Визуальные элементы получают данные в качестве аргумента update метода. В этом разделе описано, как обновить этот метод для получения данных.

Следующий код выбирает и textLabel из textValueDataViewнее, а если данные существуют, обновляет состояние компонента.

  1. В VS Code в папке src откройте visual.ts.

  2. Замените строку import ReactCircleCard from "./component"; следующим кодом:

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

  3. Добавьте следующий код в метод 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. clear Создайте метод, добавив следующий код под методомupdate.

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

  5. Сохранение visual.ts

Настройка визуального элемента для отправки данных

В этом разделе вы обновите визуальный элемент для отправки обновлений экземплярам в файле компонента .

  1. В VS Code в папке src откройте component.tsx.

  2. Добавьте в класс 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. Сохраните component.tsx.

Просмотр изменений визуального элемента

Проверьте визуальный элемент "Карточка круга React", чтобы просмотреть внесенные изменения.

  1. Убедитесь, что pbiviz start выполняется и в служба Power BI обновите визуальный элемент React Circle Card.

  2. Добавьте продажи в поле данных измерения визуального элемента.

Снимок экрана: значение продаж, отображаемое в визуальном элементе карточки с кругом react в служба Power BI.

Сделать визуальный элемент изменяемым

В настоящее время визуальный элемент имеет фиксированную ширину и высоту. Чтобы сделать визуальный элемент измененным, необходимо определить size переменную как в visual.ts, так и в файлах component.tsx. В этом разделе описано, как изменить размер визуального элемента.

После выполнения действий, описанных в этом разделе, диаметр круга в визуальном элементе будет соответствовать минимальной ширине или высоте, и вы сможете изменить его размер в служба Power BI.

Настройка файла visual.ts

Получение текущего размера визуального окна представления из options объекта.

  1. В VS Code в папке src откройте visual.ts.

  2. Вставьте этот код для импорта IViewport интерфейса.

    import IViewport = powerbi.IViewport;

  3. viewport Добавьте свойство в visual класс.

    private viewport: IViewport;

  4. В методе update добавьте ReactCircleCard.updateследующий код.

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

  5. В методе updateReactCircleCard.updateдобавьте size.

    size,

  6. Сохраните visual.ts.

Настройка файла component.tsx

  1. В VS Code в папке src откройте component.tsx.

  2. Добавьте в раздел export interface State следующий код.

    size: number

  3. Добавьте в раздел export const initialState: State следующий код.

    size: 200

  4. В методе render внесите следующие изменения в код:

    1. Добавлен size в const { textLabel, textValue, size } = this.state;. Теперь это объявление должно выглядеть следующим образом:

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

    2. Добавьте приведенный выше returnкод.

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

    3. Замените первую возвращаемую строку <div className="circleCard"> следующим:

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

  5. Сохраните component.tsx.

Настройка визуального файла

  1. В VS Code в папке стилей откройте visual.less.

  2. В .circleCard, заменяйте width и heightmin-widthmin-height на .

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

  3. Сохраните visual.less.

Настройка визуального элемента Power BI

В этом разделе вы добавите возможность настраивать визуальный элемент, позволяя пользователям вносить изменения в его цвет и толщину границы.

Добавление цвета и толщины в файл возможностей

Добавьте толщину цвета и границы object в свойство в capabilities.json.

  1. В VS Code в папке ReactCircleCard откройте capabilities.json.

  2. Добавьте следующие параметры в objects свойство.

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

  3. Сохраните capabilities.json.

Добавление класса параметров форматирования круга в файл параметров

Circle Добавьте параметры форматирования в settings.ts. Дополнительные сведения о создании параметров модели форматирования см. в разделе "Использование форматирования".

  1. В VS Code в папке src откройте settings.ts.

  2. Замените код в settings.ts следующим кодом:

    "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. Сохраните settings.ts.

Добавление метода для применения визуальных параметров

Добавьте метод, используемый getFormattingModel для применения визуальных параметров и необходимых импортов в файл visual.ts .

  1. В VS Code в папке src откройте visual.ts.

  2. Добавьте эти import инструкции в верхней части visual.ts.

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

  3. Добавьте следующее объявление в Visual.

    private formattingSettings: VisualFormattingSettingsModel;
private formattingSettingsService: FormattingSettingsService;

  4. Добавьте метод в getFormattingModelVisual.

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

  5. Visual В классе добавьте следующую строку кода для constructor инициализацииformattingSettingsService

        this.formattingSettingsService = new FormattingSettingsService();

  6. Visual В классе добавьте следующий код, чтобы update обновить параметры визуального форматирования до последних значений свойств форматирования.

    1. Добавьте этот код в инструкцию if после const size = Math.min(width, height);.

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

    2. Добавьте этот код в следующее ReactCircleCard.updatesize:

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

  7. Сохраните visual.ts.

Изменение файла компонента

Измените файл компонента, чтобы он смог отобразить изменения цвета и границы визуального элемента.

  1. В VS Code в папке src откройте component.tsx.

  2. Добавьте следующие значения Stateв :

    background?: string,
borderWidth?: number

  3. В методе замените render следующие строки кода:

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

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

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

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

  4. Сохраните component.tsx.

Просмотр изменений

Экспериментируйте с цветом и толщиной границы визуального элемента, который теперь можно контролировать.

  1. Убедитесь, что pbiviz start выполняется и в служба Power BI обновите визуальный элемент React Circle Card.

  2. Выберите вкладку "Формат" и разверните "Круг".

  3. Настройте параметры цвета и толщины визуального элемента и просмотрите их влияние на визуальный элемент.

Снимок экрана: визуальный элемент карточки react circle в службе Power B I с параметрами цвета и толщины границы.

Связанный контент

  • Last updated on