前端UI组件后端【免费下载链接】uppyThe next open source file uploader for web browsers :dog:项目地址https://gitcode.com/gh_mirrors/up/uppy点击查看免费下载导读uppy/drag-drop是 Uppy 生态中专用于提供拖拽放置区域Droppable Zone的 UI 插件用户把文件拖进该区域即可加入上传队列也可以点击区域打开系统文件选择对话框。本文以该插件在 当前仓库 中的官方文档与源码实现为骨架覆盖其安装方式、最小示例、全部可配置选项并深入DragDrop.tsx与 Uppy Core 工具函数剖析拖拽事件处理、文件夹递归解析、浏览器能力检测与上传限制联动的底层原理帮助你既会用、也能看懂它为什么这样工作。插件定位Uppy 的 Droppable Zoneuppy/drag-drop在 Uppy 插件体系中的类型是acquirer获取者即在用户上传之前负责收集文件的插件。它在页面上渲染一个可拖拽的放置区域Droppable zone UI for Uppy并同时具备两种取文件方式拖拽投放把本地文件或文件夹拖入区域点击浏览点击区域弹出系统文件选择框。与uppy/dashboard这类完整界面不同DragDrop只渲染一个独立的放置区非常适合嵌入已有页面布局、与自定义上传按钮搭配或作为简易上传表单的核心交互组件。其组件实现位于 DragDrop.tsx最终渲染为一个button元素内含隐藏的input typefile无需任何额外 DOM 容器。安装通过 npm 安装插件本体及其运行时依赖uppy/corepeer 依赖npm install uppy/drag-drop按 package.json 的exports声明安装后可引入的入口包括uppy/drag-drop插件主入口lib/index.jsuppy/drag-drop/css/style.css、uppy/drag-drop/css/style.min.css编译后的样式uppy/drag-drop/css/style.scss可直接参与 Sass 构建的源码样式。若使用 Transloadit Smart CDN 提供的预构建 bundleUppy会挂载到全局window.Uppy对象上此时无需打包器也可直接使用本插件。基础用法三行代码接入官方 README 给出的最小示例packages/uppy/drag-drop/README.mdimport Uppy from uppy/core import DragDrop from uppy/drag-drop const uppy new Uppy() uppy.use(DragDrop, { target: #upload, })执行流程是new Uppy()创建核心实例uppy.use(DragDrop, { target: #upload })注册插件并将放置区挂载到页面中#upload元素内install()方法中通过this.mount(target, this)完成用户拖入或点选文件后插件把文件以 descriptor 形式交给uppy.addFiles()进入 Uppy 的全局状态管理。若页面已有拖拽 HTML5 能力之外的样式需求还需引入样式例如import uppy/drag-drop/css/style.min.css样式文件中定义的.uppy-DragDrop-container等类名详见 style.scss。可配置选项全解析插件公开的选项类型DragDropOptions定义在 DragDrop.tsx与默认值defaultOptions见 DragDrop.tsx合并后生效。汇总如下选项类型默认值说明targetstring \| HTMLElement—插件挂载的 DOM 目标继承自UIPluginOptionsREADME 示例中传#uploadinputNamestringfiles[]隐藏input typefile的name属性便于配合传统表单提交widthstring \| number100%放置区域宽度直接作用于容器的style.widthheightstring \| number100%放置区域高度直接作用于容器的style.heightnotestring空显示在区域内的辅助提示文字如单个文件不超过 5MBonDragOver(event: DragEvent) void—文件拖入区域时回调onDragLeave(event: DragEvent) void—拖拽离开区域时回调onDrop(event: DragEvent) void—文件投放完成后回调localeLocaleStrings见下节区域文案的本地化字符串从源码DragDrop.tsx可以看到三个on*回调分别在handleDragOver、handleDragLeave、handleDrop内部被调用可用于实现拖拽高亮、统计投放次数等自定义交互逻辑。与 Uppy 限制规则的联动值得注意的一点是uppy/drag-drop不会重复实现文件校验而是直接读取 Uppy 核心实例上的restrictions配置并把它反映到隐藏的 file input 上DragDrop.tsxmultiple属性由restrictions.maxNumberOfFiles ! 1决定——若限制只能传一个文件则禁止多选accept属性由restrictions.allowedFileTypes?.join(, )生成——在系统文件对话框中预先过滤文件类型。因此你只需要在new Uppy({ restrictions: { ... } })中统一配置限制拖拽区便会自动遵循无需重复传参。源码原理四步事件处理链整个插件的拖拽逻辑集中在 DragDrop.tsx 的三个事件处理器中1.handleDragOver—— 准入检查与视觉反馈读取event.dataTransfer.types检查其中是否包含Files类型若拖入的是链接、文本等非文件内容则拒绝检查this.uppy.getState().allowNewUpload当 Uppy 正在上传且不允许新任务时同样拒绝拒绝时设置dropEffect none并中止允许时设置dropEffect copy并把isDraggingOver状态置为true触发.uppy-DragDrop--isDraggingOver样式背景变灰、边框变蓝。2.handleDragLeave—— 状态复位将isDraggingOver重置为false恢复默认外观。3.handleDrop—— 取文件并入库调用 Uppy Core 工具函数getDroppedFiles(event.dataTransfer, { logDropError })异步取回所有文件非空时记录日志并调用this.addFiles(files)。4.addFiles—— 构造 descriptor把每个File映射为{ source, name, type, data, meta }结构其中meta.relativePath取自file.relativePath用于保留文件夹层级再统一交给uppy.addFiles()进入 Uppy 状态树若被Restricter拒绝错误会通过uppy.log记录而不会中断。点击路径render()把整个区域渲染为buttononClick触发隐藏 input 的click()onInputChange处理change事件后会把input.value清空DragDrop.tsx这样即使用户重复选择同一个文件也能再次触发change。文件夹拖拽getDroppedFiles的双策略放置区支持直接拖入文件夹。其能力来自 Uppy Core 的 getDroppedFiles/index.ts它优先尝试webkitGetAsEntryApi利用webkitGetAsEntry()递归遍历目录把文件夹拍平为文件数组并为每个文件补上relativePath若浏览器不支持或解析出错则回退到fallbackApi仅返回第一层文件。因此在 Chrome、Mozilla、Safari 等支持webkitGetAsEntry的浏览器中拖入文件夹可保留相对路径结构如docs/Old Prague/airbnb.pdf在不支持的浏览器中仅能取到拖拽项的顶层文件。getDroppedFiles返回的是 Promise即便个别目录解析失败如 Windows 上文件夹名过长也会通过logDropError记录后继续解析其余文件保证整体投放流程不中断。浏览器能力检测插件在构造时即执行isDragDropSupported()并缓存结果DragDrop.tsx用于给容器追加uppy-DragDrop--isDragDropSupported类决定是否显示虚线边框。检测逻辑见 isDragDropSupported.ts在服务端渲染无window/document.body时直接返回false依次检查draggable、ondragstart、ondrop属性以及FormData、FileReader是否存在移动端浏览器通常不满足这些条件因而不会显示虚线可拖放样式但点击浏览文件的能力依然可用。国际化文案默认文案定义在 locale.ts仅两条字符串key默认文案用途dropHereOrDrop here or %{browse}区域主文案%{browse}会被替换为可点击的browse链接browsebrowse打开系统文件对话框的链接文本通过locale选项可整体替换%{browse}占位符会被源码中以.uppy-DragDrop-browse高亮的span渲染实现全中文界面只需uppy.use(DragDrop, { target: #upload, locale: { strings: { dropHereOr: 将文件拖到此处或%{browse}, browse: 浏览, }, }, })样式定制放置区的基础视觉由 style.scss 提供关键类名及作用.uppy-DragDrop-containerflex 居中布局、圆角、白底与cursor: pointer聚焦时显示蓝色外发光.uppy-DragDrop-inner内边距与居中文案容器.uppy-DragDrop-arrow内置的上传箭头 SVG 图标renderArrowSvg()渲染aria-hidden.uppy-DragDrop--isDragDropSupported灰色虚线边框标识可拖放.uppy-DragDrop--isDraggingOver拖拽悬停态背景变浅灰、边框变蓝.uppy-DragDrop-notenote选项提示文字的颜色与字号。需要深度定制时可引入uppy/drag-drop/css/style.scss参与自己的 Sass 构建覆盖上述类名即可。小结uppy/drag-drop是一个小而专的 Uppy 插件它只负责提供拖拽/点选入口把文件统一交还给 Uppy 核心从而自动获得核心的全局状态管理、restrictions校验与后续上传链路。理解它的选项、事件回调与getDroppedFiles/isDragDropSupported两条底层工具链可以让你在自定义上传界面时精准掌控拖拽体验并为移动端、限制规则、文件夹结构保留等边界场景做针对性处理。更多上下文可继续阅读插件入口 index.ts、核心实现 DragDrop.tsx 与官方文档页。赞分享前端UI组件后端【免费下载链接】uppyThe next open source file uploader for web browsers :dog:项目地址https://gitcode.com/gh_mirrors/up/uppy点击查看免费下载相关推荐Draggable DragSensor 指南用原生 HTML5 Drag Drop API 驱动拖拽Draggable DragSensor 指南用原生 HTML5 Drag Drop API 驱动拖拽 导读 DragSensor 是 Shopify D前端UI组件深入解析fpPS4项目架构基于Free Pascal的PS4兼容层开发指南深入解析fpPS4项目架构基于Free Pascal的PS4兼容层开发指南 fpPS4是一个基于Free Pascal语言开发的PS4兼容层模拟器项目旨上一篇Qwen3.5-4B-OptiQ-4bit代码生成实战编程助手的最佳选择下一篇华为HCOMM通信同步通知接口创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
