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

совет

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

DHTMLX Kanban совместим с React. Мы подготовили примеры кода, показывающие, как использовать DHTMLX Kanban с React. Подробности смотрите в соответствующем примере на GitHub.

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

информация

Перед созданием нового проекта установите Vite (опционально) и Node.js.

Вы можете создать базовый проект React или использовать React с Vite. Назовём проект my-react-kanban-app:

npx create-react-app my-react-kanban-app

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

Перейдите в директорию созданного приложения:

cd my-react-kanban-app

Установите зависимости и запустите dev-сервер. Для этого используйте менеджер пакетов:

если вы используете yarn, выполните следующие команды:

yarn
yarn start

если вы используете npm, выполните следующие команды:

npm install
npm run dev

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

Создание Kanban

Теперь необходимо получить исходный код DHTMLX Kanban. Сначала остановите приложение и приступайте к установке пакета Kanban.

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

Скачайте пробный пакет Kanban и выполните шаги, описанные в файле README. Обратите внимание, что пробная версия Kanban доступна только 30 дней.

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

Теперь необходимо создать компонент React, чтобы добавить Kanban в приложение. Создайте новый файл в директории src/ и назовите его Kanban.jsx.

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

Откройте файл Kanban.jsx и импортируйте исходные файлы Kanban. Обратите внимание:

если вы используете PRO-версию и устанавливаете пакет Kanban из локальной папки, пути к импортам будут следующими:

Kanban.jsx
import { Kanban, Toolbar } from 'dhx-kanban-package';
import 'dhx-kanban-package/dist/kanban.css';

Учтите, что в зависимости от используемого пакета исходные файлы могут быть минифицированы. В этом случае убедитесь, что импортируете CSS-файл как kanban.min.css.

если вы используете пробную версию Kanban, укажите следующие пути:

Kanban.jsx
import { Kanban, Toolbar } from '@dhx/trial-kanban';
import "@dhx/trial-kanban/dist/kanban.css";

В этом руководстве показано, как настроить пробную версию Kanban.

Чтобы отобразить Kanban с Toolbar на странице, необходимо создать контейнеры для Kanban и Toolbar и инициализировать эти компоненты с помощью соответствующих конструкторов:

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

export default function KanbanComponent(props) {
    let toolbar_container = useRef(); // инициализация контейнера для Toolbar
    let kanban_container = useRef(); // инициализация контейнера для Kanban

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

        // инициализация компонента Toolbar
        const toolbar = new Toolbar(toolbar_container.current, {
            api: kanban.api, // передача внутреннего API Kanban
            // другие параметры конфигурации
        });

        return () => {
            kanban.destructor(); // уничтожение Kanban
            toolbar.destructor(); // уничтожение Toolbar
        };
    }, []);

    return  <div className="component_container">
                <div ref={toolbar_container}></div>
                <div ref={kanban_container} className="widget"></div>
            </div>
}

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

Для корректного отображения Kanban необходимо задать основные стили для Kanban и его контейнера в основном css-файле проекта:

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

/* стили для контейнера Kanban и Toolbar */
.component_container {
    height: 100%; 
    margin: 0 auto;
}

/* стили для контейнера Kanban */
.widget {
    height: calc(100% - 56px);
}

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

Чтобы добавить данные в Kanban, необходимо предоставить набор данных. Вы можете создать файл data.js в директории src/ и добавить в него данные:

data.js
export function getData() {
    const columns = [
        {
            label: "Backlog",
            id: "backlog"
        },
        {
            label: "In progress",
            id: "inprogress"
        },
        // ...
    ];

    const cards = [
        {
            id: 1,
            label: "Integration with Angular/React",
            priority: 1,
            color: "#65D3B3",
            start_date: new Date("01/07/2021"),
            users: [3, 2],
            column: "backlog",
            type: "feature",
        },
        {
            label: "Archive the cards/boards ",
            priority: 3,
            color: "#58C3FE",
            users: [4],
            progress: 1,
            column: "backlog",
            type: "feature",
        },
        // ...
    ];

    const rows = [
        {
            label: "Feature",
            id: "feature",
        },
        {
            label: "Task",
            id: "task",
        }
    ];

    return { columns, cards, rows };
}

Затем откройте файл App.js и импортируйте данные. После этого можно передать данные в созданный компонент <Kanban/> через props:

App.js
import Kanban from "./Kanban";
import { getData } from "./data";

function App() {
    const { columns, cards, rows } = getData();
    return <Kanban columns={columns} cards={cards} rows={rows} />;
}

export default App;

Перейдите в файл Kanban.jsx и примените переданные props к объекту конфигурации Kanban:

Kanban.jsx
import { useEffect, useRef } from "react";
import { Kanban, Toolbar } from "@dhx/trial-kanban";
import "@dhx/trial-kanban/dist/kanban.css";

export default function KanbanComponent(props) {
    let kanban_container = useRef();
    let toolbar_container = useRef();

    useEffect(() => {
        const kanban = new Kanban(kanban_container.current, {
            columns: props.columns, // данные для колонок
            cards: props.cards, // данные для карточек
            rows: props.rows, // данные для строк
            rowKey: "type",
            // другие параметры конфигурации
        });

        const toolbar = new Toolbar(toolbar_container.current, {
            api: kanban.api,
            // другие параметры конфигурации
        });

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

    return  <div className="component_container">
                <div ref={toolbar_container}></div>
                <div ref={kanban_container} className="widget"></div>
            </div>
}

Также можно использовать метод parse() внутри метода useEffect() в React для загрузки данных в Kanban:

Kanban.jsx
import { useEffect, useRef } from "react";
import { Kanban, Toolbar } from "@dhx/trial-kanban";
import "@dhx/trial-kanban/dist/kanban.css";

export default function KanbanComponent(props) {
    let kanban_container = useRef();
    let toolbar_container = useRef();

    let columns = props.columns; // данные для колонок
    let cards = props.cards; // данные для карточек
    let rows = props.rows; // данные для строк

    useEffect(() => {
        const kanban = new Kanban(kanban_container.current, {
            columns: [],
            cards: [],
            rows: [],
            rowKey: "type",
            // другие параметры конфигурации
        });

        const toolbar = new Toolbar(toolbar_container.current, {
            api: kanban.api,
            // другие параметры конфигурации
        });
    
        kanban.parse({ columns, cards, rows });

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

    return  <div className="component_container">
                <div ref={toolbar_container}></div>
                <div ref={kanban_container} className="widget"></div>
            </div>
}

Метод parse(data) позволяет перезагружать данные при каждом изменении.

Теперь компонент Kanban готов. Когда элемент будет добавлен на страницу, он инициализирует Kanban с данными. Вы также можете задать необходимые настройки конфигурации. Посетите документацию по API Kanban, чтобы ознакомиться с полным списком доступных свойств.

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

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

Откройте Kanban.jsx и дополните метод useEffect() следующим образом:

Kanban.jsx
// ...
useEffect(() => {
    const kanban = new Kanban(kanban_container.current, {});

    kanban.api.on("add-card", (obj) => {
        console.log(obj.columnId);
    });
    
    return () => {
        kanban.destructor();
    };
}, []);
// ...

После этого вы можете запустить приложение и увидеть Kanban с загруженными данными на странице.

Теперь вы знаете, как интегрировать DHTMLX Kanban с React. Вы можете доработать код в соответствии с вашими требованиями. Финальный расширенный пример доступен на GitHub.

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

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

Создание Kanban​

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

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

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

Задание контейнеров и добавление Kanban с Toolbar​

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

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

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