react-kanban 源码解析(一):Board 三层组件架构与受控/非受控实现原理

react-kanban 源码解析(一):Board 三层组件架构与受控/非受控实现原理【免费下载链接】react-kanbanYet another Kanban/Trello board lib for React.项目地址: https://gitcode.com/gh_mirrors/reac/react-kanbanreact-kanban 是一个基于 React Hooks 和 react-beautiful-dnd 构建的轻量级看板Kanban/Trello 风格组件库它最大的特色是「组件化 可插拔」你既能像使用普通组件一样开箱即用也能通过渲染函数render props完全定制每一张卡片、每一列表头。本文作为 react-kanban 源码解析系列第一篇带你从零读懂它最核心的Board 三层组件架构以及看似玄妙、实则只有几行代码的受控/非受控实现原理。读完你会发现一个成熟的看板组件核心思想其实非常朴素。一、react-kanban 源码整体目录结构在动手读源码之前先建立全局地图。react-kanban 的源码集中在src目录下结构非常清晰src ├── index.js # 入口导出 Board 组件 ├── services/ │ ├── helpers.js # 看板数据的纯函数操作 │ └── utils.js # 数组/函数工具 └── components/ ├── Board/ # 看板根组件三层架构的第一层 │ ├── index.js │ ├── services/ # 拖拽坐标解析 │ └── components/ │ ├── Column/ # 列组件第二层 │ │ ├── index.js │ │ └── components/Card/ # 卡片组件第三层 │ ├── ColumnAdder/ # 新增列 │ ├── DefaultCard/ # 默认卡片外观 │ └── DefaultColumnHeader/ # 默认列表头外观 └── withDroppable/ # Droppable 高阶组件入口文件src/index.js只有两行默认导出 Board同时把 helpers 里的操作函数一并导出方便你在受控模式下自行处理数据。二、Board 三层组件架构解析所谓「三层架构」指的是Board看板→ Column列→ Card卡片的层级关系。react-beautiful-dnd 的拖拽体系要求「可拖拽项Draggable」必须被「可放置区Droppable」包裹react-kanban 的三层结构恰好与之一一对应。第一层Board 入口与模式分发src/components/Board/index.js是整个组件的神经中枢。它的职责有两个分发模式根据有没有传入initialBoard决定渲染受控还是非受控看板组装拖拽上下文通过BoardContainer提供DragDropContext。先看最关键的分发逻辑整个受控/非受控的奥秘就藏在这三行里function Board(props) { return props.initialBoard ? UncontrolledBoard {...props} / : ControlledBoard {...props} / }再看BoardContainer它负责把整块看板包进DragDropContext并渲染一个横向的Droppable通过withDroppable包装列与列之间的拖拽就是在这里发生的DragDropContext onDragEnd{handleOnDragEnd} div classNamereact-kanban-board DroppableBoard droppableIdboard-droppable directionhorizontal typeBOARD {board.columns.map((column, index) Column key{column.id} ... /)} /DroppableBoard {renderColumnAdder()} /div /DragDropContext注意typeBOARD这个细节react-beautiful-dnd 用它来区分「这次拖的是列」还是「卡片」配合src/components/Board/services/index.js里的isAColumnMove函数就能在拖拽结束时正确分流。第二层Column 列组件src/components/Board/components/Column/index.js实现第二层。每一列本身是一个Draggable可被拖去重排列的顺序列内部又包含一个DroppableColumn作为卡片的放置区Draggable draggableId{column-draggable- id}列可以横向拖动DroppableColumn droppableId{String(id)}卡片可以拖进这一列列头通过renderColumnHeader渲染默认使用DefaultColumnHeader支持重命名、删除若开启了allowAddCard还会渲染一个CardAdder用于新增卡片。一列之中「可拖 可放」的双重身份正是看板拖拽体验的灵魂。第三层Card 卡片组件src/components/Board/components/Column/components/Card/index.js是第三层也是最小单元。每张卡片是一个Draggable并借助 render prop 拿到isDragging状态Draggable draggableId{String(children.id)} index{index} isDragDisabled{disableCardDrag} {(provided, { isDragging }) ( div ref{provided.innerRef} {...provided.draggableProps} {...provided.dragHandleProps} {renderCard(isDragging)} /div )} /Draggable默认外观由DefaultCard提供显示标题、描述、删除按钮而通过renderCard你可以完全替换为自定义卡片这就是 react-kanban「可插拔」的体现。隐藏的功臣withDroppable 高阶组件src/components/withDroppable/index.js是一个小而美的 HOC它把Droppable的样板代码收敛起来让Columns和ColumnEmptyPlaceholder都能直接变成可放置区function withDroppable(Component) { return function WrapperComponent({ children, ...droppableProps }) { return ( Droppable {...droppableProps} {(provided) ( Component ref{provided.innerRef} {...provided.droppableProps} {children} {provided.placeholder} /Component )} /Droppable ) } }读到这里你会发现三层架构 HOC 的组合本质上就是一套「递归的拖拽容器」Board 装 ColumnColumn 装 Card层层嵌套职责单一。三、受控与非受控实现原理这是 react-kanban 源码解析中读者最常问的部分。受控Controlled与非受控Uncontrolled是 React 组件设计的经典模式在表单组件中很常见而 react-kanban 把它用在了「看板数据」上。如何判别就看有没有 initialBoard规则只有一条传了initialBoard→非受控组件内部用useState托管看板数据自己负责所有增删改没传initialBoard改用children传数据→受控数据完全由父组件持有组件只负责「通知」你发生了什么。非受控模式useState 一肩挑UncontrolledBoard的核心就一句话const [board, setBoard] useState(initialBoard)。之后所有操作——拖拽卡片、拖动列、新增/删除列、重命名、新增/删除卡片——都遵循同一个套路调用 helpers 里的纯函数生成新的 board 对象通过onXxx回调把新数据通知给外部可选setBoard更新内部状态。以拖拽为例function handleOnDragEnd({ source, destination, subject }, { moveCallback, notifyCallback }) { const reorderedBoard moveCallback(board, source, destination) when(notifyCallback)((callback) callback(reorderedBoard, subject, source, destination)) setBoard(reorderedBoard) }这里借助src/services/utils.js里的partialRight和when把「移动逻辑」和「通知回调」解耦代码非常函数式。受控模式组件只当「传声筒」ControlledBoard更简单——它没有自己的 state看板数据通过children传入拖拽结束时只调用回调function handleOnDragEnd({ source, destination, subject }, { notifyCallback }) { when(notifyCallback)((callback) callback(subject, source, destination)) }数据怎么变完全由父组件在onCardDragEnd/onColumnDragEnd回调里决定。这也解释了为什么src/index.js要把moveCard、moveColumn等 helpers 一并导出——受控模式下你需要在外部用它们来更新自己的 state。数据操作全靠纯函数src/services/helpers.js提供了 8 个纯函数moveCard、moveColumn、addColumn、removeColumn、changeColumn、addCard、removeCard、changeCard。它们不修改原数据而是通过展开运算符 src/services/utils.js中的addInArrayAtPosition、removeFromArrayAtPosition、changeElementOfPositionInArray等工具生成新数组保证不可变性Immutable。例如跨列移动卡片// 源列移除卡片目标列插入卡片其余列原样返回 const reorderedCardsOnSourceColumn reorderCardsOnSourceColumn((cards) removeFromArrayAtPosition(cards, fromPosition) ) const reorderedCardsOnDestinationColumn reorderCardsOnDestinationColumn((cards) addInArrayAtPosition(cards, sourceColumn.cards[fromPosition], toPosition) )四、拖拽数据流全链路回顾把前面所有模块串起来一次拖拽的完整生命周期是这样的用户拖拽结束 ↓ DragDropContext.onDragEnd (BoardContainer) ↓ getCoordinates 解析出 source / destination (Board/services) ↓ isAColumnMove 分流拖列 or 拖卡片 ↓ 非受控moveCard/moveColumn 纯函数 → 通知回调 → setBoard 受控仅通知 onCardDragEnd / onColumnDragEnd由父组件更新一条清晰的数据流把三层组件、HOC、纯函数、受控/非受控全部串了起来。五、总结与下一篇预告通过本篇 react-kanban 源码解析我们掌握了三个关键结论三层组件架构BoardDragDropContext Droppable→ ColumnDraggable Droppable→ CardDraggable层层嵌套、职责单一受控/非受控实现原理一个initialBoard判断 一个useState就完成了两种模式的无缝切换核心是「数据谁持有谁就负责变更」纯函数数据层所有增删改操作都抽离为不可变纯函数既能服务内部状态也能导出给受控用户复用。下一篇源码解析我们将深入src/services/helpers.js与utils.js拆解那些优雅的函数式工具partialRight、when、compose是如何支撑整个看板的数据操作的敬请期待。如果你正打算在自己的 React 项目中集成或改造一个看板组件不妨把这份源码当作最好的教材clone 下来边读边调试收获会远超预期。【免费下载链接】react-kanbanYet another Kanban/Trello board lib for React.项目地址: https://gitcode.com/gh_mirrors/reac/react-kanban创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考