跳至主要内容

配置

您可以通过以下属性配置 Kanban 的外观和功能：

卡片​

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 = [ // users data
    { id: 1, label: "John Smith", avatar: "../assets/user.jpg" },
    { id: 2, label: "Aaron Short" }
];

const  cardPriority = [ // card priority data
    { id: 1, color: "#FF5252", label: "high" },
    { id: 2, color: "#FFC975", label: "medium" },
    { id: 3, color: "#0AB169", label: "low" }
];

const cardShape = { // cards settings
    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", {
    // cards data
    columns,
    cards,
    // cards settings
    cardShape
});
注释

如果未通过 cardShape 属性指定卡片设置，控件将回退至 defaultCardShape。

编辑器​

Kanban 编辑器包含用于管理卡片数据的字段。使用 editorShape 属性配置编辑器字段。可用的字段类型如下：

信息

通过 editor.placement 属性将编辑器显示为侧边栏或模态窗口。

Combo、Select 和 Multiselect 类型​

以下代码片段配置了用于选择卡片优先级的下拉框：

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "combo", // 或 "select" 和 "multiselect"
            key: "priority", // 在 "cardShape" 属性中使用 "priority" 键
            label: "Priority",
            values: [
                { id: 1, label: "high" },
                { id: 2, label: "medium" },
                { id: 3, label: "low" }
            ]
        },
        // 其他字段设置
    ]
});
信息

对于 multiselect 和 combo 字段，可通过 avatar 属性设置预览图片路径：

editorShape: [
    {
        type: "multiselect", // 或 "combo"
        key: "users", // 在 "cardShape" 属性中使用 "users" 键
        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", // 在 "cardShape" 属性中使用 "color" 键
            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", // 在 "cardShape" 属性中使用 "progress" 键
            label: "Progress",
            config: {
                min: 10,
                max: 90,
                step: 5
            }
        },
        // 其他字段设置
    ]
});

Files 类型​

将 uploadURL 参数设为字符串可进行基本上传，设为函数则可自定义请求。

以字符串配置上传地址​

以下代码片段为文件上传器使用字符串 URL：

const url = "https://docs.dhtmlx.com/kanban-backend";
new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "files", 
            key: "attached", // 在 "cardShape" 属性中使用 "attached" 键
            label: "Attachment",
            uploadURL: url + "/uploads", // 以字符串设置 URL
            config: {
                accept: "image/*", // "video/*", "audio/*"
                disabled: false,
                multiple: true,
                folder: false
            }
        },
        // 其他字段设置
    ]
});

以函数配置上传地址​

向 uploadURL 传入函数可添加自定义 header、token 或响应处理逻辑。以下代码片段通过 bearer token 发送每个文件：

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 或其他 header
                    }
                };

                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
            }
        },
        // 其他字段设置
    ]
});

以下代码片段配置了编辑器的链接字段：

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "links",
            key: "links",
            label: "Links",
            config: {
                confirmDeletion: true
            }
        },
        // 其他字段设置
    ]
});

绑定编辑器字段与卡片字段​

每个编辑器字段通过共享的 key 与卡片字段关联。在 editorShape 条目和 cardShape 属性中设置相同的 key 值。对于内置卡片字段，将 key 设为 true；对于自定义字段，在 headerFields 数组中列出该 key。同一 key 也用于提供卡片的初始数据。

以下代码片段将编辑器的 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, // 内置字段的 key
    headerFields: [
        {
            key: "note", // 自定义字段的 key
            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 属性控制编辑器的可见性、自动保存和位置：

以下代码片段启用自动保存并设置 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 时，懒加载渲染将无法正确显示卡片。

变更历史​

Kanban 记录卡片操作，并在工具栏上提供撤销和重做控件。使用 history 属性可禁用此功能。

以下代码片段禁用历史记录跟踪：

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

若要跳过历史记录中的个别操作，请向方法或事件传递 $meta 参数。

工具栏​

Kanban 的工具栏提供搜索框、排序控件以及添加列和行的控件。使用 kanban.Toolbar() 构造函数在独立容器中初始化工具栏。

以下代码片段创建绑定到 Kanban 实例的工具栏：

// 创建 Kanban
const board = new kanban.Kanban("#root", {
    // 数据
    columns,
    cards,
    rows,
    // 卡片设置
    cardShape,
    // 编辑器设置
    editorShape
});

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

使用 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", // 添加新行
        // 自定义元素
    ]
});
提示

从 items 数组中移除某控件即可将其隐藏。

示例​

以下代码片段配置了 Kanban 的卡片、编辑器和工具栏：

Need more help?Contact Support