27. 拖放与文件处理：在窗口里接收文件

本节目标

理解渲染进程里的 HTML5 拖放事件模型。
用 dragover / drop 接收拖入窗口的文件。
用浏览器 File API 读取文本与图像内容。
弄清沙箱下为什么拿不到真实路径。
需要路径时，经 IPC 让主进程用对话框等方式提供。

27-1 拖放的基本模型

在 Electron 的渲染进程里，文件拖放本质就是网页标准的拖放 API。用户把系统文件拖到窗口上，浏览器会派发一系列拖放事件。最关键的两个是 dragover 与 drop。

dragover 在文件悬停在目标上方时持续触发。要允许放下，必须在这个事件里调用 event.preventDefault()，否则浏览器会拒绝接收。

drop 在用户松手放下时触发，被拖的文件就挂在 event.dataTransfer.files 上。同样需要 preventDefault() 来阻止浏览器用默认方式打开文件。

<!-- index.html -->
<div id="dropZone" style="width:400px;height:200px;border:2px dashed #888;">
  把文件拖到这里
</div>
<script src="renderer.js"></script>

// 渲染进程 renderer.js
const zone = document.getElementById('dropZone')

zone.addEventListener('dragover', (event) => {
  // 必须阻止默认，否则不允许放下
  event.preventDefault()
})

zone.addEventListener('drop', (event) => {
  event.preventDefault()
  const files = event.dataTransfer.files
  console.log('拖入文件数：', files.length)
})

27-2 读取文本文件内容

dataTransfer.files 是一个 FileList，每一项都是标准 File 对象。读取内容不需要 Node.js，用浏览器自带的 File API 即可，这在沙箱渲染进程里也能正常工作。

文本文件可用 file.text()（返回 Promise）拿到字符串；老写法是用 FileReader 读 readAsText。

// 渲染进程 renderer.js
zone.addEventListener('drop', async (event) => {
  event.preventDefault()
  const file = event.dataTransfer.files[0]
  if (!file) return

  const text = await file.text()
  document.getElementById('output').textContent = text
})

二进制文件则用 file.arrayBuffer() 取出 ArrayBuffer，再按格式解析。比如读取一个 JSON 配置文件：

// 渲染进程 renderer.js
const text = await file.text()
const config = JSON.parse(text)
console.log('配置项：', config)

27-3 读取并预览图像

拖入图片时，可用 URL.createObjectURL(file) 生成一个临时地址，直接赋给 <img src> 做预览，无需先把图片读到主进程。

// 渲染进程 renderer.js
zone.addEventListener('drop', (event) => {
  event.preventDefault()
  const file = event.dataTransfer.files[0]
  if (!file || !file.type.startsWith('image/')) return

  const url = URL.createObjectURL(file)
  document.getElementById('preview').src = url
})

用完临时地址后，建议调用 URL.revokeObjectURL(url) 释放，避免内存堆积。如果你要把这张图复制到系统剪贴板，就需借助 nativeImage（见第 25 章），此时应通过 preload 暴露的安全方法，把图片数据传回主进程处理。

27-4 为什么沙箱下拿不到真实路径

很多新手会试图直接读 file.path，期望得到磁盘上的绝对路径。但在 Electron 32.0.0 起，Web File 对象上非标准的 path 属性已被彻底移除，取而代之的是 webUtils.getPathForFile(file)。也就是说，在 v43.2.0 的任何渲染进程里，file.path 都不再存在，它并不是「沙箱专属」的行为差异。

本教程的安全默认是 sandbox: true + contextIsolation: true。即便不开沙箱，渲染进程里的 File 也不携带系统路径，这是 Electron 从 32 版起统一做的安全收敛。

正确思路是：内容是内容，路径是路径。读取内容用上面的 File API；真正需要「文件路径」时，可在 preload 里用 webUtils.getPathForFile(file) 取得（它只在 preload 可用，且沙箱 preload 的模块子集包含 webUtils），再把路径经 IPC 回传给渲染进程：

// 预加载脚本 preload.js
const { contextBridge, ipcRenderer, webUtils } = require('electron')

contextBridge.exposeInMainWorld('fileApi', {
  getPath: (file) => webUtils.getPathForFile(file)
})

// 渲染进程 renderer.js
const path = window.fileApi.getPath(file)
console.log('真实路径：', path)

如果你只需要在用户「先拖入、再处理」的流程里拿到路径，也可以走上一节的主进程对话框路线，二者并不冲突。

27-5 让主进程提供文件路径

