Конфигурация

Вы можете настраивать внешний вид и функциональность Kanban с помощью следующих свойств:

cardShape - настройка внешнего вида карточек и встроенных полей
editorShape - определение полей редактора
editor - управление видимостью редактора, автосохранением и расположением
renderType, scrollType - настройка рендеринга карточек и прокрутки доски
history - управление историей операций с карточками
cardTemplate - кастомизация внешнего вида карточек (см. раздел Кастомизация)
locale - применение локализации (см. раздел Локализация)
cards, columns, rows, links - загрузка данных для карточек, колонок, строк и связей (см. раздел Работа с данными)

Карточки

Доска Kanban состоит из карточек, распределённых по колонкам и строкам. Используйте свойство cardShape для настройки внешнего вида карточек и встроенных полей:

label: boolean | { show } - метка карточки, редактируется с помощью типа text
description: boolean | { show } - описание карточки, редактируется с помощью типа textarea
progress: boolean | { show } - прогресс карточки, редактируется с помощью типа progress
start_date: boolean | { show, format } - дата начала карточки, редактируется с помощью типа date
end_date: boolean | { show, format } - дата окончания карточки, редактируется с помощью типа date
menu: boolean | { show, items } - контекстное меню карточки
attached: boolean | { show } - вложения карточки, редактируются с помощью типа files
color: boolean | { show, values } - верхняя цветная полоска карточки, редактируется с помощью типа color
cover: boolean | { show } - превью-изображение карточки
comments: boolean | { show } - комментарии к карточке
confirmDeletion: boolean | { show } - диалог подтверждения удаления карточки
votes: boolean | { show, clickable } - голосование по карточке
users: boolean | { show, values, maxCount } - пользователи, назначенные на карточку, редактируются с помощью типов combo, select или multiselect
priority: boolean | { show, values } - приоритет карточки, редактируется с помощью типа combo или select
css: (card) => string - функция, возвращающая CSS-класс, применяемый к карточке по условию
headerFields: [{ key, label, css }] - кастомные поля карточки

Подсказка

При активации поля в cardShape редактор автоматически отображает соответствующий контрол. Настройте каждый контрол через свойство editorShape. Доступные типы описаны в разделе Редактор.

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

const users = [ // данные пользователей
    { id: 1, label: "John Smith", avatar: "../assets/user.jpg" },
    { id: 2, label: "Aaron Short" }
];

const  cardPriority = [ // данные приоритета карточек
    { id: 1, color: "#FF5252", label: "high" },
    { id: 2, color: "#FFC975", label: "medium" },
    { id: 3, color: "#0AB169", label: "low" }
];

const cardShape = { // настройки карточек
    label: true,
    description: true,
    progress: true,
    start_date: true,
    end_date: true,
    menu: true,
    attached: true,
    priority: {
        show: true,
        values: cardPriority
    },
    users: {
        show: true,
        values: users
    },
    headerFields: [
        {
            key: "sprint",
            label: "Custom field",
            css: "custom_css_class"
        }
    ]
};

new kanban.Kanban("#root", {
    // данные карточек
    columns,
    cards,
    // настройки карточек
    cardShape
});

Примечание

Если вы не укажете настройки карточек через свойство cardShape, виджет применит набор параметров defaultCardShape.

Редактор

Редактор Kanban содержит поля для управления данными карточек. Используйте свойство editorShape для настройки полей редактора. Доступны следующие типы полей:

combo, select, multiselect - выпадающие списки
color - выбор цвета
text, textarea - текстовые поля
progress - слайдер прогресса
files - загрузчик файлов
date, dateRange - одиночная дата или диапазон дат
comments - комментарии к карточке
links - связи карточки

К сведению

Отображайте редактор как боковую панель или модальное окно с помощью свойства editor.placement.

Типы Combo, Select и Multiselect

Следующий пример настраивает выпадающий список для выбора приоритета карточки:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "combo", // или "select" и "multiselect"
            key: "priority", // используйте ключ "priority" в свойстве "cardShape"
            label: "Priority",
            values: [
                { id: 1, label: "high" },
                { id: 2, label: "medium" },
                { id: 3, label: "low" }
            ]
        },
        // настройки других полей
    ]
});

К сведению

Для полей типа multiselect и combo укажите путь к превью-изображению через свойство avatar:

editorShape: [
    {
        type: "multiselect", // или "combo"
        key: "users", // используйте ключ "users" в свойстве "cardShape"
        label: "Users",
        values: [
            { 
                id: 1, label: "Alan", 
                avatar: "preview_image_path_1.png" 
            },
            { 
                id: 2, label: "John", 
                avatar: "preview_image_path_2.png" 
            }
        ]
    },
    // настройки других полей
]

Kanban. Ограничение назначения только одним пользователем

Тип Color

Следующий пример настраивает поле редактора для выбора цвета карточки:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "color", 
            key: "color", // используйте ключ "color" в свойстве "cardShape"
            label: "Card color",
            values: ["#65D3B3", "#FFC975", "#58C3FE"],
            config: {
                clear: true,
                placeholder: "Select color"
            }
        },
        // настройки других полей
    ]
});

