---
title: "图片上传节点"
description: "集成一个节点 UI 组件，可以在您的 Tiptap 编辑器中添加图像上传功能。更多内容请参见文档！"
canonical_url: "https://tiptap.zhcndoc.com/ui-components/node-components/image-upload-node"
---

# 图片上传节点

集成一个节点 UI 组件，可以在您的 Tiptap 编辑器中添加图像上传功能。更多内容请参见文档！

一个可以在 Tiptap 编辑器中直接上传图像的节点，提供拖放界面和进度跟踪。

> **Interactive demo:** [image upload node](https://template.tiptap.dev/preview/tiptap-node/image-upload-node)

## 安装

你可以通过 Tiptap CLI 添加该节点组件

```bash
npx @tiptap/cli@latest add image-upload-node
```

## 使用

```tsx
import * as React from 'react'
import { useEditor, EditorContent } from '@tiptap/react'
import { ImageUploadNode } from '@/components/tiptap-node/image-upload-node'
import { Image } from '@tiptap/extension-image'
import { StarterKit } from '@tiptap/starter-kit'
import { MAX_FILE_SIZE, handleImageUpload } from '@/lib/tiptap-utils'

import '@/components/tiptap-node/image-upload-node/image-upload-node.scss'

export default function EditorWithImageUpload() {
  const editor = useEditor({
    extensions: [
      StarterKit,
      Image,
      ImageUploadNode.configure({
        accept: 'image/*',
        maxSize: MAX_FILE_SIZE,
        limit: 3,
        upload: handleImageUpload,
        onError: (error) => console.error('上传失败:', error),
      }),
    ],
    content: '<p>尝试上传图像！</p>',
  })

  React.useEffect(() => {
    if (!editor) {
      return
    }

    editor.chain().focus().setImageUploadNode().run()
  }, [editor])

  return <EditorContent editor={editor} />
}
```

## 属性

| 名称        | 类型                                                                                  | 默认值        | 描述                      |
| --------- | ----------------------------------------------------------------------------------- | ---------- | ----------------------- |
| accept    | string                                                                              | 'image/\*' | 可接受的上传文件类型              |
| limit     | number                                                                              | 1          | 可上传文件的最大数量              |
| maxSize   | number                                                                              | 0          | 文件的最大大小（以字节为单位，0 表示无限制） |
| upload    | `(file: File, onProgress?: Function, abortSignal?: AbortSignal) => Promise<string>` | undefined  | 处理上传过程的函数               |
| onError   | (error: Error) => void                                                              | undefined  | 上传错误的回调                 |
| onSuccess | (url: string) => void                                                               | undefined  | 上传成功后的回调                |

## 特性

- 拖放文件上传
- 文件大小验证
- 上传进度跟踪
- 文件类型过滤
- 可中止的上传
- 上传过程中的视觉反馈
- 上传后与图像节点的无缝替换

## 需求

使用的参考组件

- `close-icon`（图标）

开源功能

- `@tiptap/react`
- [`@tiptap/extension-image`](https://tiptap.zhcndoc.com/editor/extensions/nodes/image.md)（推荐以实现完整功能）