Интеграция с React

Подсказка

Предполагается знакомство с базовыми концепциями и паттернами React. Для повторения см. документацию React.

DHTMLX Pivot интегрируется с React как обычный компонент. Для полного рабочего примера см. демо React Pivot на GitHub.

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

К сведению

Перед началом работы установите Node.js. Vite опционален.

Создайте базовый проект React (или проект на основе Vite) с именем my-react-pivot-app.

Следующая команда создаёт проект Create React App:

npx create-react-app my-react-pivot-app

Установка зависимостей

Перейдите в директорию нового проекта:

cd my-react-pivot-app

Установите зависимости и запустите dev-сервер с помощью вашего пакетного менеджера:

• с yarn:

yarn
yarn start # или: yarn dev

• с npm:

npm install
npm run dev

Приложение должно запуститься на локальном порту (например, http://localhost:3000).

Создание Pivot

Добавьте пакет Pivot в проект, затем оберните Pivot в React-компонент.

Шаг 1. Установка пакета

Загрузите ознакомительный пакет Pivot и следуйте инструкциям в README. Ознакомительный пакет Pivot действителен в течение 30 дней.

Шаг 2. Создание компонента

Создайте React-компонент, который монтирует Pivot. Добавьте новый файл src/Pivot.jsx.

Импорт исходных файлов

Откройте src/Pivot.jsx и импортируйте исходные файлы Pivot. Пути импорта зависят от редакции пакета:

• PRO-версия (установлена из локальной папки):

Pivot.jsx

import { Pivot } from 'dhx-pivot-package';
import 'dhx-pivot-package/dist/pivot.css';

Если пакет поставляется с минифицированными ресурсами, импортируйте pivot.min.css вместо pivot.css.

• Ознакомительная версия:

Pivot.jsx

import { Pivot } from '@dhx/trial-pivot';
import "@dhx/trial-pivot/dist/pivot.css";

В этом руководстве используется ознакомительная версия Pivot.

Настройка контейнера и монтирование Pivot

Для отображения Pivot на странице создайте контейнер div, затем инициализируйте Pivot в хуке useEffect с помощью конструктора.

Следующий фрагмент кода определяет минимальный React-компонент Pivot:

Pivot.jsx

import { useEffect, useRef } from "react";
import { Pivot } from "@dhx/trial-pivot";
import "@dhx/trial-pivot/dist/pivot.css"; // подключение стилей Pivot

export default function PivotComponent(props) {
    let container = useRef(); // реф контейнера для Pivot

    useEffect(() => {
        // инициализация компонента Pivot
        const table = new Pivot(container.current, {});

        return () => {
            table.destructor(); // уничтожение Pivot при размонтировании
        };
    }, []);

    return <div ref={container} className="widget"></div>;
}

Добавление стилей

Для корректного отображения Pivot добавьте следующие стили в основной CSS-файл проекта:

index.css

/* стили для начальной страницы */
html,
body,
#root {
    height: 100%;
    padding: 0;
    margin: 0;
}

/* стили для контейнера Pivot */
.widget {
    height: 100%;
    width: 100%;
}

Загрузка данных

Для передачи данных в Pivot подготовьте набор данных. Создайте src/data.js и экспортируйте данные и метаданные полей:

data.js

export function getData() {
    const dataset = [
        {
            "cogs": 51,
            "date": "10/1/2018",
            "inventory_margin": 503,
            "margin": 71,
            "market_size": "Major Market",
            "market": "Central",
            "marketing": 46,
            "product_line": "Leaves",
            "product_type": "Herbal Tea",
            "product": "Lemon",
            "profit": -5,
            "sales": 122,
            "state": "Colorado",
            "expenses": 76,
            "type": "Decaf"
        },
        {
            "cogs": 52,
            "date": "10/1/2018",
            "inventory_margin": 405,
            "margin": 71,
            "market_size": "Major Market",
            "market": "Central",
            "marketing": 17,
            "product_line": "Leaves",
            "product_type": "Herbal Tea",
            "product": "Mint",
            "profit": 26,
            "sales": 123,
            "state": "Colorado",
            "expenses": 45,
            "type": "Decaf"
        }, // другие элементы данных
    ];

    const fields = [
        {
            "id": "cogs",
            "label": "Cogs",
            "type": "number"
        },
        {
            "id": "date",
            "label": "Date",
            "type": "date"
        }, // другие поля
    ];

    return { dataset, fields };
};

Откройте src/App.js, импортируйте данные и передайте их в компонент <Pivot/> как пропсы:

App.js

import Pivot from "./Pivot";
import { getData } from "./data";

function App() {
    const { fields, dataset } = getData();
    return <Pivot fields={fields} dataset={dataset} />;
}

export default App;

Откройте src/Pivot.jsx, деструктурируйте пропсы и примените их к объекту конфигурации Pivot:

Pivot.jsx

import { useEffect, useRef } from "react";
import { Pivot } from "@dhx/trial-pivot";
import "@dhx/trial-pivot/dist/pivot.css";

export default function PivotComponent({ fields, dataset }) {
    let container = useRef(); 

    useEffect(() => {
        const table = new Pivot(container.current, {
            fields,
            data: dataset,
            config: {
                rows: ["state", "product_type"],
                columns: ["product_line", "type"],
                values: [
                    {
                        field: "profit",
                        method: "sum"
                    }, // другие значения
                ]
            },
            // другие свойства конфигурации
        });

        return () => {
            table.destructor();
        }
    }, []);

    return <div ref={container} className="widget"></div>;
}

Компонент готов к использованию. При монтировании Pivot отображает переданные данные. Полный список свойств конфигурации см. в документации API Pivot.

Обработка событий

Действия пользователя в Pivot генерируют события, на которые можно подписаться. Полный список событий см. в обзоре событий.

Следующий фрагмент кода расширяет useEffect обработчиком события open-filter, который записывает в лог идентификатор поля при открытии фильтра пользователем:

Pivot.jsx

// ...
useEffect(() => {
    const table = new Pivot(container.current, {
        fields,
        data: dataset,
        config: {
            rows: ["state", "product_type"],
            columns: ["product_line", "type"],
            values: [
                {
                    field: "profit",
                    method: "sum"
                }, // другие значения
            ]
        },
        // другие свойства конфигурации
    });

    table.api.on("open-filter", (ev) => {
        console.log("The field id for which the filter is activated:", ev.id);
    });
    
    return () => {
        table.destructor();
    }
}, []);
// ...

Запустите приложение, чтобы увидеть, как Pivot отображает данные на странице.

Pivot теперь интегрирован с React. Настройте конфигурацию под требования проекта. Готовый пример см. в react-pivot-demo на GitHub.