需要真实路径的典型场景，是把文件交给只在主进程可用的 Node API 处理。做法是用 ipcRenderer.invoke 请求主进程，由主进程通过 dialog.showOpenDialog 或已知的业务路径返回。

// 预加载脚本 preload.js
const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld('fileApi', {
  // 请求主进程挑选文件，返回路径数组
  pickFile: () => ipcRenderer.invoke('pick-file')
})

// 主进程 main.js
const { ipcMain, dialog } = require('electron/main')

ipcMain.handle('pick-file', async () => {
  const result = await dialog.showOpenDialog({
    properties: ['openFile', 'multiSelections']
  })
  if (result.canceled) return []
  return result.filePaths
})

// 渲染进程 renderer.js
const paths = await window.fileApi.pickFile()
console.log('选中文件路径：', paths)

如果业务上路径是「先拖入、再处理」，更稳妥的方案是：拖入后用 File API 读取内容，把内容通过 IPC 发到主进程处理，而不是执着于获取路径。这样既不破坏沙箱，也能完成绝大多数文件处理需求。

27-6 从应用拖出文件

除了接收文件，Electron 还能让应用向外拖出文件，这由主进程用 webContents.startDrag 触发。它接受一个包含文件路径与图标的数据对象，用户即可从窗口把文件拖到资源管理器。

// 主进程 main.js
const { BrowserWindow } = require('electron/main')

const win = BrowserWindow.getFocusedWindow()
win.webContents.startDrag({
  file: '/Users/me/docs/report.pdf',
  icon: '/Users/me/icons/pdf.png'
})

注意 startDrag 必须由用户手势（如点击、拖拽动作）驱动，不能在无交互时自动调用。图标在 Windows 上作用于拖拽时的缩略图，macOS 上则按需提供。

27-7 处理多个文件与状态反馈

真实场景里用户往往一次拖入多个文件。遍历 dataTransfer.files 即可逐个处理，配合文件类型判断做筛选。比如只接受图片，就跳过非图像项。

// 渲染进程 renderer.js
zone.addEventListener('drop', async (event) => {
  event.preventDefault()
  const files = event.dataTransfer.files
  const images = []

  for (const file of files) {
    if (!file.type.startsWith('image/')) continue
    const url = URL.createObjectURL(file)
    images.push(url)
  }

  console.log('收到图片数量：', images.length)
})

为了体验更好，可以在 dragenter / dragleave 上切换拖放区的样式，让用户清楚当前是否处于可放下状态。注意 dragleave 在子元素间也会频繁触发，建议用计数器或 relatedTarget 判断真正离开区域时再取消高亮。

另外，拖放区的默认样式变化只是视觉反馈，底层逻辑始终要回到 drop 里 preventDefault。只改样式而不阻止默认行为，松手时浏览器仍会按自己的方式处理文件。

对于二进制文件，用 file.arrayBuffer() 取出底层字节，再交给解析逻辑。例如读取一张图片的像素前，可先用 file.type 判断格式，避免把非图像文件误送进图像解析器导致崩溃。读取大文件时，建议配合 File.slice 做分片，避免一次性占用过多内存。

需要重复强调：这些读取都在渲染进程用 Web 标准 API 完成，不依赖 Node，因此在沙箱下完全可用。真正需要「文件路径」这种系统信息时，才走上一节讲的主进程 IPC 路线。

把「拖入后处理」做成完整闭环时，建议给用户明确的反馈。例如拖入后显示文件名列表与大小，处理成功显示绿色对勾，失败则给出具体原因。这样用户能确认应用确实收到了文件，而不是对着一个静止的拖放区疑惑。

最后注意一个边界情况：用户拖入的可能是文件夹而非文件，也可能是超大文件。File 对象本身不区分文件夹，需要结合后续读取行为判断；超大文件则应提示大小或采用分片，避免界面卡顿。把这些异常分支考虑进去，文件处理才足够稳健。

常见误区

不要把读取文件内容理解为「必须用 Node 的 fs」。沙箱渲染进程没有 fs，但浏览器 File API 已足够读文本与图像，优先用它。

不要依赖 file.path 获取拖入文件的真实路径。该属性自 Electron 32.0.0 起已从所有渲染进程移除，强行读取只会得到 undefined。需要真实路径时，改用 preload 里的 webUtils.getPathForFile(file)，再经 IPC 回传给渲染进程。

不要把拖放区域设得过大却不阻止冒泡。若父元素也监听了 drop 且未 preventDefault，可能出现重复处理或浏览器跳转，记得在目标节点上正确阻止默认行为。