拖文件进来会发生什么：TinyRobot DragOverlay 与 v-dropzone 协同指南

拖文件进来会发生什么：TinyRobot DragOverlay 与 v-dropzone 协同指南

你大概写过「把文件拖进聊天页就上传」——给容器绑drop，再自己画一层半透明提示。结果常常是：浮层闪一下就没了，或者子元素一多，dragleave提前把状态清掉。TinyRobot 把这件事拆成两件套：v-dropzone只管拖拽事件与文件校验，DragOverlay（<tr-drag-overlay>）只根据is-dragging做展示。

本文跟着同一张photo.png拖进.chat-area走完全程：怎么接到一个div、松手如何被接受或拒绝、浮层盖在哪、怎样换皮。正文停在拿到File[]，不讲对象存储上传。

先分清职责：指令听事件，浮层只管亮

把「事件」和「视觉」绑在同一个组件里，嵌套 DOM 上最容易翻车：子节点进出也会触发dragleave，浮层自己还可能挡住后续拖拽。官方文档把能力拆开——v-dropzone负责监听与处理 DOM 拖拽事件；<tr-drag-overlay>是纯展示组件，靠is-dragging显隐。

你要做的，是用状态把两边串起来：指令经onDraggingChange报告「正在拖 / 拖完了」，你把布尔值写给浮层的is-dragging，并把回调里的目标元素交给drag-target做定位。漏掉后半段会踩坑——源码里浮层用@vueuse/core的useElementBounding按dragTarget算fixed坐标；没有drag-target时样式直接display: none，即使is-dragging为true也看不见浮层。

记一句话就够：指令产出状态，浮层消费状态；中间那根线是你写的ref。

接到一个聊天容器：最小可跑通示例

前置条件：Vue 3 项目已安装@opentiny/tiny-robot，并能按官方文档引入组件与指令。下面的最小示例对标官方 basic demo：指令挂在聊天容器上，页面里另放浮层，用同一组状态同步。

