react-beautiful-dnd 贡献指南全解析从提交 Issue 到合入 PR 的完整参与路径【免费下载链接】react-beautiful-dndBeautiful and accessible drag and drop for lists with React项目地址: https://gitcode.com/gh_mirrors/re/react-beautiful-dndreact-beautiful-dnd简称 rbd是一个基于 React 的、面向列表场景的美观且无障碍的拖拽库。本文以仓库根目录的 CONTRIBUTING.md 为骨架结合仓库内真实源码Redux 状态机、Flow 类型标注、jest/cypress 双测试体系逐条拆解该项目维护者期望的贡献流程文档如何提交、Bug 如何报告与修复、功能请求为何必须先讨论再动手、大型贡献需要补齐哪些技术栈知识以及无测试不合入、破坏性能不合入、类型不完整不合入等硬性红线。读完本文你将掌握向该仓库提交高质量贡献的完整路径也能借此理解一个性能至上、类型严谨的开源拖拽库内部是如何被设计与验证的。贡献类型总览四条并行通道维护者将贡献分为四类分别对应不同的入口与流程贡献类型入口是否可直接提 PR文档改进Documentation直接发起 Pull Request✅ 可以Bug 报告与修复Bug先在 Issue 页创建 Issue⚠️ 建议先报告功能请求Feature request先创建 Issue 讨论❌ 禁止直接提 PR大型贡献Large contributions先补齐技术栈知识再行动⚠️ 视情况下面按这四条通道逐一展开。文档贡献最低门槛的入口如果你认为 docs 目录下的任何文档可以改进补全示例、修正措辞、增加图解维护者的态度非常开放直接发起 Pull Request 即可不需要事先创建 Issue。仓库的文档体系非常庞大覆盖安装docs/about/installation.md、设计原则docs/about/design-principles.md、无障碍docs/about/accessibility.md、动画docs/about/animations.md、三类传感器docs/sensors/mouse.md、docs/sensors/keyboard.md、docs/sensors/touch.md、API 参考docs/api/drag-drop-context.md、docs/api/draggable.md、docs/api/droppable.md以及各种进阶指南。而且文档质量本身是受测试保护的——仓库在 test/unit/docs/content.spec.js 与 test/unit/docs/no-broken-links.spec.js 中对文档内容和链接有效性做了自动化校验这意味着你的文档 PR 同样会被 CI 检查。Bug 报告与修复Issue 先行欢迎自荐修复发现 Bug 时你可以在项目的 Issue 页面提交报告创建 Issue 时会被引导填写项目希望了解的具体细节复现步骤、环境、预期行为与真实行为等。如果你愿意亲自修复维护者同样欢迎。修复 Bug 的 PR 通常走报告 → 讨论 → 修复 → 补测试的路径因为按照仓库的硬性规定没有测试的变更不会被接受详见下文测试文化一节。从源码结构看Bug 往往发生在状态机src/state 下的 reducer 与中间件、尺寸采集src/state/dimension-marshal或传感器src/view/use-sensor-marshal这几个核心区域对应的单测散落在 test/unit/state 与 test/unit/view 中可以先读懂现有测试再动手。功能请求先讨论、再实现严禁直接提 PR这是整个贡献指南中措辞最严厉的一节维护者明确要求请不要直接为功能请求发起 Pull Request。原因是这个库是有主见的opinionated不是通用拖拽库因此不会支持每一种拖拽交互。正确流程分四步先读 README.md理解这个库的定位与动机。README 明确指出它是为列表而生的更高层抽象支持垂直/水平列表、跨列表移动、嵌套列表但不提供react-dnd那种通用拖拽原语的广度。如果你的需求超出了列表场景很可能不会被采纳。检索已有的 open 与 closed Issue确认你的功能是否已被请求过避免重复劳动。为功能请求准备一套清晰、通用的键盘操作方案keyboard story。这一条直接呼应了项目无障碍优先的核心特性——rbd 为键盘与读屏器提供了开箱即用的完整支持任何新增功能都必须在键盘这条路径上站得住脚。创建 Issue 展开讨论等维护者与社区确认可行性后再考虑实现。即使讨论通过也可能因为库的定位原因最终不被加入——这也是先讨论的意义所在。仓库的设计原则文档docs/about/design-principles.md与功能集清单README.md 的 Currently supported feature set 一节可以作为你判断这个功能是否属于 rbd 边界的参考。大型贡献动手前先建立技术知识地图如果打算做一次大型贡献维护者强烈建议先了解该仓库所用的技术栈与设计思路。这些知识不仅用于本次贡献也是长期参与这个项目的基础。以下内容与仓库实际代码一一对应你可以结合源码对照学习。通用知识JavaScript 语言本身贡献指南首推You Dont Know JS系列作为 JavaScript 语言的深入学习资源——尤其是对this、闭包、原型与异步模型的深入理解在阅读 rbd 的 reducer、传感器与尺寸计算代码时非常有用。React这是 React 项目熟悉它是必须的rbd 是一个 React 组件库公开 API 只有四个核心概念DragDropContext /拖拽作用域的包裹组件、Droppable /可放入区域、Draggable /可拖拽项与resetServerContext()SSR 工具。视图层实现在 src/view 目录下例如连接器组件 connected-draggable.js 与 connected-droppable.js。项目 peerDependencies 要求react与react-dom版本为^16.8.5 || ^17.0.0 || ^18.0.0见 package.json开发环境使用 React 16.13.1。Redux状态管理核心这个项目的内部状态完全由 Redux 管理。如果你没用过 Redux贡献指南建议先熟悉其核心概念并推荐阅读redux官方文档、react-redux以及reselect的文档尤其是跨组件共享带 props 的 selector一节因为 selector 的性能直接关系到拖拽过程中高频的 state 派生计算。这一点可以在源码中得到充分印证状态存储的创建位于 src/state/create-store.js它用applyMiddleware串联了十余个中间件——style拖拽样式管理、lift发起拖拽、drop完成拖拽、autoScroll自动滚动、focus焦点管理、responders回调派发等所有动作类型与创建函数集中在 src/state/action-creators.js如BEFORE_INITIAL_CAPTURE、LIFT、INITIAL_PUBLISH、PUBLISH_WHILE_DRAGGING状态规约在 src/state/reducer.js。值得注意的细节是create-store.js 在开发环境下自动接入 Redux DevTools通过window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__并在注释中预留了四款调试中间件log、user-timing、action-timing、action-timing-average——例如 src/debug/middleware/log.js 支持verbose与light两种模式分别打印完整 state 前后快照或仅打印 action 类型。也就是说贡献者在调试拖拽状态机时可以直接借助 Redux DevTools 观察每一步 action。测试文化没有测试的变更不会被接受原文明确写道We test our application very thoroughly. Changes will not be accepted without tests我们对应用测试得非常彻底没有测试的变更将不会被接受。rbd 采用单元 集成 浏览器端到端的多层测试策略全部可以在仓库中验证jest 单元与集成测试配置在 jest.config.jssetupFiles引入 test/env-setup.jssetupFilesAfterEnv引入 test/test-setup.js并挂载了jest-watch-typeahead插件。数千个测试分布在 test/unit/state状态机auto-scroll、droppable、get-drag-impact、middleware、visibility 等与 test/unit/view视图层connected-draggable、connected-droppable、style-marshal、use-droppable-publisher 等。运行命令是yarn test即jest --config ./jest.config.jsCI 环境用yarn test:cijest test --maxWorkers2覆盖率统计用yarn test:coverage。cypress 浏览器端到端测试配置在 cypress.jsonbaseUrl指向本地 9002 端口的 Storybook用例在 cypress/integration 下包括reorder.spec.js、move-between-lists.spec.js、reorder-virtual.spec.js、focus.spec.js、content-security-policy.spec.js等。本地开发用yarn test:browsercypress openCI 用yarn test:browser:cicypress run。无障碍审计yarn test:accessibility用 Lighthouse 对 Storybook 页面做无障碍审计并解析结果到test-reports/lighthouse/。另外仓库的工程健康文档docs/support/engineering-health.md披露其代码覆盖率约为~94%并提醒覆盖率不等于健康度但是一个好的指标。这意味着你的 PR 如果引入新逻辑几乎必然需要配套新的 jest 用例甚至可能要补充 cypress 场景。性能这是库的 DNA红线级要求原文明确写道Performance is critical to this project. Changes that break core performance characteristics will not be accepted性能对这个项目至关重要破坏核心性能特性的变更将不会被接受。性能要求与架构决策强绑定rbd 之所以在拖拽过程中只更新该更新的组件是因为它把拖拽状态放进了 Redux并依靠高性能 selector 做派生计算让 React 的渲染面被压到最小。仓库为性能提供了多重保障机制package.json内置bundle-size:check与bundle-size:update脚本通过rollup-plugin-size-snapshot对产物体积做快照比对防止回归构建产物只有一份dist/react-beautiful-dnd.cjs.js与一份 ESM 产物且sideEffects: false声明利于 tree-shaking视图层大量使用 memoization 与上下文隔离测试目录中甚至有专门的 selector-isolation.spec.js 来验证 selector 隔离性。贡献指南推荐的性能学习路径包括 React 官方性能文档、React 性能工具以及社区关于React 慢/快的讨论——核心思想是在动手优化之前先学会测量。Flow全库强类型类型错误会导致构建失败整个代码库使用 Flow 做静态类型标注这是参与贡献不可回避的硬性要求原文明确写道Changes will not be merged without correct flow typing没有正确的 Flow 类型标注变更不会被合入。如果不确定某个类型用法就让 flow 在构建时失败然后在 PR 里讨论。仓库中的类型证据非常充分几乎每个源码文件第一行都有// flow注释src/state/action-creators.js、src/state/create-store.js 等项目还自带一整套 Flow 类型声明文件flow-typed 目录覆盖 redux、react-redux、jest、enzyme、styled-components 等依赖甚至为发布包生成了dist/react-beautiful-dnd.cjs.js.flow类型入口见 package.json 的build:flow脚本。yarn typecheck即flow check --max-warnings0——注意是零警告。同时docs/guides/types.md 说明了 rbd 为消费方提供的 TypeScript 与 Flow 类型支持。对 TypeScript 用户来说rbd 本身也自带类型定义这点可以在安装后直接验证。拖拽问题空间理解这个库为什么这样做贡献指南要求大型贡献者先深入理解拖拽这个问题的历史与现状两个主题值得特别关注。为什么 rbd 不用 HTML5 拖拽 API一个关键事实是这个库并不使用 HTML5 原生拖拽 API。贡献指南对此的解释是HTML5 拖拽无法提供 rbd 实现强大而美观的体验所需的控制粒度。从源码看rbd 的传感器体系src/view/use-sensor-marshal/sensors 下的use-mouse-sensor.js、use-keyboard-sensor.js、use-touch-sensor.js完全是自研的指针事件处理而不是依赖draggable/dropzone属性。贡献指南建议了解 HTML5 拖拽的 API、基础与已知缺陷浏览器行为不一致以便理解 rbd 的设计取舍。如果你想基于 rbd 之上构建更复杂的交互docs/guides/how-we-use-dom-events.md 详细记录了它如何使用 DOM 事件。前人的工作rbd 在拖拽库光谱中的位置贡献指南推荐研究三类既有方案react-dndrbd 从中汲取了大量灵感但定位不同——react-dnd 提供的是拖拽原语primitivesrbd 则是面向列表的更高层抽象react-sortable-hoc表面看与 rbd 相似作者专门写过对比文章说明差异jQuery sortable长期占据拖拽领域的经典方案。对照 README 的表述可以更精确地理解定位react-beautiful-dnd是为列表垂直、水平、跨列表移动、嵌套列表等而构建的更高层抽象在这个子集内提供强大、自然、美观的体验但不追求 react-dnd 那样的功能广度。换言之它是深度换广度的典型——这直接决定了哪些功能请求会被接受、哪些会被拒绝。合入红线速查表把整个 CONTRIBUTING.md 与仓库实际约束结合可归纳出以下硬性门槛红线依据功能请求必须先建 Issue 讨论禁止直接提 PRCONTRIBUTING.md Feature request 一节变更必须带测试CONTRIBUTING.md Testing 一节jest.config.js 与 cypress 配置破坏核心性能特性的变更不被接受CONTRIBUTING.md Performance 一节必须有正确的 Flow 类型标注CONTRIBUTING.md Flow 一节yarn typecheckflow check --max-warnings0功能需要完整的键盘无障碍故事CONTRIBUTING.md 功能请求第 3 步docs/about/accessibility.md文档链接必须有效test/unit/docs/no-broken-links.spec.js给你的行动清单小步快跑从文档 PR 或小 Bug 修复开始先熟悉yarn validateprettier eslint stylelint flow 全量校验的流程本地验证用yarn test跑 jest用yarn test:browser打开 cypress 在真实浏览器里拖一遍用yarn storybook9002 端口起示例页理解状态机借助 Redux DevTools 观察 action-creators.js 中各类 action 在 create-store.js 中间件链中的流动尊重定位提功能前先对照 README 的功能边界与设计原则确认它在列表拖拽这个子集之内。最后提醒一点该仓库目前在 README 中已标记为归档archived状态因此学习价值远大于实际提交价值——它的状态机设计、性能策略与测试分层依然是研究如何构建一个严谨的 React 开源库的极佳范本。【免费下载链接】react-beautiful-dndBeautiful and accessible drag and drop for lists with React项目地址: https://gitcode.com/gh_mirrors/re/react-beautiful-dnd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考