企业官网建设流程全解析

react-kanban 受控模式必备:8 个 Helper 函数让看板状态管理事半功倍

【免费下载链接】react-kanbanYet another Kanban/Trello board lib for React.项目地址: https://gitcode.com/gh_mirrors/reac/react-kanban

react-kanban 是一个开箱即用的 React 看板（Kanban/Trello 风格）组件库。当你希望完全掌控看板数据时，受控模式是首选方案，而官方内置的 8 个 Helper 函数能让你用最少的代码完成列与卡片的增、删、改、移，让看板状态管理事半功倍。本文带你逐一吃透这 8 个函数，并附上可直接上手的实战示例。

react-kanban 受控模式与非受控模式的区别

react-kanban 的看板组件提供两种使用方式，入口判断逻辑在 Board/index.js 中一目了然：

简单说：非受控模式把状态交给库，受控模式把状态握在自己手里。受控模式下，看板数据完全由你掌控，任何改动都需要你主动更新状态，这时就需要 Helper 函数来帮忙了。

受控看板状态管理为什么需要 Helper 函数

这 8 个函数全部定义在 helpers.js，并通过 index.js 随组件一起导出。它们有三大优点：

• 🧼纯函数、无副作用：传入看板数据，返回一份全新的看板，绝不会修改原数据，完美契合 React 不可变更新理念
• 🧪100% 单元测试覆盖：测试用例写在 helpers.spec.js，官方强烈推荐直接使用
• 🔗与组件内部同源：非受控模式内部就是靠它们管理状态的，行为绝对一致

底层还借助了 utils.js 中的数组工具函数（如addInArrayAtPosition、changeElementOfPositionInArray），帮你把复杂的数组操作全部封装掉了。

一、操作列的 4 个 Helper 函数

1. moveColumn：拖拽移动列

拖拽列结束时调用，根据起始位置和终点位置重排列顺序：

const newBoard = moveColumn(board, { fromPosition: 0 }, { toPosition: 2 }) setBoard(newBoard)

2. addColumn：一键新增列

在末尾追加一个新列，新列需包含id和cards字段：

const newColumn = { id: 3, title: '已完成', cards: [] } setBoard(addColumn(board, newColumn))

3. removeColumn：快速删除列

传入要删除的列对象，即可得到移除该列后的新看板：

setBoard(removeColumn(board, column))

4. changeColumn：修改列信息

用新对象与目标列做合并，常用于重命名列或给列添加自定义字段：

setBoard(changeColumn(board, column, { title: '新的列名', wip: 5 }))

二、操作卡片的 4 个 Helper 函数

5. moveCard：拖拽移动卡片

这是最常用的函数，它的source与destination参数和onCardDragEnd回调收到的完全一致，可直接拿来用：

const handleCardDragEnd = (card, source, destination) => { setBoard((prev) => moveCard(prev, source, destination)) }

无论是同一列内排序，还是跨列移动，它都能正确处理。

6. addCard：新增看板卡片

第三个参数{ on: 'top' }控制插入位置，默认插到底部：

const newCard = { id: 99, title: '新任务', description: '描述' } setBoard(addCard(board, column, newCard)) // 默认底部 setBoard(addCard(board, column, newCard, { on: 'top' })) // 插入顶部

7. removeCard：删除指定卡片

传入所在列和卡片对象，即可安全移除：

setBoard(removeCard(board, column, card))

8. changeCard：修改卡片信息

通过cardId定位卡片，再合并新属性，适合更新标题、描述或自定义字段：

setBoard(changeCard(board, 99, { title: '更新后的标题', priority: 'high' }))

react-kanban 受控模式实战：useState 管理看板状态

下面是一个完整的受控看板最小示例，覆盖拖拽移动卡片、添加卡片和删除卡片三个高频操作：

import { useState } from 'react' import Board, { moveCard, addCard, removeCard } from '@asseinfo/react-kanban' import '@asseinfo/react-kanban/dist/styles.css' const initialBoard = { columns: [ { id: 1, title: '待办', cards: [{ id: 1, title: '写 react-kanban 教程' }] }, { id: 2, title: '进行中', cards: [] }, { id: 3, title: '已完成', cards: [] }, ], } function App() { const [board, setBoard] = useState(initialBoard) const handleCardDragEnd = (card, source, destination) => setBoard((prev) => moveCard(prev, source, destination)) const handleAddCard = (column, title) => setBoard((prev) => addCard(prev, column, { id: Date.now(), title })) const handleRemoveCard = (column, card) => setBoard((prev) => removeCard(prev, column, card)) return ( <Board onCardDragEnd={handleCardDragEnd} renderCard={({ title }, { dragging }) => ( <div> {title} <button onClick={() => handleRemoveCard(column, card)}>删除</button> </div> )} > {board} </Board> ) }

核心思路只有一句话：所有操作都先调用 Helper 函数拿到新看板，再setBoard更新状态。

看板状态管理的常见坑与注意事项

• ⚠️id 必须唯一：列和卡片的id是 Helper 函数定位元素的依据，新增时记得用Date.now()或自增计数器生成
• ⚠️函数不改原对象：它们总是返回新看板，千万别用返回值去覆盖引用后还期待原数据变化
• ⚠️受控模式用children传数据：同时传children和initialBoard会走非受控逻辑，容易踩坑
• 💡想调试源码：可以git clone https://gitcode.com/gh_mirrors/reac/react-kanban后直接阅读 helpers.js 的实现

掌握了这 8 个 Helper 函数，react-kanban 受控模式下的看板状态管理就不再是难题。赶紧把moveColumn、addCard这些函数用起来，让你的看板项目开发效率翻倍吧！

【免费下载链接】react-kanbanYet another Kanban/Trello board lib for React.项目地址: https://gitcode.com/gh_mirrors/reac/react-kanban