<script setup lang="ts"> import { ref } from 'vue' import { TrDragOverlay, vDropzone, type FileRejection } from '@opentiny/tiny-robot' const isDragging = ref(false) const targetElement = ref<HTMLElement | null>(null) function handleDraggingChange(dragging: boolean, element: HTMLElement | null) { isDragging.value = dragging targetElement.value = element } function handleDrop(files: File[]) { // 预期：松手且校验通过后拿到 File[]，例如 [photo.png] console.log('accepted', files) } function handleError(rejection: FileRejection) { // 预期：类型 / 大小 / 数量不通过时进入这里 console.error(rejection.code, rejection.message, rejection.files) } </script> <template> <div class="chat-area" v-dropzone="{ accept: 'image/*', multiple: true, onDrop: handleDrop, onError: handleError, onDraggingChange: handleDraggingChange, }" > <!-- 聊天内容 --> </div> <tr-drag-overlay overlay-title="将图片拖到此处完成上传" :overlay-description="['总计最多上传3个图片（每个10MB以内）', '支持图片格式 JPG/JPEG/PNG']" :is-dragging="isDragging" :drag-target="targetElement" /> </template>

对照一下常见写法：

拖photo.png进入容器时，预期：onDraggingChange(true, el)触发，浮层出现；松手且校验通过：onDrop收到文件数组，浮层随false消失。文档把onDrop、onError标为必需——没有拒绝回调时，类型错误会悄悄丢掉，排查时找不到入口。

指令内部用dragCounter处理嵌套子元素的dragenter/dragleave，只有计数回到 0 才清拖拽态。这比「一离开子节点就关浮层」稳，也是拆分后指令层该扛的活。

松手瞬间：photo.png 怎么被收下或拒绝

浮层亮着只说明「正在拖」；决定photo.png能不能进业务的，是指令在drop里跑的校验。文档默认值（以官方属性表为准）：

源码里校验顺序固定，按这个顺序排查更省事：

1. 先看数量：整批超过maxFiles，整批拒绝，错误码file-count-exceeded。
2. 再看类型与大小：按文件逐个过滤；大小超限优先记为file-size-exceeded，否则类型不符为file-type-not-allowed。
3. multiple === false且通过类型/大小的文件多于 1 个：按数量超限处理，提示只允许一个文件。

FileRejection形如{ code, message, files }，code取自DragZoneErrorCode（file-type-not-allowed/file-size-exceeded/file-count-exceeded）。

容易误判的一点：同一次放下，既可能onError，也可能onDrop。例如拖入 3 个文件，其中 2 个符合image/*、1 个是.pdf，指令会对拒绝文件调onError，同时把接受的文件交给onDrop。业务不要假设「进了 Error 就一定没有 Drop」——上传队列以onDrop的File[]为准，用onError提示哪些被挡下。

用同一张photo.png自测三条路径：

• accept: 'image/*'，文件小于 10MB → 应走onDrop。
• 改成accept: '.pdf'再拖同一张图 → 应走onError，file-type-not-allowed。
• 一次拖入超过maxFiles个文件 → 整批file-count-exceeded，不要期待部分成功。

浮层盖在哪、显示什么

到这一步，photo.png还悬在指针上，.chat-area已通过onDraggingChange把自身交给drag-target。浮层不用「父级相对定位」糊一层，而是用目标元素的视口边界算出top/left/width/height，以position: fixed盖住该矩形。容器滚动或偏移时，只要drag-target仍指向该节点，覆盖层跟着边界走。

文案用 props 控制：

• overlay-title：主标题，例如「将图片拖到此处完成上传」。
• overlay-description：string[]，每一项一行；官方 basic demo 用两行分别写数量上限与格式提示，和默认maxFiles=3、maxSize=10MB对齐，避免浮层说「随便拖」而指令其实会拒。

fullscreen默认false。打开后主要切换全屏相关 CSS 变量（内容区内边距、边框宽度等），用来控制覆盖层边框一类展示差异，而不是另起一套拖拽协议。区域拖拽上传一般保持默认；需要整页强调投放区时再打开。

浮层根节点带pointer-events: none——视觉盖住了，事件仍落到下面的 dropzone。这是「纯展示」能成立的前提：浮层若自己抢事件，指令层的drop会丢。

换皮：CSS 变量、overlay 插槽与 disabled

默认浮层不够用时，先问要不要换整块 DOM。多数品牌色、圆角、字重用 CSS 变量就能收口，例如：

:root{--tr-drag-overlay-bg-color:rgba(0,0,0,0.1);--tr-drag-overlay-title-color:#333;--tr-drag-overlay-content-padding:60px;}

全屏模式另有--tr-drag-overlay-content-padding-fullscreen、--tr-drag-overlay-content-border-width-fullscreen等变量，文档有完整列表。变量覆盖优先于重写组件内部 class，升级时更不容易碎。

需要完全自定义视觉时，用overlay插槽替换默认图标与文案——官方 custom-overlay demo 在插槽里放渐变底与「释放鼠标上传图片」提示，同时把accept收紧为.jpg,.jpeg,.png,.gif、multiple: false。插槽换的是「看起来怎样」，校验规则仍由指令参数决定；不要只在插槽文案里写限制，却忘了改accept/maxSize。

上传中或只读态设disabled: true：指令在dragenter/drop等路径直接返回，不会再推拖拽态。比「藏掉浮层但指令还在收文件」干净。

协同数据流：回到 photo.png 的一句话

整条链路是单向的：

1. photo.png进入.chat-area→v-dropzonedragenter→onDraggingChange(true, el)。
2. 你的ref更新 →<tr-drag-overlay>因is-dragging显示，并按drag-target定位。
3. 松手 → 指令清零拖拽态、跑校验 → 接受则onDrop(File[])，拒绝则onError(FileRejection)（同一次仍可能两者都有）。
4. 浮层随is-dragging === false隐藏；业务只消费回调里的文件，自行决定预览或上传。

指令不渲染浮层，浮层不解析dataTransfer。状态只从指令经你的桥接到浮层，没有反向写入——这就是文档里「协同」的含义。

接入自检

照着photo.png+.chat-area勾一遍：

• v-dropzone挂在真正的投放容器上，且传入onDrop、onError、onDraggingChange
• is-dragging与drag-target同时同步，浮层能看见
• accept/maxSize/maxFiles与浮层文案一致
• 拒绝路径能读到rejection.code与rejection.files
• 部分文件合法、部分非法时，同时处理onError与onDrop
• 需要停用时走disabled，而不是只藏浮层
• 业务上传从onDrop的File[]开始，不依赖组件内置对象存储

关于 OpenTiny NEXT

OpenTiny NEXT 是一套企业智能前端开发解决方案，以生成式 UI 和 WebMCP 两大核心技术为基础，对现有传统的 TinyVue 组件库、TinyEngine 低代码引擎等产品进行智能化升级，构建出面向 Agent 应用的前端 NEXT-SDKs、AI Extension、TinyRobot 智能助手、GenUI 等新产品，实现 AI 理解用户意图自主完成任务，加速企业应用的智能化改造。

欢迎加入 OpenTiny 开源社区。添加微信小助手：opentiny-official 一起参与交流前端技术～
OpenTiny 官网：opentiny.design
TinyRobot 代码仓库：github.com/opentiny/tiny-robot（欢迎 star ⭐）
如果你也想要共建，可以进入代码仓库，找到 good first issue 标签，一起参与开源贡献～如果你有任何问题，欢迎在评论区留言交流！