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

Виджет Kanban можно настраивать как по внешнему виду, так и по функционалу с помощью его API. Доступно множество параметров, которые можно изменить, например:

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

Карточки

В Kanban карточки структурированы по колонкам и строкам. Вы можете управлять их отображением и содержимым с помощью свойства cardShape. Доступно несколько встроенных полей, которые можно включать или скрывать:

Название карточки с помощью опции label: boolean
Описание карточки с помощью опции description: boolean

совет

Оба поля - label и description - можно редактировать через редактор Kanban. Если они включены, соответствующие поля ввода появятся автоматически. Эти поля задаются через типы text и textarea.

Индикатор прогресса через progress: boolean

совет

Поле progress также доступно для редактирования через редактор Kanban. Если оно включено, элемент управления появляется автоматически. Это настраивается через тип progress.

Дата начала через start_date: boolean
Дата окончания через end_date: boolean

совет

Поля start date и end date управляются контролами редактора Kanban. Если поля активны - контролы появятся автоматически. Для их настройки используйте тип date.

Контекстное меню карточки через menu: boolean
Вложения с помощью attached: boolean

совет

К карточкам можно прикреплять файлы через редактор Kanban. Это реализовано с помощью типа files.

Цвет карточки через color: boolean

совет

Верхняя цветная линия карточки управляется контролом редактора Kanban. Если включено color, автоматически появится цветовой селектор. Используется тип color.

Обложка карточки (превью) через cover: boolean
Комментарии к карточкам через comments: boolean
Диалог подтверждения удаления карточек с помощью confirmDeletion: boolean
Голосование по карточкам через votes: boolean | { show: boolean, clicable: true }
Назначение пользователей через users: boolean | { show: boolean, values: object, maxCount: number | false }

совет

Назначение пользователей на карточки осуществляется через контрол редактора Kanban. Для выбора только одного пользователя используйте типы combo или select. Для выбора нескольких - multiselect.

Поле приоритета через priority: boolean | { show: boolean, values: object }

совет

Приоритет карточки настраивается через контрол редактора Kanban. При включении priority контрол появляется автоматически. Здесь используются только типы combo или select.

Пользовательские поля можно добавить в headerFields: [ { key: string, label: string, css: string } ]

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, Kanban использует настройки defaultCardShape!

Редактор

информация

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

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

combo, select и multiselect
color
text и textarea
progress
files
date и dataRange
comments
links

Типы 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

Загрузку файлов в редактор можно настроить двумя способами:

Передача Upload 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
            }
        },
        // настройки других полей
    ]
});

Передача Upload Url функцией

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  // токен или другие заголовки
                    }
                };

                return fetch(url + "/uploads", config) // URL
                    .then(res => res.json())
                    .then(
                        data => {
                            rec.id = data.id;
                            return 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 в объекте editorShape (key: "editor_field_key"). Для встроенных полей карточки убедитесь, что этот ключ включён (значение true) в cardShape. Для пользовательских полей добавьте его в массив headerFields. Также можно задать начальное значение для любого поля с этим ключом.

// настройки редактора
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.autoSave
Указать задержку автосохранения через editor.debounce (работает только при autoSave: true)

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

Панель инструментов

Панель инструментов Kanban включает строку поиска (для поиска карточек), элементы сортировки и кнопки для добавления новых колонок или строк. Для использования Toolbar инициализируйте её в отдельном контейнере через kanban.Toolbar().

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

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

Элементы Toolbar можно показать, скрыть или изменить с помощью свойства items:

// создание 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(searchResult => {
                return `<div className="list-item">
                            <div className="list-item-text">${searchResult.result.label}</div>
                            ${searchResult.result.description ? `<div className="list-item-text item-description">${searchResult.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", // добавление новых строк
        // дополнительные элементы
    ]
});

совет

Чтобы скрыть некоторые элементы Toolbar, просто уберите соответствующие строки из массива items.

Пример

Ниже пример настройки Карточек, Редактора и Панели инструментов для Kanban:

Карточки​

Редактор​

Типы Combo, Select и Multiselect​

Тип Color​

Типы Text и Textarea​

Тип Progress​

Тип Files​

Передача Upload Url строкой​

Передача Upload Url функцией​

Типы Date и DateRange​

Тип Comments​

Тип Links​

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

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

Панель инструментов​

Пример​

Карточки

Редактор

Типы Combo, Select и Multiselect

Тип Color

Типы Text и Textarea

Тип Progress

Тип Files

Передача Upload Url строкой

Передача Upload Url функцией

Типы Date и DateRange

Тип Comments

Тип Links

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

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

Панель инструментов

Пример