Pragmatic drag and drop 文档包版本演进深度解读：从 0.0.1 到 2.1.0 的关键技术里程碑-北京尧图网络

Pragmatic drag and drop 文档包版本演进深度解读从 0.0.1 到 2.1.0 的关键技术里程碑【免费下载链接】pragmatic-drag-and-dropFast drag and drop for any experience on any tech stack项目地址: https://gitcode.com/GitHub_Trending/pr/pragmatic-drag-and-dropatlaskit/pragmatic-drag-and-drop-docs即仓库中packages/documentation包的变更日志CHANGELOG.md完整记录了 Pragmatic drag and drop 文档站点从 0.0.1 到 2.1.0 的演进过程。这份日志不仅是发布历史更是理解整个项目技术决策的窗口从包名统一、1.0 正式发布到著名的 honey pot fix蜜罐修复引入再到 TypeScript 5 成为最低版本要求。读完本文你将掌握 Pragmatic drag and drop 各版本的关键变更及其背后的源码实现原理并了解文档包当前的工程结构与升级约束。一、版本演进总览packages/documentation/package.json显示该包当前版本为2.1.0包名为atlaskit/pragmatic-drag-and-drop-docs定位是将 Pragmatic drag and drop 的文档集中在一处供其他工具共享示例使用不面向消费者直接使用。其唯一运行时脚本是codegentsx ./scripts/codegen.ts。从 CHANGELOG.md 可以梳理出几个关键的版本里程碑版本类型核心内容0.0.1Patch初始版本TypeScript 4.2.4 → 4.3.50.2.0Minor默认入口点由undefined改为{}明确建议使用独立入口点以获得最小包体积0.4.0Minor包名统一为 Pragmatic drag and dropatlaskit/drag-and-drop*→atlaskit/pragmatic-drag-and-drop*1.0.0Major所有 Pragmatic drag and drop 包首次 major 发布1.1.0Minor引入 honey pot fix蜜罐修复解决浏览器拖拽指针状态 bug1.0.8Patch补齐author与license元数据2.0.0Major放弃旧版 TypeScript 4 类型支持TypeScript 5 成为最低要求其中honey pot fix 是日志中篇幅最长、技术含量最高的条目也是本文的讲解重点。二、包名统一0.4.0 背后的生态设计在 0.4.0 版本中所有包统一更名为 Pragmatic drag and drop变更日志给出了完整的改名映射- atlaskit/drag-and-drop atlaskit/pragmatic-drag-and-drop - atlaskit/drag-and-drop-autoscroll atlaskit/pragmatic-drag-and-drop-autoscroll - atlaskit/drag-and-drop-hitbox atlaskit/pragmatic-drag-and-drop-hitbox - atlaskit/drag-and-drop-indicator atlaskit/pragmatic-drag-and-drop-react-indicator # 注indicator 包因面向 React 使用包名中额外加入了 react - atlaskit/drag-and-drop-live-region atlaskit/pragmatic-drag-and-drop-live-region - atlaskit/drag-and-drop-react-beautiful-dnd-migration atlaskit/pragmatic-drag-and-drop-react-beautiful-dnd-migration - atlaskit/drag-and-drop-docs atlaskit/pragmatic-drag-and-drop-docs日志特别说明新包名从旧包版本号继续计数而不是从 0 重新开始目的是便于回溯 changelog、看清包的发展脉络。这与当前仓库的多包布局一致——packages下可以看到 auto-scroll、core、hitbox、react-drop-indicator、live-region、react-beautiful-dnd-migration 等各自独立的变更日志构成了一个可独立版本化、可组合消费的包族。三、1.0 正式发布首个 major 里程碑1.0.0 是 Pragmatic drag and drop 全系包的第一个major版本。日志明确指向一份 1.0 升级指南用于说明所有破坏性变更细节以及如何自动升级。在本文档仓库中这份指南的对应内容保存在 upgrade-guide-0.x-to-1.0.mdx位于05-core-package/12-upgrade-guides目录下。与 1.0 配套的还有几项基础性工程改动0.2.0默认入口点从undefined改为{}并给出重要提示——从默认入口点导入不受支持请使用独立入口点以获得最小 KB 数。这正是 Pragmatic drag and drop 的核心设计理念按需引入、以最小化 bundle 体积为目标。packages/core/src/entry-point/下的细分目录element、external、text-selection、private 等就是这一设计的具体体现。1.0.8为所有包补齐package.json中缺失的author: Atlassian Pty Ltd与license: Apache-2.0元数据各包此前已按 Apache-2.0 授权只是部分package.json缺少显式声明。四、honey pot fix蜜罐修复1.1.0 的核心技术内容1.1.0 引入了 the honey pot fix这是日志中最值得深挖的技术条目也是 Pragmatic drag and drop 解决浏览器原生拖拽缺陷的代表性方案。4.1 要解决的浏览器 bugChrome/Chromium 存在一个长期 bug日志中指向 Chromium issue 41129937拖拽开始后浏览器会错误地认为用户的指针仍持续按压在拖拽起始位置。这会导致拖拽过程中元素错误地收到MouseEvent如mouseenter、mouseleave违反 HTML 拖拽规范中拖拽期间必须抑制设备输入事件的要求元素在拖拽期间被错误地应用:hover、:active样式——此前消费者需要自行在拖拽期间禁用这些样式规则拖拽结束后出现明显的样式重算延迟影响 post-drop 性能。4.2 修复策略在错误指针位置放一个 2×2 的蜜罐源码 make-honey-pot-fix.ts 完整实现了这一修复核心思路只有两步在浏览器认为指针仍被按压的位置创建一个元素吸收错误的指针事件在该元素不再需要时将其移除。实现细节值得逐一拆解蜜罐元素一个2×2像素的div通过honeyPotDataAttribute data-pdnd-honey-pot见 honey-pot-data-attribute.ts标记便于后续识别与排除。精确吸附指针位置由于clientX/clientY可能为亚像素值如2.332而浏览器的命中测试通常基于最近像素源码先对坐标Math.floor()再以2px尺寸的矩形覆盖该位置getHoneyPotRectFor。同时对坐标做了越界钳制preventGoingBackwardsOffScreen/preventGoingForwardsOffScreen防止蜜罐改变窗口尺寸。两层置顶策略优先使用 Popover APIpopovermanualshowPopover()将蜜罐放入浏览器 top layer确保视觉上盖过一切z-index与堆叠上下文supportsPopover()supports-popover.ts检测HTMLElement.prototype.showPopover是否存在并用once缓存结果在不支持 Popover API 的浏览器上回退为position: fixedzIndex: 2147483647即maxZIndex见 max-z-index.ts。使用 Popover 时还会应用 popover-reset-styles.ts 中导出的popoverResetUserAgentStyles重置浏览器的 UA 样式inset: unset、border: none、overflow: visible等并特意将width/height设为auto以规避 Safari 中fit-content导致 flex 内overflow: auto子项塌缩为 0 的 bug。吸收指针事件pointerEvents: auto、backgroundColor: transparent调试时可临时改为红色显式重置padding/margin/boxSizing避免继承任何样式。Firefox 特判Firefox 在拖拽开始后仍可能派发pointermove同样是规范违例源码在捕获阶段监听window的pointermove用最后一次移动位置持续更新蜜罐矩形从而揭示被按压位置的实际所在。挂载时机在onDragStart事件后挂载蜜罐避免影响原生拖拽预览的创建若没有最新的pointermove如 iOS则回退使用拖拽起始坐标。4.3 收尾与清理机制蜜罐的生命周期管理同样细致finish函数与onPostEvent在onDrop时调用finish若用户当前指针恰好位于蜜罐矩形内直接移除蜜罐否则绑定一组捕获阶段的清理监听pointerdown、pointermove、focusin、focusout、dragstart、dragenter、dragover在下一次用户交互或拖拽进入窗口时清除蜜罐。注释特别说明不监听wheel因为单独的滚轮事件并不能解除该 bug。每次拖拽交互开始时重置latestPointerMove避免沿用上一次交互的陈旧坐标onDrop结束后同样重置。4.4 蜜罐元素的排除与独立工具蜜罐元素会被document.elementsFromPoint返回因此核心包提供了跳过蜜罐的命中测试工具get-element-from-point-without-honey-pot.ts 取命中列表的前两个元素若顶层是蜜罐由 is-honey-pot-element.ts 依据data-pdnd-honey-pot属性判定则返回第二层元素。该工具通过 entry-point/private/get-element-from-point-without-honey-pot.ts 以私有入口点导出标注为 deprecated推荐使用atlaskit/pragmatic-drag-and-drop/get-element-from-point-without-honey-pot直接引入。在 adapter/honey-pot-fix.ts 中makeHoneyPotFix()被实例化为单例honeyPotFix通过bindEvents与getOnPostDispatch两个钩子接入拖拽生命周期——核心包的 element 与 text-selection adapter 均使用它而 external adapter面向原生拖拽不需要蜜罐。设计上特意将蜜罐相关代码独立成目录让不需要它的 adapter 为此付出的代价尽可能小。五、TypeScript 版本策略从 4.x 到 5 的旅程CHANGELOG 记录了一条清晰的 TypeScript 升级路径可视为项目类型策略的时间线0.0.1TypeScript 4.2.4 → 4.3.50.1.24.3.5 → 4.5.50.5.14.5.5 → 4.9.5并在 0.5.2 中确保为 TS 4.5–4.8 发布 legacy 类型1.0.24.9.5 → 5.4.22.0.0Dropped support for legacy TypeScript 4 typesTypeScript 5 成为新的最低要求。2.0.0 的破坏性变更细节如下从 dist 中移除typesVersions属性和dist/types-ts4.5目录类型现在仅通过types: dist/types/index.d.ts提供移除的typesVersions配置形如- typesVersions: { - 4.5 4.9: { - *: [ - dist/types-ts4.5/*, - dist/types-ts4.5/index.d.ts - ] - } - },这意味着如果你的项目仍在使用 TypeScript 4.x将无法从该版本及之后版本获得类型支持升级到 TypeScript 5 是使用新版文档包与整个 Pragmatic drag and drop 包族的先决条件。六、工程化与质量保障实践日志的多个 Patch 版本揭示了文档包背后的工程化投入值得作为项目实践参考自动化测试保障1.4.5 引入视觉回归测试确保示例不会在我们不知情的情况下发生变化对应仓库中大量.vr.ap.tsx示例文件如packages/documentation/examples/board.vr.ap.tsx1.4.8 扩展了 Platform 的自动无障碍a11yPlaywright 测试覆盖1.1.2 起所有 react 单元测试在 CI 上同时针对react16和react18运行验证跨 React 版本兼容性。运行时与样式层优化0.1.3 起构建经过 tokens babel 插件处理移除运行时的tokens()调用以提升性能1.3.1 与 1.3.2 逐步迁移到 Compiled CSS-in-JS 样式方案并修复了 CJS/ESM 产物中关键帧动画的潜在问题多个版本1.4.10 ~ 1.4.14对 border radius、border、字体 token、图标导入等做了内部调整均承诺无视觉变化或极细微变化。包发布规范化1.4.4 补齐缺失的 npmignore 文件从发布包中剔除不必要的文件。示例生态维护1.4.15 将示例中的 issue 措辞改为 work-item1.0.11 修复了 CodeSandbox 中无法运行的示例1.0.5 是文档的公开发布版本。七、文档包源码结构速览packages/documentation的源码结构与其文档中枢定位完全吻合入口 src/index.ts 仅为模块解析存在constellation/按主题组织的文档内容——教程01-tutorial、核心包指南05-core-package含 adapters、drop-targets、monitors、utilities、events、reconciliation、UI frameworks、recipes、testing、upgrade-guides 等子目录、可选包06-optional-packages、Web 平台设计约束07-web-platform-design-constraints、设计指南08-design-guidelines与无障碍指南09-accessibility-guidelinesexamples/可直接运行的示例覆盖棋盘board、树形tree、表格table、虚拟列表virtual-list、多选拖拽board-with-multi-drag、溢出滚动board-with-overflow-scroll等场景其中data/people、data/quotes、data/presidents.tsx等提供了示例数据scripts/codegen.ts与package.json中的codegen脚本对应的代码生成器。八、对使用者的实践建议综合 CHANGELOG.md 与 package.json可提炼出三条对使用者的明确建议版本前提使用atlaskit/pragmatic-drag-and-drop-docs2.x 需要 TypeScript 52.0.0 起不再提供 TS 4 类型历史 TS 4.5–4.8 用户应停留在 1.x 并留意dist/types-ts4.5类型的发布历史。不要直接依赖文档包不面向消费者直接使用它服务于共享示例与文档工具链实际拖拽能力应通过atlaskit/pragmatic-drag-and-drop核心包及其可选包hitbox、auto-scroll、react-drop-indicator、live-region 等按需引入并优先使用独立入口点以获得最小 bundle。升级路径从 0.x 升级到 1.0 的破坏性变更细节可查阅仓库内 upgrade-guide-0.x-to-1.0.mdx若你遇到拖拽期间:hover/mouseenter误触发的问题honey pot fix 自 1.1.0 起已在核心包内默认启用无需再手动处理。总而言之这份 CHANGELOG 本身就是一篇浓缩的项目技术史它记录了 Pragmatic drag and drop 从内部工具走向公开生态的每一步而 honey pot fix 的源码实现则展示了该项目直面浏览器平台缺陷、以极小成本换取规范行为的工程哲学。【免费下载链接】pragmatic-drag-and-dropFast drag and drop for any experience on any tech stack项目地址: https://gitcode.com/GitHub_Trending/pr/pragmatic-drag-and-drop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Pragmatic drag and drop 文档包版本演进深度解读：从 0.0.1 到 2.1.0 的关键技术里程碑

相关推荐

es-toolkit 使用指南：更小、更快、类型完备的现代 JavaScript 工具库

Base UI Field 组件完全指南：类型定义、校验机制与源码级 API 解析

STM32G070驱动CS5530高精度ADC：SPI时序、校准与噪声验证

更多资讯

华为OD面试全流程经验：机试、技术面、薪资与转正避坑指南

STM32L151裸机实现NB-IoT直连阿里云MQTT

数据获取与清洗：构建高可靠金融数据管道的实战指南

compliance-checker 实战：netCDF 数据文件合规校验与发布流程接入

VideoPose3D环境搭建全攻略：3D人体姿态估计实战指南

如何用 taosgen 编排并运行 TDengine 写入基准测试作业

今日更新

基于高阶循环谱的MPSK载波频率估计与MATLAB实现

MiniPdf方：.NET开源Office转PDF的高效解决方案

Solon AI v3.10：Java全栈智能体开发框架解析

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？