---
title: "FileHandler 扩展"
description: "使用 FileHandler 扩展处理您的 Tiptap 编辑器中的文件拖放和粘贴。点击这里查看如何设置！"
canonical_url: "https://tiptap.zhcndoc.com/editor/extensions/functionality/filehandler"
---

# FileHandler 扩展

使用 FileHandler 扩展处理您的 Tiptap 编辑器中的文件拖放和粘贴。点击这里查看如何设置！

您是否想过将文件拖放或粘贴到编辑器中？我们也有这个需求——所以这里有一个扩展可以实现。

`FileHandler` 扩展允许您轻松处理编辑器中的文件拖放和粘贴。您可以为这两种事件定义自定义处理程序并管理允许的文件类型。

默认情况下，当文件被粘贴或拖放时，该扩展不会显示上传的文件。相反，它会触发一个事件，您可以通过在编辑器中插入一个新的节点来响应该事件。例如，要显示上传的图像文件，请使用 [图像扩展](https://tiptap.zhcndoc.com/editor/extensions/nodes/image.md)。

> **无服务器上传功能:**
>
> 此扩展仅负责处理将文件拖放或粘贴到编辑器中的事件。它不实现服务器端文件上传功能。

> **Interactive demo:** [FileHandler](https://embed.tiptap.dev/preview/Extensions/FileHandler)

## 安装

```bash
npm install @tiptap/extension-file-handler
```

## 设置

### onPaste

当文件粘贴到编辑器中时，将调用的回调函数。您将可以访问编辑器实例和粘贴的文件。

默认值：`undefined`

```js
FileHandler.configure({
  onPaste: (editor, files, htmlContent) => {
    // 对文件做一些操作
    // 并将文件插入到编辑器中
    // 在某些情况下（例如，从其他应用程序复制/粘贴的 gif），您可能不应直接使用该文件
    // 因为文件解析器将只有单个 gif 帧作为 png
    // 在这种情况下，您可以从 htmlContent 中提取 URL 并使用它， 让其他输入规则处理插入
    // 或对粘贴到这里的 htmlContent 做其他任何事情
  },
})
```

### onDrop

当文件被拖放到编辑器中时，将调用的回调函数。您将可以访问编辑器实例、被拖放的文件以及文件被拖放的位置。

默认值：`undefined`

```js
FileHandler.configure({
  onDrop: (editor, files, pos) => {
    // 对文件做一些操作
    // 并将文件插入到编辑器中
  },
})
```

### allowedMimeTypes

此选项控制允许被拖放或粘贴到编辑器中的文件类型。您可以定义 MIME 类型列表或文件扩展名列表。如果未定义 MIME 类型或文件扩展名，则允许所有文件。

默认值：`undefined`

```js
FileHandler.configure({
  allowedMimeTypes: ['image/jpeg', 'image/png', 'image/gif'],
})
```

### consumePasteEvent

当为 `true` 时，如果剪贴板中存在文件，即使旁边还有 HTML 内容，粘贴事件也会被完全消费。这可以防止其他扩展的粘贴规则在同一事件上运行并创建重复内容。

当您的 `onPaste` 回调负责处理文件插入，并且您希望阻止其他扩展处理同一次粘贴时使用此选项（例如，避免文件处理器和图片扩展都尝试处理同一张已粘贴图片而导致重复的图片节点）。

默认值：`false`

```js
FileHandler.configure({
  consumePasteEvent: true,
})
```