Типы Text и Textarea

Следующий пример настраивает поле редактора для ввода метки карточки:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "text", // или "textarea"
            key: "label",
            label: "Label",
            config: {
                placeholder: "Type your tips here", 
                readonly: false, 
                focus: true,
                disabled: false,
                inputStyle: "height: 50px;"
            }
        },
        // настройки других полей
    ]
});

Тип Progress

Следующий пример настраивает поле редактора для установки прогресса карточки:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "progress", 
            key: "progress", // используйте ключ "progress" в свойстве "cardShape"
            label: "Progress",
            config: {
                min: 10,
                max: 90,
                step: 5
            }
        },
        // настройки других полей
    ]
});

Тип Files

Укажите строку в параметре uploadURL для базовой загрузки или функцию для кастомного запроса.

Настройка uploadURL как строки

Следующий пример использует строковый URL для загрузчика файлов:

const url = "https://docs.dhtmlx.com/kanban-backend";
new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "files", 
            key: "attached", // используйте ключ "attached" в свойстве "cardShape"
            label: "Attachment",
            uploadURL: url + "/uploads", // указать URL как строку
            config: {
                accept: "image/*", // "video/*", "audio/*"
                disabled: false,
                multiple: true,
                folder: false
            }
        },
        // настройки других полей
    ]
});

Настройка uploadURL как функции

Передайте функцию в uploadURL для добавления кастомных заголовков, токенов или обработки ответа. Следующий пример отправляет каждый файл с токеном авторизации:

const url = "https://docs.dhtmlx.com/kanban-backend";
new kanban.Kanban("#root", {
    editorShape: [
        ...defaultEditorShape,
        {
            key: "attached",
            type: "files",
            label: "Files",
            uploadURL: rec => {
                const formData = new FormData();
                formData.append("upload", rec.file);

                const config = {
                    method: "POST",
                    body: formData,
                    headers: {
                        'Authorization': 'Bearer ' + token  // token или другие заголовки
                    }
                };

                return fetch(url + "/uploads", config) // URL
                    .then(res => res.json())
                    .then(
                        data => {
                            return { id: rec.id, ...data };
                        },
                        () => ({ id: rec.id, status: "error" })
                    )
                    .catch();
            }
        }
    ]
});

Типы Date и DateRange

Следующий пример настраивает поле редактора для одиночной даты:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "date", 
            key: "start_date",
            label: "Start date",
            format: "%d/%m/%y"
        },
        // настройки других полей
    ]
});

Следующий пример настраивает поле редактора для диапазона дат начала и окончания:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "dateRange", 
            key: {
                start: "start_date",
                end: "end_date"
            },
            label: "Date Range",
            format: "%d/%m/%y"
        },
        // настройки других полей
    ]
});

Тип Comments

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

new kanban.Kanban("#root", {
    editorShape: [
       {
            type: "comments",
            key: "comments",
            label: "Comments",
            config: {
                dateFormat: "%M %d",
                placement: "page", // или "editor"
                html: true,
                confirmDeletion: true
            }
        },
        // настройки других полей
    ]
});

Тип Links

Следующий пример настраивает поле связей редактора:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "links",
            key: "links",
            label: "Links",
            config: {
                confirmDeletion: true
            }
        },
        // настройки других полей
    ]
});

Привязка полей редактора к полям карточки

Каждое поле редактора связывается с полем карточки через общий key. Укажите одинаковое значение key в записи editorShape и в свойстве cardShape. Для встроенных полей карточки установите ключ в true. Для кастомных полей перечислите ключ в массиве headerFields. Этот же ключ предоставляет начальные данные карточки.

Следующий пример привязывает поля редактора label и note к соответствующим полям карточки:

// настройки редактора
const editorShape = [ 
    { 
        type: "text",
        key: "label",
        label: "Label",
        config: {
            placeholder: "Enter new label here"
        }
    },
    { 
        type: "textarea",
        key: "note",
        label: "Note",
        config: {
            placeholder: "Enter usefull note here"
        }
    }
];
// настройки карточек
const cardShape = {
    label: true, // ключ встроенного поля
    headerFields: [
        {
            key: "note", // ключ кастомного поля
            label: "Note"
        }
    ]
};
// данные карточек
const cards = [
    {
        label: "Volvo",
        note: "It is the swedish car",
        column: "backlog"
    },
    {
        label: "Audi",
        note: "It is the german car",
        column: "backlog"
    }
];
// создать Kanban
new kanban.Kanban("#root", {
    editorShape,
    cardShape,
    cards,
    columns
    // другие параметры конфигурации
});

Примечание

Если вы не укажете настройки редактора через свойство editorShape, виджет применит набор параметров defaultEditorShape. Стандартные контролы и поля появятся в редакторе только после активации соответствующих полей карточек через свойство cardShape.

Настройка редактора

Свойство editor управляет видимостью редактора, автосохранением и расположением:

