ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Dropzone 6 使用指南:用 TypeScript 把任意 HTML 元素变成拖拽上传区

Dropzone 6 使用指南:用 TypeScript 把任意 HTML 元素变成拖拽上传区 前端UI组件【免费下载链接】dropzoneDropzone is an easy to use dragndrop library. It supports image previews and shows nice progress bars.项目地址https://gitcode.com/gh_mirrors/dr/dropzone点击查看免费下载Dropzone 是一款把任意 HTML 元素变成拖拽上传区的 JavaScript 库用户把文件拖到元素上Dropzone 会自动生成文件预览、显示上传进度并通过 XHR 替你完成上传。本文以当前仓库packages/dropzone包npm 上发布为dropzone为准从安装、最小示例到全部配置项、事件系统、上传队列与分块上传逐层展开读完即可在你的项目中落地一个可配置、可主题化的文件上传组件。快速开始安装与最小示例Dropzone 通过 npm 生态安装支持 npm 与 pnpm 两种包管理器npm install dropzone # 或 pnpm add dropzone安装后以 ES Module 方式引入并实例化即可使用import { Dropzone } from dropzone; const dropzone new Dropzone(div#myId, { url: /file/post });构造函数接收两个参数第一个是 HTML 元素本身或 CSS 选择器字符串第二个是配置对象。上例把idmyId的div变成上传区文件将被 POST 到/file/post。若目标元素找不到或已被别的 Dropzone 实例占用构造时会直接抛出错误见 dropzone.ts 中对Invalid dropzone element.与Dropzone already attached.的检查。关于url有一处关键行为当配置里没有显式提供url时构造函数会回退读取元素自身的action属性两者都为空则抛错No URL provided.dropzone.ts。所以当元素是form且带有action时甚至可以不传url。内置 TypeScript 类型无需安装 types/dropzoneDropzone 6 本身用 TypeScript 编写package.json 中main/module/types均指向src/dropzone.ts类型定义随包一起发布。你不需要再安装types/dropzone——那个包停更在5.7.9描述的是 v5 API与 v6 冲突且不准确如果之前装过请移除。直接按类型导入即可import { Dropzone } from dropzone; import type { DropzoneFile, DropzoneOptions } from dropzone;常用的导出类型包括定义见 types.d.ts 与 dropzone.tsDropzoneOptions用户传入的配置是默认选项的Partial版本ResolvedDropzoneOptions合并默认值后的完整配置所有键必然存在DropzoneFile浏览器File的扩展额外携带status、upload含uuid、progress、bytesSent等上传记账信息、previewElement、width/height等字段DropzoneAcceptCallback、DropzoneTransformCallback、DropzoneThumbnailCallback分别对应accept、transformFile、thumbnail回调的参数签名。类型层面还有一个值得注意的设计DropzoneOptions刻意不设索引签名这意味着像maxFileSize这种把maxFilesize拼错的写法会直接被 TypeScript 拒绝而不是在运行时静默失效见 options.ts 的注释说明。核心配置选项以 src/options.ts 为准全部可用选项的权威清单在 src/options.ts每一项默认值都带详细注释。下面按功能分组整理最常用的一批。上传目标与请求行为选项默认值说明urlnull上传地址可传字符串或(files, dataBlocks) string函数不传时回退读取元素action属性methodpost请求方法可改为put也支持函数动态返回withCredentialsfalse是否在 XHR 上设置withCredentialstimeoutnullXHR 超时毫秒null或0表示不设超时headersnull附加请求头如{ My-Awesome-Header: header value }defaultHeaderstrue是否发送默认请求头Accept: application/json、Cache-Control: no-cache、X-Requested-With: XMLHttpRequestparamNamefile文件字段名uploadMultiple为true时会自动追加[]params默认实现附加表单参数可传对象或(files, xhr, chunk) map函数分块上传时默认注入dzuuid、dzchunkindex、dztotalchunkcount等字段binaryBodyfalse以二进制 Blob 作为请求体发送文件此时params被忽略且不能与uploadMultiple同用文件筛选与大小限制选项默认值说明maxFilesize256允许上传的最大文件体积MiBmaxFilesnull最多可处理文件数超出后触发maxfilesexceeded事件元素被加上dz-max-files-reached类acceptedFilesnull逗号分隔的 MIME 类型或扩展名白名单如image/*,application/pdf,.psd同时会写进隐藏input的accept属性accept默认接受自定义接受/拒绝回调(file, done) done()无参调用表示接受传字符串则拒绝并展示错误信息注意体积超限或类型不符的文件不会走到该回调ignoreHiddenFilestrue是否忽略目录中的隐藏文件队列与并发选项默认值说明parallelUploads2同时处理的文件上传数uploadMultiplefalse是否多个文件合并为一次请求发送为true时隐藏 input 带multiple并触发processingmultiple等复数事件autoProcessQueuetrue为false时文件只入队不自动上传需手动调用myDropzone.processQueue()autoQueuetrue为false时新文件不入队需手动调用enqueueFile(file)分块上传大文件选项默认值说明chunkingfalse是否分块上传不能与uploadMultiple同时开启构造时会校验并抛错forceChunkingfalse为true时即使文件小于chunkSize也强制分块便于统一接收方协议chunkSize2 * 1024 * 1024每块字节数默认 2 MiBparallelChunkUploadsfalse单文件各分块是否并行上传上限为parallelUploadsInfinity则全部同时开始retryChunksfalse分块失败是否重试retryChunksLimit3重试次数上限chunksUploaded默认完成所有分块上传完后的收尾回调(file, done)业务方完成合并等操作后调用done()图片缩略图与上传前重采样选项默认值说明createImageThumbnailstrue是否为图片生成缩略图maxThumbnailFilesize10超过该体积MB不生成缩略图thumbnailWidth/thumbnailHeight120/120缩略图尺寸null时按图片原始宽高比计算两者都null则不做缩放thumbnailMethodcrop缩略图缩放方式contain或cropresizeWidth/resizeHeightnull上传前把图片重采样到指定尺寸只给一个时保持原始宽高比resizeMimeTypenull重采样后图片的 MIME 类型如强制image/jpegnull保留原类型resizeQuality0.8重采样 JPEG 质量resizeMethodcontain上传重采样的缩放方式resizeTransparencyFillnull透明区域在转成不支持透明度的格式时填充的颜色如#fffnull则可能得到黑色该选项只影响上传前的重采样缩略图始终是 PNGtransformFile是重采样的总入口默认实现仅在配置了resizeWidth/resizeHeight且文件为图片时调用resizeImage否则原样放行options.ts。一旦你重写transformFile上述 resize 系列选项就不再生效。交互与文案选项默认值说明clickabletrue元素是否可点击触发选文件可传true、元素、选择器或元素数组用于多区域触发previewsContainernull预览容器可传元素或选择器null时用 Dropzone 元素本身元素需带dropzone-previews类disablePreviewsfalse为true时不显示预览hiddenInputContainerbody隐藏input typefile挂载的位置框架动态切换页面内容时可能需要调整addRemoveLinksfalse是否在每个文件预览上添加删除/取消链接文案由dictCancelUpload、dictCancelUploadConfirmation、dictRemoveFile控制capturenull移动端跳过分组选择直接调用摄像头/麦克风取值camera、microphone、camcorderrenameFilenull上传前重命名文件的函数实际上传名可从file.upload.filename读取forceFallbackfalse强制启用无 JS 回退表单便于先测试服务端实现filesizeBase1000显示文件体积时使用的进制基数改成1024则显示 KiB/MiBdict*系列选项dictDefaultMessage、dictFileTooBig、dictInvalidFileType、dictResponseError等负责全部界面文案其中{{filesize}}、{{maxFilesize}}、{{statusCode}}、{{maxFiles}}会被替换为实际值dictFileSizeUnits可自定义tb/gb/mb/kb/b的单位显示适合做国际化。事件系统on / off / emit 与全部事件名Dropzone 继承自自带的轻量 Emitter参考 component 的 emitter 实现、去掉了框架依赖。事件注册用dropzone.on(addedfile, (file) ...)且监听器的参数类型会根据事件名自动推断。Emitter 还做了两件额外的事emit时会遍历回调快照避免监听器自我移除导致后续监听器被跳过并同时派发一个dropzone:事件名的 DOM 自定义事件到元素上冒泡、可取消方便在元素层面统一监听。完整事件列表定义在 dropzone.ts核心事件如下事件参数触发时机dragenter/dragover/dragleave/dropDOM 事件拖拽进入、悬停、离开、放下默认行为给元素切换dz-drag-hover类addedfile/addedfilesfile/files文件加入队列含点击选择与拖放removedfilefile文件被移除thumbnailfile, dataUrl缩略图生成完成dataUrl为 Data URLprocessing/processingmultiplefile文件开始处理进入上传管线uploadprogressfile, progress, bytesSent单个文件上传进度0-100totaluploadprogresstotalProgress, totalBytes, totalBytesSent整体上传进度sendingfile, xhr, formData请求发送前可在此给 xhr 加 CSRF token 或补充 formDatasuccess/successmultiplefile上传成功errorfile, message出错message可能是服务器返回的错误对象canceledfile上传被取消默认实现会转发error并显示dictUploadCanceledcomplete/completemultiplefile上传结束无论成败所有文件完成后延迟触发queuecompletemaxfilesexceeded/maxfilesreachedfile超出maxFiles限制emptyfolder文件夹路径拖入的文件夹实际为空init选项是一个在 Dropzone 初始化末尾被调用的钩子dropzone.ts官方推荐在里面注册监听器例如const dropzone new Dropzone(div#myId, { url: /file/post, init() { this.on(addedfile, (file) console.log(Added:, file.name)); this.on(error, (file, message) console.error(message)); }, });上传流程与队列enqueueFile 到 processQueue 的调用链理解 Dropzone 的并发控制关键是看队列处理链路。文件进来后走addFile → enqueueFileenqueueFile在autoQueue为true时入队并setTimeout(() this.processQueue(), 0)延迟触发队列处理dropzone.ts。processQueue()会先按状态过滤出QUEUED文件扣除正在处理的数量后取parallelUploads上限的剩余配额调用processFilesdropzone.ts。processFile是processFiles的单文件封装。队列消费掉一个文件后会再次调用processQueue()补充下一个dropzone.ts从而保证任意时刻在途上传数不超过parallelUploads。这就是autoProcessQueue: false时手动processQueue()依然可用的原因它只是把入队即处理改成你说了算。文件状态由Dropzone的静态常量表示QUEUED、UPLOADING、ADDED等配套的查询方法包括getAcceptedFiles()、getRejectedFiles()、getQueuedFiles()、getUploadingFiles()、getActiveFiles()便于在自定义 UI 或测试中按状态捞取文件集合。分块上传走的是另一条路径uploadFiles里若chunking生效文件被切成chunkSize大小的块并各自发起请求每块带独立的 XHR块信息记录在file.upload.chunks上见 dropzone.ts。全部块完成后调用chunksUploaded(file, done)收尾。6.3.2 的 CHANGELOGCHANGELOG.md特别记录过取消上传必须中止所有在途分块的请求而不是只中止最后一个这正是块级xhr独立管理的价值。预览与缩略图从 previewTemplate 到自定义主题每个文件的预览由previewTemplate选项控制默认模板在 preview-template.html结构如下div classdz-preview dz-file-preview div classdz-imageimg>pnpm test # 库的单元测试vitest pnpm test:e2e # 库的浏览器端到端测试playwright单元测试覆盖了 上传错误处理、拖放、粘贴、Amazon S3、实例隔离 与 公开 API 等场景E2E 测试提供了可直接在浏览器里手测的 示例页面含 零配置、上传错误、AWS S3 分片上传其中 AWS S3 Multipart 集成是仓库 README.md 明确列出的主特性之一。服务端配合的实现要点可参考文档区的 服务端实现指南。许可证Dropzone 以 MIT 协议发布许可证全文见仓库根目录 LICENSE。参考资源全部配置选项\src\options.ts核心实现dropzone.ts版本变更记录CHANGELOG.md包元信息与构建脚本package.json完整官方文档apps/docs/docs/index.md赞分享前端UI组件【免费下载链接】dropzoneDropzone is an easy to use dragndrop library. It supports image previews and shows nice progress bars.项目地址https://gitcode.com/gh_mirrors/dr/dropzone点击查看免费下载相关推荐beautiful-react-hooks 的 useDropZone 深度指南:把任意 DOM 元素变成可接收数据的拖放区beautiful react hooks 的 useDropZone 深度指南:把任意 DOM 元素变成可接收数据的拖放区 useDropZone 是 bea前端开发工具Gatsby 集成 Snipcart 购物车完全指南用 HTML 属性把任意元素变成购买按钮Gatsby 集成 Snipcart 购物车完全指南用 HTML 属性把任意元素变成购买按钮 导读 本文是一份以 docs/docs/adding a s前端静态站点Web框架React-Dropzone基础使用教程实现文件拖拽上传功能React Dropzone基础使用教程实现文件拖拽上传功能 什么是React Dropzone React Dropzone是一个流行的React组件库前端UI组件上一篇Ant Design Vue 2.0 升级迁移实战指南从 1.x 到 2.x 的破坏性变更与 Form 重构全解析下一篇Slang 泛型Generics完全指南类型参数、约束系统与参数包编程创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表