editor.show - включить или отключить редактор
editor.placement - отображать редактор как "sidebar" или "modal" окно
editor.autoSave - включить или отключить режим автосохранения
editor.debounce - задержка перед автосохранением (применяется только с autoSave: true)

Следующий пример включает автосохранение с задержкой 2 секунды:

// создать Kanban
new kanban.Kanban("#root", {
    columns,
    cards,
    editorShape,
    editor: {
        autoSave: true,
        debounce: 2000
    }
    // другие параметры
});

Рендеринг и прокрутка

По умолчанию виджет Kanban рендерит все карточки и прокручивает всю доску целиком. Для досок с большим количеством карточек переключитесь на ленивый рендеринг или прокрутку по колонкам:

renderType - установите значение "lazy" для рендеринга только видимых на доске карточек
scrollType - установите значение "column" для независимой прокрутки каждой колонки

Следующий пример включает ленивый рендеринг и прокрутку по колонкам:

new kanban.Kanban("#root", {
    columns,
    cards,
    rows,
    renderType: "lazy",
    scrollType: "column",
    cardHeight: 150
});

important

При совместном использовании renderType: "lazy" с любым scrollType задайте статическую высоту карточек через свойство cardHeight. Без cardHeight ленивый рендеринг не отображает карточки корректно.

Если cardHeight не указан при использовании renderType: "lazy" и scrollType: "column", виджет применяет экспериментальное приближение высоты карточек на основе видимых полей в cardShape. Для досок с кастомным cardTemplate виджет не может предсказать итоговую высоту. Передайте кастомную функцию getCardHeight(cardShape, card, cardWidth), возвращающую ожидаемую высоту карточки.

История изменений

Kanban отслеживает операции с карточками и предоставляет контролы отмены и повтора действий на Toolbar. Используйте свойство history для отключения этого поведения.

Следующий пример отключает отслеживание истории:

new kanban.Kanban("#root", {
    columns,
    cards,
    history: false
});

Подсказка

Чтобы исключить отдельные операции из истории, передайте параметр $meta в методы или события.

Toolbar Kanban предоставляет строку поиска, контролы сортировки и контролы для добавления колонок и строк. Инициализируйте Toolbar в отдельном контейнере с помощью конструктора kanban.Toolbar().

Следующий пример создаёт Toolbar, привязанный к экземпляру Kanban:

// создать Kanban
const board = new kanban.Kanban("#root", {
    // данные
    columns,
    cards,
    rows,
    // настройки карточек
    cardShape,
    // настройки редактора
    editorShape
});

new kanban.Toolbar("#toolbar", { api: board.api });

Используйте свойство items для отображения, скрытия или кастомизации контролов Toolbar. Следующий пример задаёт кастомную строку поиска, контролы отмены и повтора, кастомную сортировку и контролы колонок и строк:

// создать Kanban
const board = new kanban.Kanban("#root", {...});

new kanban.Toolbar("#toolbar", {
    api: board.api,
    items: [
        { // кастомная строка поиска
            type: "search",
            options: [
                {
                    id: "label",
                    label: "By label"
                },
                {
                    id: "start_date",
                    label: "By date",
                    searchRule: (card, value, by) => {
                        const date = card[by];
                        return date?.toString().includes(value);
                    }
                }
            ],
            resultTemplate: kanban.template(({ result }) => {
                return `<div className="list-item">
                            <div className="list-item-text">${result.label}</div>
                            ${result.description ? `<div className="list-item-text item-description">${result.description}</div>` : ""}
                        </div>`
            })
        },
        "spacer", // пустое пространство
        "undo", // отмена операций с карточками из истории
        "redo", // повтор операций с карточками из истории
        { // кастомный контрол сортировки
            type: "sort",
            options: [
                {
                    text: "Sort by label",
                    by: "label",
                    dir: "asc"
                },
                {
                    text: "Sort by description",
                    by: "description",
                    dir: "desc"
                }
            ]
        },
        "addColumn", // контрол для добавления новых колонок
        "addRow", // контрол для добавления новых строк
        // кастомные элементы
    ]
});

Подсказка

Удалите контрол из массива items, чтобы скрыть его.

Пример

Следующий сниппет настраивает карточки, редактор и Toolbar Kanban:

Карточки​

Редактор​

Типы Combo, Select и Multiselect​

Тип Color​

Типы Text и Textarea​

Тип Progress​

Тип Files​

Настройка uploadURL как строки​

Настройка uploadURL как функции​

Типы Date и DateRange​

Тип Comments​

Тип Links​

Привязка полей редактора к полям карточки​

Настройка редактора​

Рендеринг и прокрутка​

История изменений​

Toolbar​

Пример​

Карточки

Редактор

Типы Combo, Select и Multiselect

Тип Color

Типы Text и Textarea

Тип Progress

Тип Files

Настройка uploadURL как строки

Настройка uploadURL как функции

Типы Date и DateRange

Тип Comments

Тип Links

Привязка полей редактора к полям карточки

Настройка редактора

Рендеринг и прокрутка

История изменений

Toolbar

Пример